elision.lyx

#LyX 2.0 created this file. For more info see http://www.lyx.org/
\lyxformat 413
\begin_document
\begin_header
\textclass amsbook
\begin_preamble
%%\usepackage{minted}
\usepackage{tipa}
\definecolor{shadecolor}{rgb}{0.8,0.8,1}
\sloppypar
%\usepackage{nameref}
\usepackage{fancybox}
\newenvironment{elision}{%
\VerbatimEnvironment
\begin{lstlisting}%
}{%
\end{lstlisting}%
}
\definecolor{listing}{RGB}{224,224,224}
\end_preamble
\use_default_options true
\begin_modules
theorems-ams
eqs-within-sections
figs-within-sections
\end_modules
\maintain_unincluded_children false
\language english
\language_package default
\inputencoding auto
\fontencoding global
\font_roman default
\font_sans default
\font_typewriter default
\font_default_family default
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100

\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\paperfontsize 11
\spacing single
\use_hyperref false
\papersize default
\use_geometry true
\use_amsmath 1
\use_esint 1
\use_mhchem 1
\use_mathdots 1
\cite_engine basic
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\use_refstyle 1
\boxbgcolor #3ebcbc
\index Index
\shortcut idx
\color #008000
\end_index
\leftmargin 1in
\topmargin 1in
\rightmargin 1in
\bottommargin 1in
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\paragraph_indentation default
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\listings_params "backgroundcolor={\color{listing}},basewidth={.5em},basicstyle={\ttfamily\small},columns=fixed,commentstyle={\color{blue}\emph},language=Java,morecomment={[l]{e>}},morecomment={[l]{q>}},morecomment={[l]{\ >}},numbers=none"
\tracking_changes false
\output_changes false
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
\end_header

\begin_body

\begin_layout Title
Elision User Guide
\end_layout

\begin_layout Dedicatory
Version @VERSION@ Build @BUILD@
\end_layout

\begin_layout Standard

\series bold
\shape italic
\size larger
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
makebox[0pt][r]{nominatim}
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Linguistically, an 
\emph on
elision
\emph default
 (
\begin_inset ERT
status open

\begin_layout Plain Layout

i'liZH
\backslash
textipa{@}n
\end_layout

\end_inset

) is the omission of sounds from an utterance to create a result that is
 (typically) easier to pronounce.
 Contractions are examples of elisions.
 Elision can also refer to omissions in books and films.
 Finally, it may mean the process of joining or merging together abstract
 ideas.
\end_layout

\begin_layout Standard
\begin_inset CommandInset toc
LatexCommand tableofcontents

\end_inset


\end_layout

\begin_layout Standard
Elision is distributed under the following modified BSD 
\begin_inset Quotes eld
\end_inset

two clause
\begin_inset Quotes erd
\end_inset

 license.
\end_layout

\begin_layout LyX-Code
      _ _     _
\end_layout

\begin_layout LyX-Code
  ___| (_)___(_) ___  _ __
\end_layout

\begin_layout LyX-Code
 / _ 
\backslash
 | / __| |/ _ 
\backslash
| '_ 
\backslash

\end_layout

\begin_layout LyX-Code
|  __/ | 
\backslash
__ 
\backslash
 | (_) | | | |
\end_layout

\begin_layout LyX-Code
 
\backslash
___|_|_|___/_|
\backslash
___/|_| |_|
\end_layout

\begin_layout LyX-Code
The Elision Term Rewriter
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code
Copyright (c) 2012 by UT-Battelle, LLC.
\end_layout

\begin_layout LyX-Code
All rights reserved.
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code
Redistribution and use in source and binary forms, with or without
\end_layout

\begin_layout LyX-Code
modification, are permitted provided that the following conditions are met:
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code
1.
 Redistributions of source code must retain the above copyright notice,
 this
\end_layout

\begin_layout LyX-Code
   list of conditions and the following disclaimer.
\end_layout

\begin_layout LyX-Code
2.
 Redistributions in binary form must reproduce the above copyright notice,
\end_layout

\begin_layout LyX-Code
   this list of conditions and the following disclaimer in the documentation
\end_layout

\begin_layout LyX-Code
   and/or other materials provided with the distribution.
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code
Collection of administrative costs for redistribution of the source code
 or
\end_layout

\begin_layout LyX-Code
binary form is allowed.
 However, collection of a royalty or other fee in excess
\end_layout

\begin_layout LyX-Code
of good faith amount for cost recovery for such redistribution is prohibited.
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
 IS"
\end_layout

\begin_layout LyX-Code
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
\end_layout

\begin_layout LyX-Code
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
\end_layout

\begin_layout LyX-Code
ARE DISCLAIMED.
 IN NO EVENT SHALL THE COPYRIGHT HOLDER, THE DOE, OR
\end_layout

\begin_layout LyX-Code
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
\end_layout

\begin_layout LyX-Code
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
\end_layout

\begin_layout LyX-Code
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
\end_layout

\begin_layout LyX-Code
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
\end_layout

\begin_layout LyX-Code
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
\end_layout

\begin_layout LyX-Code
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
\end_layout

\begin_layout LyX-Code
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\end_layout

\begin_layout Chapter
Installation
\end_layout

\begin_layout Standard
This chapter explains how to build the Elision rewriter.
 Information about the rewriter can be obtained by visiting 
\begin_inset Flex URL
status open

\begin_layout Plain Layout

http://elision.github.com/
\end_layout

\end_inset

.
 This page contains a frequently updated version, along with documentation
 links and a link to Elision's source.
\end_layout

\begin_layout Standard
Elision contains Parboiled, a parser expression grammar (PEG) library.
 See 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

https://github.com/sirthias/parboiled/wiki
\end_layout

\end_inset

 for details, including the license agreement.
 The Elision REPL uses JLine, a Java library for handling console input.
 See 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

https://github.com/jline/jline2
\end_layout

\end_inset

 for details, including the license agreement.
 Note that Elision actually uses the modified version of JLine built for
 the Scala REPL and distributed with Scala.
\end_layout

\begin_layout Section
Running
\end_layout

\begin_layout Standard
If you only want to run the Elision REPL, you have two choices.
\end_layout

\begin_layout Itemize
Make sure the Java 1.6 runtime is installed and download the large 
\family typewriter
elision-all.jar
\family default
.
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
Actually the filename will contain the build information, and will probably
 resemble 
\family typewriter
elision-all-20120601.jar
\family default
.
\end_layout

\end_inset

 Run Elision with the command 
\family typewriter
java -jar elision-all.jar
\family default
.
 In some envrionments you can just double-click the jar file.
\end_layout

\begin_layout Itemize
Make sure both Java 1.6 and the Scala 2.9.1 (or later) distribution are installed.
 Download the (much smaller) 
\family typewriter
elision.jar
\family default
 and run Elision with the command 
\family typewriter
scala elision.jar
\family default
.
\end_layout

\begin_layout Section
Building
\end_layout

\begin_layout Standard
Elision requires Scala 2.9 or later to build.
 Be careful with later versions of Scala as the language is still changing
 quite a bit.
 Java 6 or later and Apache Ant 1.8 or later are also prerequisites.
\end_layout

\begin_layout Enumerate
Install the Java 6 (or later) SDK.
 Visit 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://java.oracle.com
\end_layout

\end_inset

 to download the correct version for your platform.
\end_layout

\begin_layout Enumerate
Install Scala 2.9.1 (or later).
 Visit 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://www.scala-lang.org
\end_layout

\end_inset

 to download the Scala distribution.
\end_layout

\begin_layout Enumerate
Set the environment variable 
\family typewriter
SCALA_HOME
\family default
 to point to the root folder of your Scala installation (the folder that
 contains the 
\family typewriter
bin
\family default
 and 
\family typewriter
lib
\family default
 folders).
\end_layout

\begin_deeper
\begin_layout Enumerate
On Windows platforms you should edit the environment variable settings under
 System, and add 
\family typewriter
%SCALA_HOME%
\backslash
bin
\family default
 to the 
\family typewriter
Path
\family default
 environment variable.
 Open 
\family sans
System Properties
\family default
 and click 
\family sans
Advanced system settings
\family default
.
 Then on the 
\family sans
Advanced
\family default
 tab click 
\family sans
Environment Variables...

\family default
 Under 
\family sans
System Variables
\family default
 click 
\family sans
New...
\end_layout

\begin_deeper
\begin_layout Standard
\begin_inset Tabular
<lyxtabular version="3" rows="2" columns="2">
<features tabularvalignment="middle">
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family sans
Variable name
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family sans
Variable value
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
SCALA_HOME
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
C:
\backslash
scala
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Standard
You should replace 
\family typewriter
C:
\backslash
scala
\family default
 with the directory where you installed Scala.
 Next edit the value for 
\family typewriter
Path
\family default
 
\emph on
carefully
\emph default
 to add 
\family typewriter
;%SCALA_HOME%
\backslash
bin
\family default
 on the end.
\end_layout

\end_deeper
\begin_layout Enumerate
On MacOS X platforms you can edit the environment plist 
\emph on
or
\emph default
 follow the directions for UNIX below.
 You can do this from the Terminal prompt with 
\family typewriter
open ~/.MacOSX/environment.plist
\family default
.
 This will open the environment settings in the 
\family sans
Property List Editor
\family default
.
 Add a new 
\family sans
Item
\family default
 at the top level.
\end_layout

\begin_deeper
\begin_layout Standard
\begin_inset Tabular
<lyxtabular version="3" rows="2" columns="3">
<features tabularvalignment="middle">
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family sans
Key
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family sans
Type
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family sans
Value
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
SCALA_HOME
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
String
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
/usr/local/scala
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Standard
You should replace 
\family typewriter
/usr/local/scala
\family default
 with the directory where you installed Scala.
 Next edit the value for 
\family typewriter
PATH
\family default
 
\emph on
carefully
\emph default
 to add 
\family typewriter
:$SCALA_HOME/bin
\family default
 on the end.
\end_layout

\end_deeper
\begin_layout Enumerate
On modern UNIX systems (including MacOS X) and most Linux systems you can
 create a 
\family typewriter
/etc/profile.d/scala.sh
\family default
 file with the following content:
\end_layout

\begin_deeper
\begin_layout LyX-Code
# Add Scala
\begin_inset Newline newline
\end_inset

export SCALA_HOME=/usr/local/scala
\begin_inset Newline newline
\end_inset

PATH=${PATH}:$SCALA_HOME/bin
\end_layout

\begin_layout Standard
You should replace 
\family typewriter
/usr/local/scala
\family default
 with the directory where you installed Scala.
\end_layout

\end_deeper
\end_deeper
\begin_layout Enumerate
(Optional) It is recommended to get the Scala developer documentation package.
 After you have installed Scala, run the following command at the prompt.
 If you have installed Scala in a folder owned by root on Linux or UNIX,
 you will need to precede the command with 
\family typewriter
sudo
\family default
.
\begin_inset Newline newline
\end_inset


\family typewriter
sbaz install scala-devel-docs
\end_layout

\begin_layout Enumerate
Install Apache Ant 1.8 (or later).
 Visit 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://ant.apache.org
\end_layout

\end_inset

 to download the Ant distribution.
\end_layout

\begin_layout Enumerate
(Optional) If you want to use Eclipse, you should install Eclipse Indigo
 (or later).
\end_layout

\begin_layout Enumerate
To build the Elision jar file, 
\family typewriter
cd
\family default
 to the root folder of the Elision distribution and run the command 
\family typewriter
ant
\family default
.
 This will build the jar file.
\end_layout

\begin_layout Enumerate
(Optional) If you want to build the API documentation, then run the command
 
\family typewriter
ant docs
\family default
.
 To build both the jar files and documentation, use 
\family typewriter
ant all
\family default
.
 To see what other targets are available, use 
\family typewriter
ant -p
\family default
.
\end_layout

\begin_layout Section
REPL
\end_layout

\begin_layout Standard
Elision comes with a read, evaluate, print loop interpreter (a REPL).
 You can start it in any of the following ways.
\end_layout

\begin_layout Itemize
Use the 
\family typewriter
elision.sh
\family default
 script found in the root folder of the Elision distribution.
 This starts the REPL using the compiled class files in the 
\family typewriter
bin
\family default
 folder, and is the best way to run it if you are using a continuous build
 system such as Eclipse.
 If you try to run the REPL this way while Eclipse is compiling, you will
 get missing class file errors.
 Just wait for Eclipse to finish compiling.
\end_layout

\begin_layout Itemize
To run the REPL from the jar file, execute the command 
\family typewriter
scala elision.jar
\family default
.
 You must have built the jar file to use this method, and must update it
 each time you make changes.
\end_layout

\begin_layout Itemize
To start the REPL from inside a program, invoke the 
\family typewriter
ornl.elision.repl.ReplMain.run()
\family default
 method.
\end_layout

\begin_layout Standard
To exit from the REPL use 
\family typewriter
:quit
\family default
.
 To get help use 
\family typewriter
help()
\family default
.
 The REPL is the subject of 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Interacting-with-the"

\end_inset

.
\end_layout

\begin_layout Section
Scala with Emacs, Notepad-Plus, and Others
\end_layout

\begin_layout Standard
Most editors now come with a Scala mode installed.
 In case yours does not, you should look in the Scala distribution under
 
\family typewriter
misc/scala-tool-support
\family default
.
 We will provide some instructions for Emacs here.
\end_layout

\begin_layout Standard
The Emacs mode works for Emacs 21.1or later, and does not work on XEmacs.
 Things change; consult the 
\family typewriter
README
\family default
 file in the folder for current details.
 It is suggested you leave these files in place so they get magically updated
 when the next version of Scala is installed.
\end_layout

\begin_layout Standard
In your Emacs startup file (typically 
\family typewriter
~/.emacs
\family default
 on Linux or UNIX) add the following two lines.
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=Lisp"
inline false
status open

\begin_layout Plain Layout

(add-to-list 'load-path
\end_layout

\begin_layout Plain Layout

  "/usr/local/scala/misc/scala-tool-support/emacs")
\end_layout

\begin_layout Plain Layout

(require 'scala-mode-auto)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Adjust the second line as necessary to point to your Scala installation.
 Now restart Emacs, and you should get the Scala mode when you open a file
 ending with 
\family typewriter
.scala
\family default
.
 You can compile the 
\family typewriter
.el
\family default
 files to 
\family typewriter
.elc
\family default
 files using the provided 
\family typewriter
Makefile
\family default
, but be sure to run 
\family typewriter
make
\family default
 each time you update.
\end_layout

\begin_layout Section
Scala with Eclipse
\end_layout

\begin_layout Standard
The root folder of the Elision distribution contains an Eclipse project.
 Before you attempt to import it into Eclipse you should do the following.
\end_layout

\begin_layout Itemize
Install the 
\series bold
Scala IDE
\series default
.
 At present the version of the Scala IDE for Scala 2.9 can be found at the
 update site 
\begin_inset CommandInset href
LatexCommand href
target "http://download.scala-ide.org/releases-29/stable/site"

\end_inset

.
 Visit 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://scala-ide.org
\end_layout

\end_inset

 for the latest version, documentation, etc.
\end_layout

\begin_layout Standard
That is all that is required.
 You may optionally install the following helpful plugins.
\end_layout

\begin_layout Itemize

\series bold
ShellEd
\series default
 is an excellent editor for working with shell scripts, but at present it
 only works with Eclipse Indigo.
 You can find out more at 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://sourceforge.net/apps/trac/shelled
\end_layout

\end_inset

.
 To install ShellEd you need to install components from the Linux Tools.
 The update site is 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://download.eclipse.org/technology/linuxtools/update
\end_layout

\end_inset

.
 Add this update site first, but do not install anything.
 The update site for ShellEd is 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

https://downloads.sourceforge.net/project/shelled/shelled/ShellEd%202.0.1/update
\end_layout

\end_inset

.
 After adding the update site for the Linux Tools, add this update site
 and then install ShellEd; it will resolve the dependencies and get the
 components from the Linux Tools that are actually required.
\end_layout

\begin_layout Itemize

\series bold
Copyright Wizard
\series default
 can be used to automatically and quickly update the copyrights on all files
 and to make sure all new files have the correct copyright information.
 The distribution includes a configuration file for Copyright Wizard that
 will be automatically discovered if you install Copyright Wizard.
 Find out more at 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://www.wdev91.com/?p=cpw
\end_layout

\end_inset

.
 The update site is 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://www.wdev91.com/update
\end_layout

\end_inset

.
\end_layout

\begin_layout Standard
Once you have installed the Scala IDE plugin, do the following.
\end_layout

\begin_layout Enumerate
Unpack the Elision distribution into an Eclipse workspace, or create a 
\family typewriter
workspace
\family default
 folder and place the 
\family typewriter
Elision
\family default
 folder in it.
\end_layout

\begin_layout Enumerate
Start Eclipse.
 You will probably be prompted to run the Scala Setup Diagnostics.
 Click Yes to run them.
 Make sure you open Eclipse in the correct workspace containing the Elision
 distribution.
\end_layout

\begin_layout Enumerate
Go to the workbench.
 Right-click in the package explorer and choose New and then Project.
 In the New Project wizard expand Scala Wizards and select Scala Project.
 Click Next.
\end_layout

\begin_layout Enumerate
In the New Scala Project dialog enter Elision as the project name.
 If you have done everything correctly you should see a note at the bottom
 of the dialog telling you the wizard is about to automatically configure
 the project based on the existing source.
 This is what you want, so click Finish.
\end_layout

\begin_layout Enumerate
You may be asked if you want to switch to the Scala perspective.
 You do, so click Yes.
\end_layout

\begin_layout Standard
At this point Elision should automatically build, and you are ready to start
 working with the code or running the REPL using 
\family typewriter
repl.sh
\family default
.
\end_layout

\begin_layout Section
Scala Code
\end_layout

\begin_layout Standard
Elision is written in Scala, and provides a Scala API.
 Discussions of the Scala API are highlighted in blue.
\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
Elision's classes live in packages under 
\family typewriter
ornl.elision
\family default
.
 Throughout this document packages, classes, objects, traits, etc., will
 be discussed in reference to this top-level package.
 Thus 
\family typewriter
core.BasicAtom
\family default
 refers to the fully-qualified class name (FQCN) 
\family typewriter
ornl.elision.core.BasicAtom
\family default
.
\end_layout

\end_inset


\end_layout

\begin_layout Chapter
\begin_inset CommandInset label
LatexCommand label
name "chap:Interacting-with-the"

\end_inset

Interacting with the REPL
\end_layout

\begin_layout Standard
The REPL is Elision's read, evaluate, print loop.
 It provides a way to interact directly with the rewriter.
\end_layout

\begin_layout Section
Starting the REPL
\end_layout

\begin_layout Standard
You can start the REPL in any of the following ways.
\end_layout

\begin_layout Itemize
Use the 
\family typewriter
elision.sh
\family default
 script found in the root folder of the Elision distribution.
 This starts the REPL using the compiled class files in the 
\family typewriter
bin
\family default
 folder, and is the best way to run it if you are using a continuous build
 system such as Eclipse.
 If you try to run the REPL this way while Eclipse is compiling, you will
 get missing class file errors.
 Just wait for Eclipse to finish compiling.
\end_layout

\begin_layout Itemize
To run the REPL from the jar file, execute the command 
\family typewriter
scala elision.jar
\family default
.
 You must have built the jar file to use this method, and must update it
 each time you make changes.
\end_layout

\begin_layout Itemize
To start the REPL from inside a program, invoke the 
\family typewriter
ornl.elision.repl.ReplMain.run()
\family default
 method.
 This is useful from the Scala prompt, assuming you have the correct 
\family typewriter
CLASSPATH
\family default
.
 You can use the 
\family typewriter
run.sh
\family default
 script found in the Elision root to start Scala with the correct 
\family typewriter
CLASSPATH
\family default
.
\end_layout

\begin_layout Standard
All of these methods will display the Elision banner and present you with
 the REPL prompt 
\family typewriter
e>
\family default
.
 You can enter text to be evaluated as an Elision atom (described in later
 sections), interact with the history (using the up and down arrow keys),
 or edit the current line.
 Pressing Enter submits the line to the Elision parser for evaluation.
\end_layout

\begin_layout Standard
The most useful commands to know immediately are 
\family typewriter
help()
\family default
 (to get help) and 
\family typewriter
:quit
\family default
 (to quit).
\end_layout

\begin_layout Standard
The REPL commands (with the exception of 
\family typewriter
:quit
\family default
 and history recall) are actually Elision operators (see 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Operators"

\end_inset

).
 As such you must follow them with parentheses, otherwise the Elision REPL
 will interpret them as symbols.
 Try 
\family typewriter
history
\family default
 and then try 
\family typewriter
history()
\family default
.
\begin_inset Foot
status open

\begin_layout Plain Layout
It is permissible to put spaces between the operator name and the opening
 parenthesis: 
\family typewriter
history ()
\family default
.
 This can lead to trouble.
 Suppose you want to have the symbol 
\family typewriter
fred
\family default
 followed by a parenthesized expression: 
\family typewriter
fred (5).$x
\family default
.
 Here the parentheses are necessary to prevent the parser from interpreting
 the dot as a decimal point.
 Unfortunately this will not work the way you might expect.
 The system will parse this as 
\family typewriter
(fred(5)).$x
\family default
.
 To prevent this, put parentheses around 
\family typewriter
fred
\family default
: 
\family typewriter
(fred) (5).$x
\family default
.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The REPL reads zero or more atoms per line, evaluates them, and displays
 the output.
 Several atoms can be present on a single line; in that case the REPL displays
 each one.
\end_layout

\begin_layout Standard
Atoms can span multiple lines.
 If a parenthesis, brace, bracket, or verbatim block
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
A verbatim block is text within triple double quotation marks: 
\family typewriter
"""
\family default
...
\family typewriter
"""
\family default
.
 No escapes are interpreted, and spaces and newlines are maintained.
 Thus the verbatim block:
\end_layout

\begin_layout LyX-Code
"""This is the first line,
\end_layout

\begin_layout LyX-Code
  and this is the second.
\end_layout

\begin_layout LyX-Code
Escapes and quotation marks are preserved.
\end_layout

\begin_layout LyX-Code
"See 
\backslash
n?" he said."""
\end_layout

\begin_layout Plain Layout
Denotes the following string.
\end_layout

\begin_layout LyX-Code
"This is the first line,
\backslash
n  and this is the second.
\backslash
nEscapes and quotation marks
\end_layout

\begin_layout LyX-Code
are preserved.
\backslash
"See 
\backslash

\backslash
n?
\backslash
" he said."
\end_layout

\end_inset

 is open at the end of the line, then the REPL will prompt for additional
 input with the prompt 
\family typewriter
>
\family default
.
 The newlines are converted to spaces, except with verbatim blocks.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> { operator
\end_layout

\begin_layout Plain Layout

 >   #name=set
\end_layout

\begin_layout Plain Layout

 >   #params=%ACI($P: BOOLEAN, $Q: BOOLEAN)
\end_layout

\begin_layout Plain Layout

 >   #type=BOOLEAN
\end_layout

\begin_layout Plain Layout

 > }
\end_layout

\begin_layout Plain Layout

$_repl0 = {: operator:SYMBOL { binds name -> set:SYMBOL
\end_layout

\begin_layout Plain Layout

  params -> %ACI($P:BOOLEAN, $Q:BOOLEAN) type -> BOOLEAN } :}
\end_layout

\begin_layout Plain Layout

e> ("Fred".
\end_layout

\begin_layout Plain Layout

 > " Flintstone")
\end_layout

\begin_layout Plain Layout

$_repl1 = "Fred Flintstone"
\end_layout

\end_inset


\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout Section
History
\end_layout

\begin_layout Standard
The Elision REPL saves a persistent history from session to session.
 This history can be viewed with the 
\family typewriter
history()
\family default
 command.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> history()
\end_layout

\begin_layout Plain Layout

0: // New Session: Fri Jun 08 12:12:59 EDT 2012
\end_layout

\begin_layout Plain Layout

1: // Running: 0.1, build 201206081150
\end_layout

\begin_layout Plain Layout

2: {operator #name=test #params=%($x:INTEGER) #type=INTEGER}
\end_layout

\begin_layout Plain Layout

3: {rule add($x,neg($x)) -> 0}
\end_layout

\begin_layout Plain Layout

4: add(21,17,$x)
\end_layout

\begin_layout Plain Layout

5: history()
\end_layout

\begin_layout Plain Layout

Persistent history is found in: /home/userguy/.elision
\end_layout

\end_inset


\end_layout

\begin_layout Standard
It is possible to recall any prior history element by entering the history
 index after an exclamation mark.
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> !4
\end_layout

\begin_layout Plain Layout

add(21,17,$x)
\end_layout

\begin_layout Plain Layout

$_repl14 = add($x, 38)
\end_layout

\begin_layout Plain Layout

e> bind($x, 2)
\end_layout

\begin_layout Plain Layout

Bound $x
\end_layout

\begin_layout Plain Layout

e> !4
\end_layout

\begin_layout Plain Layout

add(21,17,$x)
\end_layout

\begin_layout Plain Layout

$_repl15 = 40
\end_layout

\begin_layout Plain Layout

e> history()
\end_layout

\begin_layout Plain Layout

0: // New Session: Fri Jun 08 12:12:59 EDT 2012
\end_layout

\begin_layout Plain Layout

1: // Running: 0.1, build 201206081150
\end_layout

\begin_layout Plain Layout

2: {operator #name=test #params=%($x:INTEGER) #type=INTEGER}
\end_layout

\begin_layout Plain Layout

3: {rule add($x,neg($x)) -> 0}
\end_layout

\begin_layout Plain Layout

4: add(21,17,$x)
\end_layout

\begin_layout Plain Layout

5: history()
\end_layout

\begin_layout Plain Layout

6: add(21,17,$x)
\end_layout

\begin_layout Plain Layout

7: bind($x, 2)
\end_layout

\begin_layout Plain Layout

8: add(21,17,$x)
\end_layout

\begin_layout Plain Layout

9: history()
\end_layout

\begin_layout Plain Layout

Persistent history is found in: /home/userguy/.elision
\end_layout

\end_inset


\end_layout

\begin_layout Section
Properties
\end_layout

\begin_layout Standard
The operation of the REPL, and of Elision itself, is configurable using
 
\emph on
properties
\emph default
.
 To see all properties defined in the current system, use the command 
\family typewriter
listprops()
\family default
.
 This lists each property name, gives a short description, and gives the
 
\emph on
current
\emph default
 value of the property in parentheses.
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> listprops()
\end_layout

\begin_layout Plain Layout

applybinds .............
 Rewrite each atom with the
\end_layout

\begin_layout Plain Layout

                         context's bindings.
  (true)
\end_layout

\begin_layout Plain Layout

autoop .................
 If the current result is an
\end_layout

\begin_layout Plain Layout

                         operator, automatically declare it
\end_layout

\begin_layout Plain Layout

                         in the operator library.
  (true)
\end_layout

\begin_layout Plain Layout

autorewrite ............
 Automatically apply rules in the
\end_layout

\begin_layout Plain Layout

                         active rulesets to each atomas it
\end_layout

\begin_layout Plain Layout

                         is evaluated.
  (true)
\end_layout

\begin_layout Plain Layout

autorule ...............
 If the current atom is a rewrite
\end_layout

\begin_layout Plain Layout

                         rule, automatically declare it in
\end_layout

\begin_layout Plain Layout

                         the rule library.
  (true)
\end_layout

\begin_layout Plain Layout

...
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To set the value of a property, use 
\family typewriter
setprop(name,value)
\family default
, where 
\family typewriter
name
\family default
 is the property name (a string) and the value is an atom of the correct
 type.
\end_layout

\begin_layout Section
Binding
\end_layout

\begin_layout Standard
We can tell the Elision system that we want to replace the variable 
\family typewriter
$x
\family default
 with the value 
\family typewriter
7
\family default
 wherever it appears.
 We say the variable 
\family typewriter
$x
\family default
 is 
\emph on
bound
\emph default
 to 
\family typewriter
7
\family default
, and that the pair 
\family typewriter
$x
\family default
 and 
\family typewriter
7
\family default
 is a 
\emph on
binding
\emph default
, written 
\family typewriter
$x -> 7
\family default
.
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
This notation is called a 
\emph on
map pair
\emph default
, and it is actually more general.
 It is explained in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:Map-Pairs"

\end_inset

.
\end_layout

\end_inset

 When we replace the variable 
\family typewriter
$x
\family default
 with 
\family typewriter
7
\family default
 in some other term, we say we are 
\emph on
rewriting
\emph default
 the term with the binding.
 The REPL keeps a set of bindings that are used to immediately rewrite any
 atom 
\emph on
after
\emph default
 it is parsed and constructed.
 For instance, if the variable 
\family typewriter
$x
\family default
 is bound to 
\family typewriter
7
\family default
, then entering 
\family typewriter
$x
\family default
 at the prompt results in the value 
\family typewriter
7
\family default
.
 These bindings are stored in the REPL's 
\emph on
context
\emph default
.
 Contexts are explained in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Contexts"

\end_inset

; for now you only need to know that the REPL creates and maintains a context
 for you.
\end_layout

\begin_layout Standard
The 
\family typewriter
bind(
\emph on
v
\emph default
,
\emph on
a
\emph default
)
\family default
 command binds a variable 
\family typewriter
\emph on
v
\family default
\emph default
 to an atom 
\family typewriter
\emph on
a
\family default
\emph default
.
 For instance, try 
\family typewriter
bind($x,7)
\family default
 and 
\family typewriter
bind($y,
\backslash
$x.%($x,$x))
\family default
.
 Then try 
\family typewriter
$x
\family default
 and 
\family typewriter
$y
\family default
 at the prompt.
 Then try 
\family typewriter
$y.$x
\family default
.
 Variables can be rebound at any time, and there is no need to 
\begin_inset Quotes eld
\end_inset

unbind
\begin_inset Quotes erd
\end_inset

 them first.
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> bind($x,7)
\end_layout

\begin_layout Plain Layout

Bound $x
\end_layout

\begin_layout Plain Layout

e> bind($y,
\backslash
$x.%($x,$x))
\end_layout

\begin_layout Plain Layout

Bound $y
\end_layout

\begin_layout Plain Layout

e> $x
\end_layout

\begin_layout Plain Layout

$_repl16 = 7
\end_layout

\begin_layout Plain Layout

e> $y
\end_layout

\begin_layout Plain Layout

$_repl17 = 
\backslash
$`:1`.%($`:1`, $`:1`)
\end_layout

\begin_layout Plain Layout

e> $y.$x
\end_layout

\begin_layout Plain Layout

$_repl18 = %(7, 7)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 
\family typewriter
unbind(
\emph on
v
\emph default
)
\family default
 command removes any binding for the variable 
\family typewriter
\emph on
v
\family default
\emph default
.
 Try 
\family typewriter
unbind($x)
\family default
 and then repeat 
\family typewriter
$y.$x
\family default
.
 No error is generated if a variable is not bound.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> unbind($x)
\end_layout

\begin_layout Plain Layout

Unbound $x
\end_layout

\begin_layout Plain Layout

e> $y.$x
\end_layout

\begin_layout Plain Layout

$_repl19 = %($x, $x)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If the 
\family typewriter
setreplbinds
\family default
 property is 
\family typewriter
true
\family default
 (which is the default), then every time an atom is evaluated by the REPL,
 the result is displayed and then bound to a new variable whose name starts
 with 
\family typewriter
$_repl
\family default
 followed by a number.
 These variables are displayed on the output.
 Try 
\family typewriter
$_repl1
\family default
.
 Unlike the history, which is persistent between invocations of the REPL,
 these variables are re-started at each session.
\end_layout

\begin_layout Standard
To see all the bindings being used by the shell, enter the command 
\family typewriter
showbinds()
\family default
.
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
Note that any bindings to variables whose name starts with an underscore
 are suppressed in the output.
\end_layout

\end_inset


\end_layout

\begin_layout Section
Atom Display
\end_layout

\begin_layout Standard
When you type an atom at the REPL prompt the system parses the atom and
 constructs it, which may involve evaluating operators.
 Otherwise the current bindings are applied to the atom, and the atom is
 then rewritten using any active rulesets.
 The result of this is then bound to the next 
\family typewriter
$_repl
\family default
\emph on
n
\emph default
 variable.
\end_layout

\begin_layout Standard
You can see the atom after it is parsed and constructed, but before bindings
 are applied and rewriting is performed, by setting the 
\family typewriter
showprior
\family default
 property to 
\family typewriter
true
\family default
.
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
This action results in the odd output 
\family typewriter
` NO SHOW `:SYMBOL
\family default
.
 Elision expects every operator to yield an atom, but this makes no sense
 for operators executed only for their side effect.
 As such, these operators return a special atom typically hidden by the
 REPL.
 Enabling 
\family typewriter
showprior
\family default
 causes ths atom to be displayed.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> bind($x,10)
\end_layout

\begin_layout Plain Layout

Bound $x
\end_layout

\begin_layout Plain Layout

e> setprop("showprior", true)
\end_layout

\begin_layout Plain Layout

` NO SHOW `:SYMBOL
\end_layout

\begin_layout Plain Layout

e> add($x,$x,0)
\end_layout

\begin_layout Plain Layout

add($x, $x)
\end_layout

\begin_layout Plain Layout

$_repl20 = 20
\end_layout

\begin_layout Plain Layout

e> setprop("showprior", false)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The atom as entered was 
\family typewriter
add($x,$x,0)
\family default
.
 During construction the identity 
\family typewriter
0
\family default
 is removed, leaving the atom 
\family typewriter
add($x,$x)
\family default
, which is displayed.
 Then the bindings are applied, yielding 
\family typewriter
add(10,10)
\family default
, which is rewritten to 
\family typewriter
20
\family default
 and displayed as the final result.
\end_layout

\begin_layout Standard
Most REPL printing can be suppressed using the 
\family typewriter
quiet(level)
\family default
 command.
 The 
\family typewriter
level
\family default
 is one of the following values.
\end_layout

\begin_layout Labeling
\labelwidthstring 00.00.0000
0 Show all output.
\end_layout

\begin_layout Labeling
\labelwidthstring 00.00.0000
1 Suppress most output, but still show errors, warnings, and explicitly
 requested output.
\end_layout

\begin_layout Labeling
\labelwidthstring 00.00.0000
2 Suppress warnings, but show errors and explicitly requested output.
\end_layout

\begin_layout Labeling
\labelwidthstring 00.00.0000
3 Suppress warnings and errors, but still show explicitly requested output.
\end_layout

\begin_layout Labeling
\labelwidthstring 00.00.0000
4 Suppress nearly everything.
\end_layout

\begin_layout Standard
Any quiet level except 0 changes the prompt to 
\family typewriter
q>
\family default
.
\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
It is possible to display the Scala code to create the atom.
 This is enabled (and disabled) with the 
\family typewriter
showscala
\family default
 property.
 The assumed context for the resulting code is that the content of the 
\family typewriter
core
\family default
 package is imported.
\end_layout

\begin_layout Plain Layout
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> setprop("showscala", true)
\end_layout

\begin_layout Plain Layout

e> 
\backslash
$x:$T.$T
\end_layout

\begin_layout Plain Layout

Scala: $_repl28 = Lambda(Variable(Variable(NamedRootType("ANY"), "T", 
\end_layout

\begin_layout Plain Layout

  BooleanLiteral(NamedRootType("BOOLEAN"), true), Set()), ":1", 
\end_layout

\begin_layout Plain Layout

  BooleanLiteral(NamedRootType("BOOLEAN"), true), Set()), 
\end_layout

\begin_layout Plain Layout

  Variable(NamedRootType("ANY"), "T", BooleanLiteral(NamedRootType("BOOLEAN"),
 
\end_layout

\begin_layout Plain Layout

  true), Set()))
\end_layout

\begin_layout Plain Layout

$_repl28 = 
\backslash
$`:1`:$T.$T
\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout
This can be useful to discover how to construct an atom using the Scala
 API.
\end_layout

\begin_layout Plain Layout
If the above seems excessively complex, 
\emph on
don't panic
\emph default
.
 There are several helpful parts of the API, including implicit conversions,
 to make this all much simpler.
\end_layout

\end_inset


\end_layout

\begin_layout Section
Automatic Rewriting
\end_layout

\begin_layout Standard
Once an atom is entered and bindings are applied, it is rewritten with the
 active rulesets.
 (Applying rules is the subject of 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Rules-and-Strategies"

\end_inset

.)
\end_layout

\begin_layout Standard
Rulesets are initially disabled when declared.
 They can be 
\emph on
enabled
\emph default
 using the 
\family typewriter
enable(RS)
\family default
 command, where 
\family typewriter
RS
\family default
 is the name of the ruleset.
 Likewise, they can be 
\emph on
disabled
\emph default
 with the 
\family typewriter
disable(RS)
\family default
 command.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> decl.{rule fred -> james #rulesets RENAME}
\end_layout

\begin_layout Plain Layout

ERROR: The ruleset RENAME has not been declared.
\end_layout

\begin_layout Plain Layout

e> declare(RENAME)
\end_layout

\begin_layout Plain Layout

Declared ruleset RENAME:SYMBOL.
\end_layout

\begin_layout Plain Layout

e> decl.{rule fred -> james #rulesets RENAME}
\end_layout

\begin_layout Plain Layout

Declared rule.
\end_layout

\begin_layout Plain Layout

e> fred
\end_layout

\begin_layout Plain Layout

$_repl8 = fred:SYMBOL
\end_layout

\begin_layout Plain Layout

e> enable(RENAME)
\end_layout

\begin_layout Plain Layout

e> fred
\end_layout

\begin_layout Plain Layout

$_repl9 = james:SYMBOL
\end_layout

\end_inset


\end_layout

\begin_layout Standard
A limit is placed on the number of times a rule can be applied to rewrite
 an atom.
 This limit can be set via the 
\family typewriter
setlimit(lim)
\family default
 command, where 
\family typewriter
lim
\family default
 is the new limit.
 A limit of zero disables automatic rewriting, and a negative limit is equivalen
t to no limit.
 Automatic rewriting is on by default, but can be disabled (or re-enabled)
 altogether with the 
\family typewriter
autorewrite
\family default
 property.
 It is enabled by default.
\end_layout

\begin_layout Standard
You can ask the system which rules may be applied to an atom, using the
 
\family typewriter
showrules(atom)
\family default
 command, where 
\family typewriter
atom
\family default
 is the atom to test.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> showrules(if (true, 6, 7))
\end_layout

\begin_layout Plain Layout

{ RULE if(true, $thenpart, $elsepart) -> $thenpart rulesets IF level 2 }
\end_layout

\begin_layout Plain Layout

{ RULE if(false, $thenpart, $elsepart) -> $elsepart rulesets IF level 2
 } 
\end_layout

\end_inset


\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout Section
Understanding Matching
\end_layout

\begin_layout Standard
To support better understanding of the matching process, it is possible
 to enable (or disable) tracing the matching process with the 
\family typewriter
tracematch()
\family default
 command.
 When enabled considerable diagnostic information is printed for every match
 that is attempted.
\end_layout

\begin_layout Standard
Several things trigger the matching system.
 One is constructing an operator application, where arguments are matched
 against the formal parameters.
 Another is matching a lambda argument to the parameter.
 Of course, the most obvious way is by explicitly trying to match two atoms.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> tracematch()
\end_layout

\begin_layout Plain Layout

Match tracing is ON.
\end_layout

\begin_layout Plain Layout

e> 
\backslash
$x.add(1,$x).5
\end_layout

\begin_layout Plain Layout

Sequence Matcher called: 
\end_layout

\begin_layout Plain Layout

    Patterns: $type
\end_layout

\begin_layout Plain Layout

    Subjects: ANY
\end_layout

\begin_layout Plain Layout

    Bindings: { binds  }
\end_layout

\begin_layout Plain Layout

TRYING  (a55109e) in class ornl.elision.core.Variable:
\end_layout

\begin_layout Plain Layout

  pattern: $type
\end_layout

\begin_layout Plain Layout

  subject: ANY
\end_layout

\begin_layout Plain Layout

  with: { binds  }
\end_layout

\begin_layout Plain Layout

SUCCESS (a55109e): { binds type -> ANY }
\end_layout

\begin_layout Plain Layout

...
\end_layout

\begin_layout Plain Layout

TRYING  (f021a3c0) in class ornl.elision.core.INTEGER$:
\end_layout

\begin_layout Plain Layout

  pattern: INTEGER
\end_layout

\begin_layout Plain Layout

  subject: INTEGER
\end_layout

\begin_layout Plain Layout

  with: { binds  }
\end_layout

\begin_layout Plain Layout

SUCCESS (f021a3c0): { binds  }
\end_layout

\begin_layout Plain Layout

SUCCESS (1412e2ce): { binds x -> 6 }
\end_layout

\begin_layout Plain Layout

$_repl14 = 6
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Reading this trace can be tricky.
 The sequence matcher tries to perform an in-order pairwise match of two
 sequences of atoms, given some set of bindings.
 For example, the first line indicates that the sequence matcher was called
 to match the pattern sequence 
\family typewriter
$domain,$codomain
\family default
 against the subject sequence 
\family typewriter
$T,ANY
\family default
 with no prior bindings.
\end_layout

\begin_layout Standard
The lines that begin with 
\family typewriter
TRYING
\family default
 and 
\family typewriter
SUCCESS
\family default
 or 
\family typewriter
FAILURE
\family default
 are linked using the hexadecimal number in parentheses.
 This number is actually a hash code for the match attempt and serves to
 link together the lines.
 In a large match attempts will often interleave.
\end_layout

\begin_layout Standard
Following a 
\family typewriter
TRYING
\family default
 line the pattern, subject, and any bindings are printed.
 On 
\family typewriter
SUCCESS
\family default
 we see the bindings that result in a successful match.
 On 
\family typewriter
FAILURE
\family default
 we are told why the match failed, and the pattern and subject may be repeated.
\end_layout

\begin_layout Standard
In some cases there will be additional matching reports after the 
\family typewriter
$_repl
\family default
 result is shown.
 These are due to 
\emph on
round-trip testing
\emph default
 by the system.
 This is testing that determines whether or not an atom's representation
 can be successfully re-parsed to yield the original atom, and this output
 can safely be ignored.
 Look for the line beginning with 
\family typewriter
$_repl
\family default
 and ignore subsequent output.
 To disable round trip testing, set the property 
\family typewriter
roundtrip
\family default
 to 
\family typewriter
false
\family default
.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> {match 7}.$x
\end_layout

\begin_layout Plain Layout

Sequence Matcher called: 
\end_layout

\begin_layout Plain Layout

    Patterns: $type
\end_layout

\begin_layout Plain Layout

    Subjects: INTEGER
\end_layout

\begin_layout Plain Layout

    Bindings: { binds  }
\end_layout

\begin_layout Plain Layout

TRYING  (a9d51ff0) in class ornl.elision.core.Variable:
\end_layout

\begin_layout Plain Layout

  pattern: $type
\end_layout

\begin_layout Plain Layout

  subject: INTEGER
\end_layout

\begin_layout Plain Layout

  with: { binds  }
\end_layout

\begin_layout Plain Layout

SUCCESS (a9d51ff0): { binds type -> INTEGER }
\end_layout

\begin_layout Plain Layout

Sequence Matcher called: 
\end_layout

\begin_layout Plain Layout

    Patterns: $domain,$codomain
\end_layout

\begin_layout Plain Layout

    Subjects: ANY,BINDING
\end_layout

\begin_layout Plain Layout

    Bindings: { binds  }
\end_layout

\begin_layout Plain Layout

TRYING  (71407c54) in class ornl.elision.core.Variable:
\end_layout

\begin_layout Plain Layout

  pattern: $domain
\end_layout

\begin_layout Plain Layout

  subject: ANY
\end_layout

\begin_layout Plain Layout

  with: { binds  }
\end_layout

\begin_layout Plain Layout

SUCCESS (71407c54): { binds domain -> ANY }
\end_layout

\begin_layout Plain Layout

TRYING  (f6b11b01) in class ornl.elision.core.Variable:
\end_layout

\begin_layout Plain Layout

  pattern: $codomain
\end_layout

\begin_layout Plain Layout

  subject: BINDING
\end_layout

\begin_layout Plain Layout

  with: { binds domain -> ANY }
\end_layout

\begin_layout Plain Layout

SUCCESS (f6b11b01): { binds domain -> ANY codomain -> BINDING }
\end_layout

\begin_layout Plain Layout

TRYING  (c390faa3) in class ornl.elision.core.IntegerLiteral:
\end_layout

\begin_layout Plain Layout

  pattern: 7
\end_layout

\begin_layout Plain Layout

  subject: $x
\end_layout

\begin_layout Plain Layout

  with: { binds  }
\end_layout

\begin_layout Plain Layout

TRYING  (50a1946e) in class ornl.elision.core.INTEGER$:
\end_layout

\begin_layout Plain Layout

  pattern: INTEGER
\end_layout

\begin_layout Plain Layout

  subject: ANY
\end_layout

\begin_layout Plain Layout

  with: { binds  }
\end_layout

\begin_layout Plain Layout

SUCCESS (50a1946e): { binds  }
\end_layout

\begin_layout Plain Layout

FAILURE (c390faa3): Literal pattern does not match subject.
\end_layout

\begin_layout Plain Layout

  pattern: 7
\end_layout

\begin_layout Plain Layout

  subject: $x
\end_layout

\begin_layout Plain Layout

$_repl10 = NONE
\end_layout

\end_inset


\end_layout

\begin_layout Standard
For this simple example we see the inner attempt to match the types succeeds,
 and then the outer attempt to match the entire atoms fails because 
\family typewriter
7
\family default
 is a literal pattern and it can only match another literal 
\family typewriter
7
\family default
.
\end_layout

\begin_layout Section
Understanding Parsing
\end_layout

\begin_layout Standard
The parser can also be traced, and this results in an enormous quantity
 of output.
 To enable (or disable) parser tracing, use the 
\family typewriter
traceparse()
\family default
 command.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> traceparse()
\end_layout

\begin_layout Plain Layout

Parser tracing is ON.
\end_layout

\begin_layout Plain Layout

e> 7
\end_layout

\begin_layout Plain Layout

Starting new parsing run
\end_layout

\begin_layout Plain Layout

a sequence of atoms/ZeroOrMore/AtomSeqPush1Action1, matched, cursor at 1:1
 after ""
\end_layout

\begin_layout Plain Layout

..(1)../ZeroOrMore/ZeroOrMore/Sequence/an atom/LApply/a simple atom/whitespace
 or
\end_layout

\begin_layout Plain Layout

comments/FirstOf/OneOrMore/[ 
\backslash
n
\backslash
r
\backslash
t
\backslash
f], failed, cursor at 1:1 after ""
\end_layout

\begin_layout Plain Layout

..(9)../OneOrMore, failed, cursor at 1:1 after ""
\end_layout

\begin_layout Plain Layout

..(8)../FirstOf/Sequence/"/*", failed, cursor at 1:1 after ""
\end_layout

\begin_layout Plain Layout

..(9)../Sequence, failed, cursor at 1:1 after ""
\end_layout

\begin_layout Plain Layout

..(8)../FirstOf/Sequence/"//", failed, cursor at 1:1 after ""
\end_layout

\begin_layout Plain Layout

..(9)../Sequence, failed, cursor at 1:1 after ""
\end_layout

\begin_layout Plain Layout

..(8)../FirstOf, failed, cursor at 1:1 after ""
\end_layout

\begin_layout Plain Layout

..(7)../whitespace or comments, matched, cursor at 1:1 after ""
\end_layout

\begin_layout Plain Layout

..(6)../a simple atom/FirstOf/Sequence/'(', failed, cursor at 1:1 after ""
\end_layout

\begin_layout Plain Layout

..(8)../Sequence, failed, cursor at 1:1 after ""
\end_layout

\begin_layout Plain Layout

..(7)../FirstOf/a ruleset declaration/'{', failed, cursor at 1:1 after ""
\end_layout

\begin_layout Plain Layout

..(8)../a ruleset declaration, failed, cursor at 1:1 after ""
\end_layout

\begin_layout Plain Layout

..(7)../FirstOf/a rewrite rule/'{', failed, cursor at 1:1 after ""
\end_layout

\begin_layout Plain Layout

..(8)../a rewrite rule, failed, cursor at 1:1 after ""
\end_layout

\begin_layout Plain Layout

...
\end_layout

\begin_layout Plain Layout

..(3)../Sequence, failed, cursor at 1:2 after "7"
\end_layout

\begin_layout Plain Layout

..(2)../FirstOf/Sequence/"//", failed, cursor at 1:2 after "7"
\end_layout

\begin_layout Plain Layout

..(3)../Sequence, failed, cursor at 1:2 after "7"
\end_layout

\begin_layout Plain Layout

..(2)../FirstOf, failed, cursor at 1:2 after "7"
\end_layout

\begin_layout Plain Layout

..(1)../whitespace or comments, matched, cursor at 1:2 after "7"
\end_layout

\begin_layout Plain Layout

a sequence of atoms/EOI, matched, cursor at 1:3 after "7"
\end_layout

\begin_layout Plain Layout

a sequence of atoms, matched, cursor at 1:3 after "7"
\end_layout

\begin_layout Plain Layout

$_repl14 = 7
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Many, many lines are omitted from the above.
 The number shows the depth of the parse which, for this example, reaches
 16.
 Note that, as with match tracing, the round trip testing results in additional
 output that can be ignored.
\end_layout

\begin_layout Section
Reading Files
\end_layout

\begin_layout Standard
If you want to load several operator definitions and rules, you can put
 these in a file and then tell Elision to read the file.
 You do this via the 
\family typewriter
read(filename)
\family default
 operator, where 
\family typewriter
filename
\family default
 is the name of the file to load.
 Elision reads the contents of the file, processing bindings, operator definitio
ns, rules, etc.
 Most output from this process is suppressed by first putting the REPL is
 quiet mode and suspending creating 
\family typewriter
$_repl
\family default
 bindings.
\end_layout

\begin_layout Standard
If the filename is absolute (that is, it fully specifies the location of
 the file), then the file is simply read.
 Otherwise Elision needs to 
\emph on
find
\emph default
 the file before it can read it.
 It does this by checking a search path.
 The path is specified by the 
\family typewriter
path
\family default
 property.
 This is a string containing a list of folders to search.
 On Windows the folders are separated by semicolons (
\family typewriter
;
\family default
), while on UNIX (including Mac OS X) and Linux they are separated by colons
 (
\family typewriter
:
\family default
).
\end_layout

\begin_layout Section
Bootstrapping
\end_layout

\begin_layout Standard
When the Elision REPL starts, it first reads its bootstrap files that declare
 all the 
\begin_inset Quotes eld
\end_inset

built in
\begin_inset Quotes erd
\end_inset

 operators and rules.
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
This includes declaring the operator 
\family typewriter
decl
\family default
 that is used to declare other operators and rules.
 How this is done is explained in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Native-Handlers"

\end_inset

.
\end_layout

\end_inset

 It does this by locating and reading the file 
\family typewriter
Boot.eli
\family default
.
\end_layout

\begin_layout Chapter
Basic Atoms
\end_layout

\begin_layout Standard
The objects manipulated by Elision are called 
\emph on
atoms
\emph default
, and they exist in several forms.
\end_layout

\begin_layout Itemize

\emph on
Literals
\emph default
 that denote a simple, fixed value.
\end_layout

\begin_layout Itemize

\emph on
Variables
\emph default
 denote an unspecified atom, perhaps with type information.
\end_layout

\begin_layout Itemize

\emph on
Lambdas
\emph default
 denote simple unnamed functions of one parameter.
\end_layout

\begin_layout Itemize

\emph on
Applies
\emph default
 denote an ordered pair consisting of a left-hand element often called the
 
\emph on
operator
\emph default
 and a right-hand element often called the 
\emph on
argument
\emph default
.
\end_layout

\begin_layout Itemize

\emph on
Operators
\emph default
 denote a mapping.
\end_layout

\begin_layout Itemize

\emph on
Rewriters
\emph default
 transform an atom into a potentially new form, reporting whether this transform
ation succeeded.
\end_layout

\begin_layout Standard
Atoms can be combined to make composite atoms
\begin_inset Foot
status open

\begin_layout Plain Layout
No, not molecules.
 This is not chemistry.
\end_layout

\end_inset

 in a variety of ways.
 These are discussed in the following sections and chapters.
\end_layout

\begin_layout Section
Types
\end_layout

\begin_layout Standard
Every atom has an associated 
\emph on
type
\emph default
, which is itself just another atom.
 Since every atom has a type, and every type is an atom, we have a potential
 infinite regress.
 To avoid this the special 
\emph on
type universe
\emph default
 atom, denoted 
\family typewriter
^TYPE
\family default
, is its own type.
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
As has been pointed out, 
\begin_inset Quotes eld
\end_inset

it's turtles all the way down.
\begin_inset Quotes erd
\end_inset

 
\family typewriter
^TYPE
\family default
 is the turtle that stands on its own head.
\end_layout

\end_inset

 The fact that atom 
\begin_inset Formula $a$
\end_inset

 has type 
\begin_inset Formula $T$
\end_inset

 is denoted by joining the atom and its type with a colon: 
\begin_inset Formula $a:T$
\end_inset

.
 The type colon is right associative, so 
\begin_inset Formula $a:B:C$
\end_inset

 denotes 
\begin_inset Formula $a:(B:C)$
\end_inset

.
 In fact, this is the only way the colon can work.
 Since an atom has exactly one type, 
\begin_inset Formula $(a:B):C$
\end_inset

 is effectively meaningless, and generates an error in Elision.
 The term 
\emph on
root type
\emph default
 refers to any type whose own type is 
\family typewriter
^TYPE
\family default
.
 For instance, 
\family typewriter
STRING
\family default
 is a root type that denotes 
\family typewriter
STRING:^TYPE
\family default
.
 If the symbol 
\family typewriter
STRING
\family default
 is desired, it must be written 
\family typewriter
STRING:SYMBOL
\family default
.
\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
Every atom is an instance of a class extending 
\family typewriter
core.BasicAtom
\family default
.
 All atoms are immutable after construction.
 The type of an atom must be specified at construction time, and can be
 accessed later via the public field 
\family typewriter
theType
\family default
.
 The type universe can be accessed in two ways: 
\family typewriter
core.TypeUniverse
\family default
 is a singleton implementing the type universe, and it can be accessed via
 the alias 
\family typewriter
`^TYPE`
\family default
 provided by the 
\family typewriter
core
\family default
 package.
 Back ticks must be used since 
\family typewriter
^TYPE
\family default
 is not a valid Scala symbol.
\end_layout

\end_inset


\end_layout

\begin_layout Section
Literals
\end_layout

\begin_layout Standard
Elision directly supports several kinds of literals.
 These are indivisible, simple-valued atoms.
\end_layout

\begin_layout Subsection
Symbols
\end_layout

\begin_layout Standard
Symbols start with an underscore or letter, followed by any number of letters,
 digits, and underscores.
 The following are legal symbol literals.
\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="1" columns="4">
<features tabularvalignment="middle" tabularwidth="80col%">
<column alignment="left" valignment="top" width="0pt">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0pt">
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
A
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
x
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
_21
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
Fred21
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Standard
Other characters may occur in symbols, but the entire symbol must be enclosed
 in back ticks, which are not themselves part of the symbol.
 Several escape sequences are interpreted; these are listed in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "tab:Escape-Codes"

\end_inset

.
\begin_inset Float table
wide false
sideways false
status collapsed

\begin_layout Plain Layout
\begin_inset Caption

\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "tab:Escape-Codes"

\end_inset

Escape Codes
\end_layout

\end_inset


\begin_inset Tabular
<lyxtabular version="3" rows="7" columns="2">
<features tabularvalignment="middle">
<column alignment="center" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter

\backslash
f
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Form Feed Character
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter

\backslash
n
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Newline
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter

\backslash
r
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Carriage Return
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter

\backslash
t
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tab Character
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter

\backslash
`
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Back tick
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter

\backslash

\begin_inset Quotes erd
\end_inset


\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Double Quotation Mark
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter

\backslash

\backslash

\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Backslash
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\end_inset

 Using the back tick notation the following are also legal symbol literals.
\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="1" columns="4">
<features tabularvalignment="middle" tabularwidth="80col%">
<column alignment="left" valignment="top" width="0pt">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0pt">
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
`1`
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
`$_4`
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
`
\backslash
`Fred
\backslash
``
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
``
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
Symbols are created via the 
\family typewriter
core.Literal(sym)
\family default
 method, where 
\family typewriter
sym
\family default
 is a Scala symbol.
\end_layout

\begin_layout Plain Layout
Take care! Scala symbols are automatically converted to Elision 
\emph on
variables
\emph default
, not symbol literals, when used in a context expecting an Elision atom.
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Strings
\end_layout

\begin_layout Standard
A string is a sequence of characters enclosed in double quotation marks,
 which are not themselves part of the symbol.
 As with back-tick-quoted symbols, escape codes are interpreted in the string.
 The escape codes are listed in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "tab:Escape-Codes"

\end_inset

.
 The following are legal string literals.
\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="1" columns="4">
<features tabularvalignment="middle" tabularwidth="80col%">
<column alignment="left" valignment="top" width="0pt">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0pt">
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
""
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
"Fred"
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
"`21,` she said."
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
"
\backslash
"Yes,
\backslash
" he replied."
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Standard
Elision also provides for verbatim blocks, which evaluate to strings.
 A verbatim block is indicated by any arbitrary text enclosed within triple
 quotation mark pairs.
 All characters are preserved as-is, and the result of evaluation is a string
 literal.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> """
\end_layout

\begin_layout Plain Layout

 > This is a multiline string literal.
\end_layout

\begin_layout Plain Layout

 > Note that 
\backslash
 is left untouched."""
\end_layout

\begin_layout Plain Layout

$_repl3 = "
\backslash
nThis is a multiline string literal.
\backslash
nNote that 
\backslash

\backslash
 is left untouched." 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Finally, strings can be concatenated with the applicative dot.
 Thus 
\family typewriter
"DJ "."Kousuke"
\family default
 is interpreted as 
\family typewriter
"DJ Kousuke"
\family default
.
 This enables defining strings with variables, as with 
\family typewriter
{binds last->"Kousuke"}.("DJ ".$last)
\family default
, which also yields 
\family typewriter
"DJ Kousuke"
\family default
.
\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
Strings are created via the 
\family typewriter
core.Literal(str)
\family default
 method, where 
\family typewriter
str
\family default
 is a Scala string.
\end_layout

\begin_layout Plain Layout
Scala strings are automatically converted to Elision string literals as
 necessary.
 Thus it is possible to pass 
\family typewriter
"$"
\family default
 to a method expecting an Elision atom.
\end_layout

\begin_layout Plain Layout
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

scala> "I'm a string":BasicAtom
\end_layout

\begin_layout Plain Layout

res0: ornl.elision.core.BasicAtom = StringLiteral(NamedRootType("STRING"),
\end_layout

\begin_layout Plain Layout

"I'm a string") 
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Numbers
\end_layout

\begin_layout Standard
Numbers may be expressed in binary, octal, decimal, or hexadecimal (the
 
\emph on
radix
\emph default
).
 Binary numbers are indicated by the prefix 
\family typewriter
0b
\family default
, octal numbers are indicated by a leading 
\family typewriter
0
\family default
, decimal numbers are indicated by a leading non-zero digit, and hexadecimal
 numbers are indicated by the prefix 
\family typewriter
0x
\family default
.
 The prefixes are 
\emph on
not
\emph default
 case-sensitive.
\end_layout

\begin_layout Standard
Floating point numbers are also supported in binary, octal, decimal, and
 hexadecimal, and are indicated either by a decimal point, an exponent,
 or both.
 The exponent is typically indicated by an 
\family typewriter
e
\family default
, must be an integer, and may be in a different radix.
 Because 
\family typewriter
e
\family default
 is a valid hexadecimal digit, 
\family typewriter
p
\family default
 may also be used to indicate an exponent (and must be for hexadecimal numbers).
 Numbers are 
\emph on
not
\emph default
 case sensitive.
 If a floating point number consists of significand 
\begin_inset Formula $s$
\end_inset

, exponent 
\begin_inset Formula $e$
\end_inset

, and radix 
\begin_inset Formula $r$
\end_inset

, then the number denoted is given by the following equation.
\begin_inset Formula 
\[
s\times r^{e}
\]

\end_inset


\end_layout

\begin_layout Standard
The following are legal number literals.
\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="3" columns="4">
<features tabularvalignment="middle" tabularwidth="80col%">
<column alignment="left" valignment="top" width="0pt">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0pt">
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
0
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
-1
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
05743645134635
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
-0x232
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
2.5
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
0b10.1
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
0x2.8
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
02.4
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
21e-6
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
0b10101e-0b110
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
0x15p-0x6
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
025e-06
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Standard
\noindent
Keep in mind that the radix of the significand and the exponent must both
 be specified.
\end_layout

\begin_layout Standard
The number undergoes a conversion to place it in a consistent radix.
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
This conversion takes place during parsing.
\end_layout

\end_inset

 This conversion is performed as follows.
 Let the number be 
\begin_inset Formula $i.f\mathtt{e}e$
\end_inset

, where 
\begin_inset Formula $i$
\end_inset

 is the integer portion of the significand, 
\begin_inset Formula $f$
\end_inset

 is the fractional portion of the significand, and 
\begin_inset Formula $e$
\end_inset

 is the exponent.
 We note that 
\begin_inset Formula $i.f$
\end_inset

 is in one radix, which we denote 
\begin_inset Formula $r$
\end_inset

, and the exponent may be in a different radix.
 If the length of 
\begin_inset Formula $f$
\end_inset

 is 
\begin_inset Formula $|f|$
\end_inset

, then the entire significand is multiplied by 
\begin_inset Formula $r^{|f|}$
\end_inset

 to convert it to an integer.
 The exponent is then converted to radix 
\begin_inset Formula $r$
\end_inset

, yielding 
\begin_inset Formula $e'$
\end_inset

, and 
\begin_inset Formula $|f|$
\end_inset

 is subtracted from it.
\begin_inset Formula 
\[
n=i.f\mathtt{e}e=(i.f)r^{|f|}\mathtt{e}(e'-|f|)
\]

\end_inset


\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
Integers are created via the 
\family typewriter
core.Literal(i)
\family default
 method, where 
\family typewriter
i
\family default
 is a Scala 
\family typewriter
BigInt
\family default
.
 Floating point numbers can be created via the 
\family typewriter
core.Literal(FLOAT,sig,exp,rad)
\family default
 method, where 
\family typewriter
sig
\family default
 is the significand (a Scala 
\family typewriter
BigInt
\family default
), 
\family typewriter
exp
\family default
 is the exponent (a Scala 
\family typewriter
Int
\family default
), and 
\family typewriter
rad
\family default
 is the radix (one of 2, 8, 10, or 16).
\end_layout

\begin_layout Plain Layout
Scala 
\family typewriter
Int
\family default
 and 
\family typewriter
BigInt
\family default
 are automatically converted to Elision integer literals as necessary.
 Thus it is possible to pass 
\family typewriter
17
\family default
 to a method expecting an Elision atom.
\end_layout

\begin_layout Plain Layout
If you have a floating point literal, you can obtain its value as a Scala
 float with 
\family typewriter
toFloat
\family default
 and as a Scala double with 
\family typewriter
toDouble
\family default
.
 You can also convert it to radix two using 
\family typewriter
toBinary
\family default
.
 Because this changes the base of a floating point number you may lose precision.
\end_layout

\begin_layout Plain Layout
At present Elision does not support the positive or negative infinity or
 the signaling or quiet NaN.
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Booleans
\end_layout

\begin_layout Standard
Boolean literals come in two forms: 
\family typewriter
true
\family default
 and 
\family typewriter
false
\family default
.
 Both have the type 
\family typewriter
BOOLEAN
\family default
.
 If you want an Elision symbol named 
\family typewriter
true
\family default
 or 
\family typewriter
false
\family default
, you must override the type, and write 
\family typewriter
true:SYMBOL
\family default
, for instance.
\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
The Boolean literals can be obtained as 
\family typewriter
Literal.TRUE
\family default
 and 
\family typewriter
Literal.FALSE
\family default
.
 Scala Booleans are automatically converted to Elision Boolean literals
 as necessary.
\end_layout

\end_inset


\end_layout

\begin_layout Section
Special Symbols
\end_layout

\begin_layout Standard
Certain symbols are interpreted differently from others.
 Three have already been discussed: 
\family typewriter
^TYPE
\family default
 denoting the type universe, 
\family typewriter
true
\family default
, and 
\family typewriter
false
\family default
.
 Others denote named root types.
 A 
\emph on
root atom
\emph default
 is an atom whose type is 
\family typewriter
^TYPE
\family default
.
 
\begin_inset CommandInset ref
LatexCommand formatted
reference "tab:Special-Root-Type"

\end_inset

 lists the named root atoms declared by the current system.
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
It is possible to create new named root atoms.
 The following declares an operator that does just this.
 Give it a symbol, and that symbol becomes a named root type.
 For details about how this works, see 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Native-Handlers"

\end_inset

.
\end_layout

\begin_layout LyX-Code
decl.{! declare_rt($name: SYMBOL)
\end_layout

\begin_layout LyX-Code
#description="Declare a new named root atom."
\end_layout

\begin_layout LyX-Code
#detail="Declare $name to be a new named root atom."
\end_layout

\begin_layout LyX-Code
#handler="""
\end_layout

\begin_layout LyX-Code
  args match {
\end_layout

\begin_layout LyX-Code
    case Args(SymbolLiteral(_, sym)) =>
\end_layout

\begin_layout LyX-Code
      NamedRootType(sym.name)
\end_layout

\begin_layout LyX-Code
    case _ => as_is
\end_layout

\begin_layout LyX-Code
  }
\end_layout

\begin_layout LyX-Code
"""}
\end_layout

\end_inset

 These are typically used as types, so they are often called 
\emph on
root types
\emph default
.
 Two of these: 
\family typewriter
OPREF
\family default
 and 
\family typewriter
RSREF
\family default
 exist to cause the system to 
\begin_inset Quotes eld
\end_inset

look up
\begin_inset Quotes erd
\end_inset

 a name in the current context.
\end_layout

\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status open

\begin_layout Plain Layout
\begin_inset Caption

\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "tab:Special-Root-Type"

\end_inset

Special Root Type Symbols
\end_layout

\end_inset


\begin_inset Tabular
<lyxtabular version="3" rows="12" columns="2">
<features tabularvalignment="middle">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<row>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Elision Symbol
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Interpretation
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
ANY
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
The wildcard.
 The special atom denoting anything.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
BINDING
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
The root type for all bindings.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
BOOLEAN
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
The root type for all Booleans.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
FLOAT
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
The root type for all floating point numbers.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
INTEGER
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
The root type for all integer numbers.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
NONE
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
The special atom denoting nothing.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
OPREF
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
A root type for indicating that a symbol denotes an operator.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
RSREF
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
A root type for indicating that a symbol denotes a ruleset.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
STRATEGY
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
The root type for all strategies and rewrite rules.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
STRING
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
The root type for all strings.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
SYMBOL
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
The root type for all symbols.
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
The special atom 
\family typewriter
ANY
\family default
 matches any atom, and any atom matches it, so it can be treated as a wildcard
 during matching, and is also the assumed type of otherwise untyped atoms.
 
\family typewriter
ANY
\family default
 is unusual; it violates the substitution principle (see 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Matching-and-Rewriting"

\end_inset

).
 
\family typewriter
ANY
\family default
 matches 
\family typewriter
NONE
\family default
, but 
\family typewriter
NONE
\family default
 matches only itself.
\end_layout

\begin_layout Standard
Untyped symbols not in the above list have the assumed type 
\family typewriter
SYMBOL
\family default
.
 If you want an ordinary symbol counterpart to any of the above, you must
 explicitly ask for it.
 For example, if you want the ordinary symbol 
\family typewriter
STRATEGY
\family default
, you must use 
\family typewriter
STRATEGY:SYMBOL
\family default
.
\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
All the symbols listed in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "tab:Special-Root-Type"

\end_inset

 are also Scala objects that extend 
\family typewriter
core.NamedRootType
\family default
.
 They can be used directly, so 
\family typewriter
SYMBOL
\family default
 is a Scala value denoting the Elision 
\family typewriter
SYMBOL
\family default
 type.
\end_layout

\end_inset


\end_layout

\begin_layout Section
Variables
\end_layout

\begin_layout Standard
Variables are indicated by a leading dollar sign followed by the variable
 name, which is parsed as a symbol.
 The following are legal variables.
\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="1" columns="4">
<features tabularvalignment="middle" tabularwidth="80col%">
<column alignment="left" valignment="top" width="0pt">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0pt">
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
$x
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
$_21
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
$`1`
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
$`$_4`
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Standard
Variables are looked up by name, but matched by 
\emph on
both
\emph default
 name and type.
 This means that you should never use the same variable name with different
 types in a single atom, as it will break matching in unusual ways.
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
This is not an attempt to be frustrating.
 It is a performance issue.
 Under the hood, bindings are stored in a hash table indexed by the interned
 variable name.
 This makes lookup faster than if we had to check for an equal name and
 type.
\end_layout

\end_inset

 If no type is specified for a variable, Elision assigns it the special
 root type 
\family typewriter
ANY
\family default
.
\end_layout

\begin_layout Standard
A variable instance may have an associated guard that controls how it may
 be bound.
 This will be explained in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Matching-and-Rewriting"

\end_inset

.
 Variables may also have zero or more labels attached to them.
 A 
\emph on
label
\emph default
 consists of a symbol preceded by an at symbol (
\family typewriter
@
\family default
).
 An example is 
\family typewriter
$x @free @strict
\family default
.
 Labels are used by the 
\emph on
map
\emph default
 strategy, explained in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Rules-and-Strategies"

\end_inset

.
\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
Variables are created using 
\family typewriter
core.Variable(typ,name,guard,labels)
\family default
, where 
\family typewriter
typ
\family default
 is the variable type, 
\family typewriter
name
\family default
 is the variable name, 
\family typewriter
guard
\family default
 is an optional guard (it is 
\family typewriter
true
\family default
 by default), and 
\family typewriter
labels
\family default
 is an optional set of labels.
 Thus the Elision variable 
\family typewriter
$x:INTEGER
\family default
 can be created with 
\family typewriter
Variable(INTEGER,"x")
\family default
.
 Scala symbols are also automatically converted to variables of type 
\family typewriter
ANY
\family default
, so it is possible to pass a Scala symbol to methods expecting an atom.
 Thus 
\family typewriter
$x:ANY
\family default
 can also be written (depending on context) as 
\family typewriter
'x
\family default
.
\end_layout

\end_inset


\end_layout

\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Metavariables"

\end_inset

Metavariables
\end_layout

\begin_layout Standard
A variable 
\family typewriter
$x
\family default
 can be converted to a 
\emph on
meta
\emph default
variable by writing it with an extra dollar sign: 
\family typewriter
$$x
\family default
.
 This term still denotes the variable 
\family typewriter
$x
\family default
, but prevents evaluation of operators and other applications and rewrites.
 A 
\emph on
meta-term
\emph default
 is any term containing at least one metavariable.
 Metavariables may have guards and labels, just as ordinary variables do.
 The variable 
\family typewriter
$x
\family default
 and the metavariable 
\family typewriter
$$x
\family default
 denote the same (unspecified) atom.
\end_layout

\begin_layout Standard
The function of metavariables is to delay evaluation of terms.
 For example, the term 
\family typewriter
is_bindable($x)
\family default
 evaluates to 
\family typewriter
true
\family default
 immediately, since the variable 
\family typewriter
$x
\family default
 is, in fact, bindable.
 However the term 
\family typewriter
is_bindable($$x)
\family default
 is preserved as-is until the metavariable 
\family typewriter
$$x
\family default
 is rewritten to some other term.
 This rewriting is most easily performed using a lambda (see 
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:Lambdas"

\end_inset

).
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> is_bindable($x)
\end_layout

\begin_layout Plain Layout

$_repl0 = true
\end_layout

\begin_layout Plain Layout

e> is_bindable($$x)
\end_layout

\begin_layout Plain Layout

$_repl1 = (is_bindable:OPREF.%($$x))
\end_layout

\begin_layout Plain Layout

e> 
\backslash
$$x.is_bindable($$x)
\end_layout

\begin_layout Plain Layout

$_repl2 = 
\backslash
$$`:1`.(is_bindable:OPREF.%($$`:1`))
\end_layout

\begin_layout Plain Layout

e> 
\backslash
$$x.is_bindable($$x).5
\end_layout

\begin_layout Plain Layout

$_repl3 = false
\end_layout

\begin_layout Plain Layout

e> 
\backslash
$$x.is_bindable($$x).$y
\end_layout

\begin_layout Plain Layout

$_repl4 = true
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Metavariables are enormously useful, and should be used by convention in
 guards and certain other places where we want to defer evaluation.
\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
Variables are created using 
\family typewriter
core.MetaVariable(typ,name,guard,labels)
\family default
, where 
\family typewriter
typ
\family default
 is the variable type, 
\family typewriter
name
\family default
 is the variable name, 
\family typewriter
guard
\family default
 is the optional guard (the default is 
\family typewriter
true
\family default
), and 
\family typewriter
labels
\family default
 is an optional set of labels.
 Thus the Elision metavariable 
\family typewriter
$$x:INTEGER
\family default
 can be created with 
\family typewriter
MetaVariable(INTEGER,"x")
\family default
.
\end_layout

\end_inset


\end_layout

\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Lambdas"

\end_inset

Lambdas
\end_layout

\begin_layout Standard
A lambda expression denotes a function with a single parameter, and consists
 of a variable called the 
\emph on
lambda parameter
\emph default
 and an atom called the 
\emph on
body
\emph default
.
 The lambda is 
\emph on
evaluated
\emph default
 (or 
\emph on
curried
\emph default
) by applying it to another atom, called the 
\emph on
argument
\emph default
, and then replacing instances of the lambda parameter in the body with
 the argument.
 This is all much simpler than it sounds.
\end_layout

\begin_layout Standard
Lambdas are introduced by a backslash (
\family typewriter

\backslash

\family default
) followed by the parameter (a variable), then a dot (
\family typewriter
.
\family default
), and then the body (an atom).
 The following is a lambda that denotes a constant function whose value
 is 7 no matter what argument is provided.
\end_layout

\begin_layout LyX-Code

\backslash
$x.7
\end_layout

\begin_layout Standard
The following denotes the identity function that returns the atom it is
 applied to.
\begin_inset Foot
status open

\begin_layout Plain Layout
This is sometimes called the 
\emph on
I combinator
\emph default
.
\end_layout

\end_inset


\end_layout

\begin_layout LyX-Code

\backslash
$x.$x
\end_layout

\begin_layout Standard
The following is a lambda that creates constant functions.
\begin_inset Foot
status open

\begin_layout Plain Layout
This also has a catchy name: it is the 
\emph on
K combinator
\emph default
.
\end_layout

\end_inset

 When applied to an argument, the result is a function that always returns
 that argument.
\end_layout

\begin_layout LyX-Code

\backslash
$x.
\backslash
$y.$x
\end_layout

\begin_layout Standard
To apply a lambda to an atom, join the lambda and the atom with a dot (
\family typewriter
.
\family default
).
 The lambda dot binds more tightly than the application dot.
 
\begin_inset CommandInset ref
LatexCommand formatted
reference "tab:Lambdas"

\end_inset

 shows some examples of lambda applications and the results.
 The parentheses around the 7 in the first entry are required to prevent
 the system from seeing 7.12 as a floating point number.
\end_layout

\begin_layout Standard
Consider the last item in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "tab:Lambdas"

\end_inset

.
 We move through this step-by-step to show what is going on here.
 First, let's parenthesize this to better see the pieces: 
\family typewriter
(
\backslash
$x.(
\backslash
$y.$x)).12
\family default
.
 Now we see that we have a lambda expression of the form 
\family typewriter

\backslash
$x.
\family default

\begin_inset Formula $b$
\end_inset


\family typewriter
.12
\family default
, where 
\begin_inset Formula $b$
\end_inset

 is the lambda body.
 This says to replace 
\family typewriter
$x
\family default
 with 
\family typewriter
12
\family default
 in the body.
 Replacing 
\family typewriter
$x
\family default
 with 
\family typewriter
12
\family default
 in the body (
\family typewriter
$y.$x
\family default
) gives 
\family typewriter
$y.12
\family default
, which is the answer.
\end_layout

\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status open

\begin_layout Plain Layout
\begin_inset Caption

\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "tab:Lambdas"

\end_inset

Lambdas
\end_layout

\end_inset


\begin_inset Tabular
<lyxtabular version="3" rows="4" columns="2">
<features tabularvalignment="middle">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<row>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Lambda Expression
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Value
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter

\backslash
$x.(7).12
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
7
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter

\backslash
$x.$x.12
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
12
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter

\backslash
$x.
\backslash
$y.$x.12
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter

\backslash
$y.12
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you enter 
\family typewriter

\backslash
$x.
\backslash
$y.$x.12
\family default
 at the Elision prompt, you will 
\emph on
not
\emph default
 see 
\family typewriter

\backslash
$y.12
\family default
.
 What you 
\emph on
will
\emph default
 see is 
\family typewriter

\backslash
$`:1`.12
\family default
.
 The 
\family typewriter
$y
\family default
 has been replaced with the funny variable 
\family typewriter
$`:1`
\family default
.
 This variable is a DeBruijn index, and it is used to prevent lambdas from
 
\begin_inset Quotes eld
\end_inset

capturing
\begin_inset Quotes erd
\end_inset

 variables.
 In practice you should not need to worry about DeBruijn indices; the system
 uses them when appropriate and keeps track of the details for you.
 If you are curious, please see 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:De-Bruijn-Indices"

\end_inset

.
\begin_inset Foot
status open

\begin_layout Plain Layout
For reasons now obvious, you should avoid variable names that start with
 colons.
 Elision uses these internally, and not just for DeBruijn indices, but also
 for 
\begin_inset Quotes eld
\end_inset

synthetic
\begin_inset Quotes erd
\end_inset

 rules and 
\begin_inset Quotes eld
\end_inset

synthetic
\begin_inset Quotes erd
\end_inset

 parameters created during matching.
 Partial rule completion is explained in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Rules-and-Strategies"

\end_inset

 and matching is explained in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Matching-and-Rewriting"

\end_inset

.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
A lambda parameter is 
\emph on
matched
\emph default
 against the argument, and the result is used to 
\emph on
rewrite
\emph default
 the body.
 This is all explained in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Matching-and-Rewriting"

\end_inset

, but in practice it means that if you specify the type of the parameter,
 then Elision will enforce this.
 Thus the lambda expression 
\family typewriter

\backslash
$x:INTEGER.$x.7
\family default
 will succeed with the value 7, while the lambda expression 
\family typewriter

\backslash
$x:INTEGER.$x."Fred"
\family default
 will fail with an error.
 This also means that the type of an atom can be extracted using a lambda.
 The following lambda will extract the type of any atom it is applied to.
\end_layout

\begin_layout LyX-Code

\backslash
$x:$T.$T
\end_layout

\begin_layout Standard
Thus the expression 
\family typewriter

\backslash
$x:$T.$T."Fred"
\family default
 evaluates to 
\family typewriter
STRING
\family default
.
\end_layout

\begin_layout Standard
The applicative dot binds right to left.
 For this reason, multiple parameter lambda expressions 
\emph on
may
\emph default
 need to be parenthesized when applied.
 Consider the following example.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> 
\backslash
$first.
\backslash
$second.%($first,$second).(2).(1)
\end_layout

\begin_layout Plain Layout

$_repl14 = %(2, 1)
\end_layout

\begin_layout Plain Layout

e> 
\backslash
$first.(
\backslash
$second.%($first,$second).2).(1)
\end_layout

\begin_layout Plain Layout

$_repl15 = %(1, 2)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
So what happened? The lambda dot binds more tightly than the applicative
 dot, and the applicative dot binds to the left, so in the first line the
 
\family typewriter
2
\family default
 become the argument to 
\family typewriter

\backslash
$first.
\backslash
$second.%($first,$second)
\family default
.
 This is rewritten to 
\family typewriter

\backslash
$second.%(2,$second)
\family default
.
 Parentheses in the second line force 
\family typewriter
2
\family default
 to be bound in the inner lambda first.
 This binding order was chosen so that arguments can, in the unparenthesized
 case, be given in the same order (left to right) as the parameters to which
 they bind.
\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
To create a lambda use 
\family typewriter
core.Lambda(param,body)
\family default
, where 
\family typewriter
param
\family default
 is the lambda parameter and 
\family typewriter
body
\family default
 is the lambda body.
 To apply a lambda to an argument, use 
\family typewriter
core.Apply(lambda,arg)
\family default
, where 
\family typewriter
lambda
\family default
 is the lambda expression and 
\family typewriter
arg
\family default
 is the argument.
 The following shows how several lambda expressions can be created in Scala.
\end_layout

\begin_layout Plain Layout
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="6" columns="2">
<features tabularvalignment="middle">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<row>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Lambda Expression
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Scala Code
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter

\backslash
$x.7
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
Lambda('x,7)
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter

\backslash
$x.$x
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
Lambda('x,'x)
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter

\backslash
$x.
\backslash
$y.$x
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
Lambda('x,Lambda('y,'x))
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter

\backslash
$x:INTEGER.$x.7
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
Apply(Lambda(Variable(INTEGER,"x"),'x),7)
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter

\backslash
$x:$T.$T."Fred"
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
Apply(Lambda(Variable('T,"x"),'T),"Fred")
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Section
Lambdas and Metavariables
\end_layout

\begin_layout Standard
It is often useful to use metavariables in lambdas.
 In fact, it is recommended to use a metavariable for the lambda parameter.
 Consider 
\family typewriter
is_bindable(atom)
\family default
.
 This evaluates to 
\family typewriter
true
\family default
 if the atom is bindable (that is, is a variable), and evaluates to 
\family typewriter
false
\family default
 if it is not.
 Suppose I want a function to tell me whether an atom is bindable or not.
 I might try to write this as follows: 
\family typewriter

\backslash
$a.is_bindable($a)
\family default
.
 This will not work.
 The term 
\family typewriter
is_bindable($x)
\family default
 immediately evaluates to true (since 
\family typewriter
$x
\family default
 is bindable), leaving the constant lambda 
\family typewriter

\backslash
$x.true
\family default
.
 This is not what we want at all.
\end_layout

\begin_layout Standard
The solution is to use metavariables (see 
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:Metavariables"

\end_inset

).
 We write 
\family typewriter

\backslash
$$x.is_bindable($$x)
\family default
.
 This works as desired.
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> 
\backslash
$x.is_bindable($x).7
\end_layout

\begin_layout Plain Layout

$_repl16 = true
\end_layout

\begin_layout Plain Layout

e> 
\backslash
$$x.is_bindable($$x).7
\end_layout

\begin_layout Plain Layout

$_repl15 = false
\end_layout

\end_inset

The first entry fails (because 
\family typewriter
7
\family default
 is not bindable), but the second entry works.
 Once you decide to use a metavariable in one place in a lambda, however,
 you must use it everywhere.
 The reason is that the lambda variables get rewritten to De Bruijn indices
 (see 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:De-Bruijn-Indices"

\end_inset

) based on the lambda parameter.
 The following illustrates how this can fail.
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> 
\backslash
$x.is_bindable($$x).7
\end_layout

\begin_layout Plain Layout

$_repl16 = true
\end_layout

\begin_layout Plain Layout

e> 
\backslash
$$x.is_bindable($x).7
\end_layout

\begin_layout Plain Layout

$_repl15 = true
\end_layout

\end_inset

In the first case a De Bruijn variable 
\family typewriter
$v
\family default
 is created for 
\family typewriter
$x
\family default
, and the body is rewritten to 
\family typewriter
is_bindable($v)
\family default
 which is true.
 The second case falls into the problem discussed earlier, where 
\family typewriter
is_bindable($x)
\family default
 is rewritten to 
\family typewriter
true
\family default
 before De Bruijn substitution can even occur.
\end_layout

\begin_layout Standard
The simple rule is to use metavariables consistently in lambdas.
 If you use a metavariable in the body, you must also use a metavariable
 for the parameter.
\end_layout

\begin_layout Chapter
\begin_inset CommandInset label
LatexCommand label
name "chap:Lists"

\end_inset

Collections
\end_layout

\begin_layout Standard
Elision provides a generalized collection type called, for lack of a better
 name, an 
\emph on
atom sequence
\emph default
.
 In its 
\begin_inset Quotes eld
\end_inset

default
\begin_inset Quotes erd
\end_inset

 form it is an ordered list of atoms, but this can be changed in a variety
 of ways by specifying the algebraic properties of the collection.
\end_layout

\begin_layout Section
The Basic Ordered Sequence
\end_layout

\begin_layout Standard
A basic ordered sequence of atoms is represented by a comma-separated list
 of atoms, enclosed in parentheses, and prefixed with a percent sign (
\family typewriter
%
\family default
).
 This 
\begin_inset Quotes eld
\end_inset

looks like
\begin_inset Quotes erd
\end_inset

 a 
\family typewriter
%
\family default
 operator applied to a list of atoms.
 For instance the list 
\family typewriter
1
\family default
 followed by 
\family typewriter
2
\family default
 can be represented with 
\family typewriter
%(1,2)
\family default
.
 Empty sequences are permissible, too: 
\family typewriter
%()
\family default
.
\end_layout

\begin_layout Standard
The collection can be heterogeneous.
 For instance 
\family typewriter
%(1,"Fred")
\family default
 is perfectly fine.
 The type of a collection is deduced by looking at the types of the contained
 elements.
 If they all have the same type 
\begin_inset Formula $T$
\end_inset

, then the type is 
\family typewriter
SEQ(
\family default

\begin_inset Formula $T$
\end_inset


\family typewriter
)
\family default
.
 If any has a different type, then the type of the collection is 
\family typewriter
SEQ(ANY)
\family default
.
\end_layout

\begin_layout Section
Algebraic Properties
\end_layout

\begin_layout Standard
Algebraic properties can be assigned to the sequence, and are specified
 starting with a percent sign.
 Actually, the leading percent sign for the basic ordered sequence is itself
 an algebraic properties specification, albeit a very simple one.
 Several properties are available, and the properties can even be 
\begin_inset Quotes eld
\end_inset

detached
\begin_inset Quotes erd
\end_inset

 from the sequence, matched, and rewritten.
 That is, an algebraic property specification is an atom on its own.
 Algebraic properties specifications look like operators, and even behave
 a bit like operators.
\end_layout

\begin_layout Standard
Each available property is described in more detail in the following subsections.
 Properties are specified by a single character, which is 
\emph on
not
\emph default
 case-sensitive, and can be negated by prefixing with an exclamation mark
 (
\family typewriter
!
\family default
).
 Properties are combined by juxtaposing them, and omitting a property altogether
 leaves it unspecified.
 The following table is a quick reference to the properties.
\end_layout

\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status open

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout
\begin_inset Caption

\begin_layout Plain Layout
Algebraic Properties
\end_layout

\end_inset


\begin_inset Tabular
<lyxtabular version="3" rows="6" columns="4">
<features tabularvalignment="middle">
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Property
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Character
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Can Be Negated
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Requires an Argument
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Associativity
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
A
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Yes
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
No
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Commutativity
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
C
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Yes
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
No
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Idempotency
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
I
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Yes
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
No
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Absorber
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
B
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
No
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Yes
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Identity
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
D
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
No
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Yes
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Properties may be given an argument in square brackets.
 For absorbers and identities, this will be the appropriate atom.
 For associativity, commutativity, and idempotency, this is typically either
 a Boolean literal or a variable for matching.
 The sense of the Boolean represents whether the property is present, so
 
\family typewriter
A
\family default
 alone is the same as 
\family typewriter
A[true]
\family default
, and 
\family typewriter
!A
\family default
 is the same as 
\family typewriter
A[false]
\family default
.
\end_layout

\begin_layout Standard
The order of properties is not significant, and conflicts are resolved with
 the last property specification winning.
 Thus 
\family typewriter
%AA!A
\family default
 is the same as 
\family typewriter
%!A
\family default
.
 Spaces are only permitted in the arguments to a property (inside the square
 brackets).
\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
Operator properties are specified by 
\family typewriter
core.AlgProp
\family default
.
 This class can be used directly, but it is typically easier to use its
 extensions: 
\family typewriter
Associative(bool)
\family default
, 
\family typewriter
Commutative(bool)
\family default
, 
\family typewriter
Idempotent(bool)
\family default
, 
\family typewriter
Absorber(atom)
\family default
, and 
\family typewriter
Identity(atom)
\family default
.
 The first three take a Boolean value, and the last two take an atom.
 Join these with 
\family typewriter
and
\family default
.
 The following builds the properties specification for integer addition,
 which is associative, commutative, not idempotent, and has an identity
 of zero.
\end_layout

\begin_layout LyX-Code
Associative(true) and Commutative(true) and Idempotent(false) and Identity(0)
\end_layout

\begin_layout Plain Layout
There is also an extension 
\family typewriter
NoProps
\family default
 that indicates no properties.
 This is useful if you don't care to specify any properties.
 Note that leaving a property unspecified is not the same as negating it;
 it just leaves the property unspecified.
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Associativity
\end_layout

\begin_layout Standard
An associative collection can have its elements grouped arbitrarily, provided
 the subgroups have the same algebraic properties specification.
 Associative collections are indicated with the symbol 
\family typewriter
A
\family default
.
 Thus we have 
\family typewriter
%A(5,2,%A(3,4),1)
\family default
 is the same as 
\family typewriter
%A(5,2,3,4,1)
\family default
.
 In fact, Elision will convert the former to the latter.
\begin_inset Newline newline
\end_inset


\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> %A(5,2,%A(3,4),1)
\end_layout

\begin_layout Plain Layout

$_repl0 = %A(5, 2, 3, 4, 1)
\end_layout

\begin_layout Plain Layout

e> %A(5,2,%(3,4),1)
\end_layout

\begin_layout Plain Layout

$_repl1 = %A(5, 2, %(3, 4), 1)
\end_layout

\end_inset

In the second line the properties specifications do not match, so Elision
 does not flatten the elements.
\end_layout

\begin_layout Subsection
Commutativity
\end_layout

\begin_layout Standard
A commutative collection can have its arguments re-ordered arbitrarily.
 Commutative collections are indicated with the symbol 
\family typewriter
C
\family default
.
 Thus 
\family typewriter
%C(1,2,3)
\family default
 is the same as 
\family typewriter
%C(3,2,1)
\family default
.
\end_layout

\begin_layout Subsection
Idempotency
\end_layout

\begin_layout Standard
An idempotent collection ignores element multiplicity.
 This is a complicated way of saying repeated elements do not matter.
 Idempotent collections are indicated with the symbol 
\family typewriter
I
\family default
.
 Thus 
\family typewriter
%I(1,2,2,3)
\family default
 is the same as 
\family typewriter
%I(1,2,3)
\family default
.
 In fact, Elision will discard repeated elements.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> %I(1,2,2,3)
\end_layout

\begin_layout Plain Layout

$_repl2 = %I(1, 2, 3)
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Identity
\end_layout

\begin_layout Standard
A special element may be designated as the identity.
 Including the identity in the sequence does not change its meaning.
 In fact, Elision will discard instances of the identity from the collection.
 An identity is indicated by the character 
\family typewriter
D
\family default
 followed by the identity element in square brackets.
 Thus 
\family typewriter
%D(1,0,0,3)
\family default
 is the same as 
\family typewriter
%(1,3)
\family default
.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> %D[0](1,0,0,3)
\end_layout

\begin_layout Plain Layout

$_repl3 = %D[0](1, 3)
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Absorber
\end_layout

\begin_layout Standard
Similar to an identity, a special element may be designated as an absorber.
 If an absorber is present, the meaning is the same as if 
\emph on
only
\emph default
 the absorber were present.
 Because of this, if Elision finds an absorber it dicards everything else
 (including other instances of the absorber) from the collection.
 An absorber is indicated by the character 
\family typewriter
B
\family default
 followed by the absorber element in square brackets.
 Thus 
\family typewriter
%B[0](1,0,0,3)
\family default
 is the same as 
\family typewriter
%B[0](0)
\family default
.
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
Yes, you can designate the same atom as both an identity and an absorber,
 but why? You will get a collection consisting of exactly one instance of
 the absorber, as absorber processing takes precedence.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> %B[0](1,0,0,3)
\end_layout

\begin_layout Plain Layout

$_repl4 = %B[0](0)
\end_layout

\end_inset


\end_layout

\begin_layout Section
Simple Collections
\end_layout

\begin_layout Standard
Using the algebraic properties we can construct some common collections.
 First, the specification 
\family typewriter
%CI
\family default
 denotes a set: a collection for which order and multiplicity are not significan
t.
 Sets within the set are preserved; if this is not desired, use 
\family typewriter
%ACI
\family default
.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> %CI(4,4,5,Red,"Joe",Blue,4,%CI(Red,Blue))
\end_layout

\begin_layout Plain Layout

$_repl5 = %CI(4, 5, Red:SYMBOL, "Joe", Blue:SYMBOL, %CI(Red:SYMBOL, Blue:SYMBOL)
)
\end_layout

\begin_layout Plain Layout

e> %ACI(4,4,5,Red,"Joe",Blue,4,%ACI(Red,Blue))
\end_layout

\begin_layout Plain Layout

$_repl6 = %ACI(4, 5, Red:SYMBOL, "Joe", Blue:SYMBOL)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If we omit idempotency or specify 
\emph on
not
\emph default
 idempotent with 
\family typewriter
!I
\family default
, then we have a multiset or bag, where multiple elements are preserved
 (though order still does no matter).
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> %C(4,4,5,Red,"Joe",Blue,4,%CI(Red,Blue))
\end_layout

\begin_layout Plain Layout

$_repl7 = %C(4, 4, 5, Red:SYMBOL, "Joe", Blue:SYMBOL, 4, %CI(Red:SYMBOL,
 Blue:SYMBOL))
\end_layout

\begin_layout Plain Layout

e> %AC(4,4,5,Red,"Joe",Blue,4,%AC(Red,Blue))
\end_layout

\begin_layout Plain Layout

$_repl8 = %AC(4, 4, 5, Red:SYMBOL, "Joe", Blue:SYMBOL, 4, Red:SYMBOL, Blue:SYMBO
L)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Omitting commutativity or specifying 
\emph on
not
\emph default
 commutative with 
\family typewriter
!C
\family default
 results in a list.
 If we want lists to be flattened, we can specify associativity.
 Likewise, if we want only the first instance of an element, we can specify
 idempotency.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> %(4,4,5,Red,"Joe",Blue,4,%(Red,Blue))
\end_layout

\begin_layout Plain Layout

$_repl9 = %(4, 4, 5, Red:SYMBOL, "Joe", Blue:SYMBOL, 4, %(Red:SYMBOL, Blue:SYMBO
L))
\end_layout

\begin_layout Plain Layout

e> %A(4,4,5,Red,"Joe",Blue,4,%A(Red,Blue))
\end_layout

\begin_layout Plain Layout

$_repl10 = %A(4, 4, 5, Red:SYMBOL, "Joe", Blue:SYMBOL, 4, Red:SYMBOL, Blue:SYMBO
L)
\end_layout

\begin_layout Plain Layout

e> %AI(4,4,5,Red,"Joe",Blue,4,%AI(Red,Blue))
\end_layout

\begin_layout Plain Layout

$_repl11 = %AI(4, 5, Red:SYMBOL, "Joe", Blue:SYMBOL)
\end_layout

\end_inset


\end_layout

\begin_layout Section
Properties Specifications as Operators
\end_layout

\begin_layout Standard
It was mentioned previously that the algebraic properties specification
 looks like an operator.
 In fact, it can function similarly to one, too.
 We use the applicative dot (
\family typewriter
.
\family default
) to apply it to another collection.
 Specified properties 
\emph on
override
\emph default
 the properties of the argument.
 For instance, if 
\family typewriter
%A
\family default
 is applied to 
\family typewriter
%C
\family default
, the result is 
\family typewriter
%AC
\family default
.
 Likewise, if 
\family typewriter
%A
\family default
 is applied to 
\family typewriter
%!AC
\family default
, the result is again 
\family typewriter
%AC
\family default
.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> %A.%C
\end_layout

\begin_layout Plain Layout

$_repl11 = %AC
\end_layout

\begin_layout Plain Layout

e> %A.%!AC
\end_layout

\begin_layout Plain Layout

$_repl12 = %AC
\end_layout

\begin_layout Plain Layout

e> %AD[0].%CD[2]
\end_layout

\begin_layout Plain Layout

$_repl13 = %ACD[0]
\end_layout

\begin_layout Plain Layout

e> (%A.%I).%(3,%AI(3),3)
\end_layout

\begin_layout Plain Layout

$_repl14 = %AI(3)
\end_layout

\begin_layout Plain Layout

e> %A.%I(3,%I(3),3)
\end_layout

\begin_layout Plain Layout

$_repl15 = %AI(3, %I(3))
\end_layout

\begin_layout Plain Layout

e> %A.%I(3,%AI(3),3)
\end_layout

\begin_layout Plain Layout

$_repl16 = %AI(3)
\end_layout

\end_inset


\end_layout

\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Long-Property-Specifications"

\end_inset

Long Property Specifications
\end_layout

\begin_layout Standard
A properties specification like 
\family typewriter
%AC!ID[0]
\family default
 is terse almost to the point of being unreadable.
 If a properties specification contains no variables or other complex terms,
 it can be written in an alternate form, replacing the letters with the
 entire property name, and negation with 
\family typewriter
not
\family default
.
 The above specification can be written in the following form.
\end_layout

\begin_layout LyX-Code
% associative, commutative, not idempotent, identity 0
\end_layout

\begin_layout Standard
The commas are required, and spaces are allowed.
 This form is much more readable, but also much longer.
 Note that absorbers are specified via the 
\family typewriter
absorber
\family default
 keyword, followed by the absorber atom.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> %associative.%commutative
\end_layout

\begin_layout Plain Layout

$_repl1 = %AC
\end_layout

\begin_layout Plain Layout

e> %associative.% not associative, commutative
\end_layout

\begin_layout Plain Layout

$_repl2 = %AC
\end_layout

\begin_layout Plain Layout

e> (%associative, identity 0).%commutative, identity 2
\end_layout

\begin_layout Plain Layout

$_repl3 = %ACD[0]
\end_layout

\begin_layout Plain Layout

e> (%associative.%idempotent).%(3,%associative,idempotent(3),3)
\end_layout

\begin_layout Plain Layout

$_repl4 = %AI(3)
\end_layout

\begin_layout Plain Layout

e> %associative.%idempotent(3,%idempotent(3),3)
\end_layout

\begin_layout Plain Layout

$_repl5 = %AI(3, %I(3))
\end_layout

\begin_layout Plain Layout

e> %associative.%idempotent(3,%idempotent, associative(3),3)
\end_layout

\begin_layout Plain Layout

$_repl6 = %AI(3)
\end_layout

\end_inset


\end_layout

\begin_layout Chapter
\begin_inset CommandInset label
LatexCommand label
name "chap:Operators"

\end_inset

Operators
\end_layout

\begin_layout Standard
In general, operators denote mappings on atoms.
 However, Elision manipulates operators symbolically, so they should be
 regarded as mathematical functions or symbols, and not in the computer
 language sense.
 Elision supports the following kinds of operator.
\end_layout

\begin_layout Itemize
A 
\emph on
symbolic
\emph default
 operator is simply an atom that is manipulated by the system through rewriting.
 A Scala 
\emph on
closure
\emph default
 can be provided to construct instances of the operator, making the operator
 a 
\emph on
native
\emph default
 operator.
 This is how arithmetic operators, for example, are implemented.
\end_layout

\begin_layout Itemize
An 
\emph on
immediate
\emph default
 or 
\emph on
case
\emph default
 operator denotes a kind of macro.
 One or more patterns are provided, and arguments are matched against patterns,
 in order.
 The result of the match is used to construct a new atom, which is the 
\begin_inset Quotes eld
\end_inset

value
\begin_inset Quotes erd
\end_inset

 of the operator application.
 Case operators provide for a kind of controlled polymorphism, and can operate
 in ways that a symbolic operator cannot.
\end_layout

\begin_layout Standard
Operators must be declared in the current context to be used by name.
 This is done via the built-in 
\family typewriter
decl
\family default
 operator.
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
Don't like this? Use the 
\begin_inset Quotes eld
\end_inset

autodefine
\begin_inset Quotes erd
\end_inset

 function of the REPL.
 Enable it by setting the 
\family typewriter
autoop
\family default
 property to 
\family typewriter
true
\family default
.
\end_layout

\end_inset

 This can be used in two ways: Either as 
\family typewriter
decl.oper
\family default
 or as 
\family typewriter
decl(oper)
\family default
, where 
\family typewriter
oper
\family default
 is the operator to declare.
 The dot form is preferred in the system libraries.
\end_layout

\begin_layout Standard
Operator redeclaration is permissible, but results in a warning.
 Finally, operators are a special form (see 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Special-Forms"

\end_inset

), so they may be specified in more than one way.
 In this chapter we present only one style of operator definition to simplify
 the discussion.
 Other forms are potentially more useful for matching and rewriting (see
 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Matching-and-Rewriting"

\end_inset

).
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> setprop("autoop", false)
\end_layout

\begin_layout Plain Layout

e> {operator #name=foo params=%($x)}
\end_layout

\begin_layout Plain Layout

$_repl1 = {: operator:SYMBOL { binds name -> foo:SYMBOL params -> %($x)
 type -> ANY } :}
\end_layout

\begin_layout Plain Layout

e> decl($_repl1)
\end_layout

\begin_layout Plain Layout

Declared operator foo.
\end_layout

\begin_layout Plain Layout

e> decl.$_repl1
\end_layout

\begin_layout Plain Layout

WARNING: Redefining operator foo.
\end_layout

\begin_layout Plain Layout

WARNING: Prior definition: {: operator:SYMBOL { binds name -> foo:SYMBOL
 params -> %($x)
\end_layout

\begin_layout Plain Layout

type -> ANY } :}
\end_layout

\begin_layout Plain Layout

Declared operator foo.
\end_layout

\begin_layout Plain Layout

e> foo:OPREF
\end_layout

\begin_layout Plain Layout

$_repl2 = foo:OPREF
\end_layout

\begin_layout Plain Layout

e> getop(foo:OPREF)
\end_layout

\begin_layout Plain Layout

$_repl3 = {: operator:SYMBOL { binds name -> foo:SYMBOL params -> %($x)
 type -> ANY } :}
\end_layout

\end_inset


\end_layout

\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Symbolic-Operators"

\end_inset

Symbolic Operators
\end_layout

\begin_layout Standard
A symbolic operator declaration must have the following elements.
\end_layout

\begin_layout Itemize
A 
\emph on
name
\emph default
, specified as a symbol.
 For example, 
\family typewriter
add
\family default
.
\end_layout

\begin_layout Itemize
A 
\emph on
type
\emph default
, which is the type of the fully-applied operator.
 For example, the type of the integer add operator is 
\family typewriter
INTEGER
\family default
.
\end_layout

\begin_layout Itemize
A 
\emph on
parameter list
\emph default
, which specifies both the parameter types and also the operator's algebraic
 properties.
\end_layout

\begin_layout Standard
To specify a symbolic operator, give these three items in the following
 form:
\end_layout

\begin_layout LyX-Code
{ operator #name=NAME #type=TYPE #params=PARAMS }
\end_layout

\begin_layout Standard
where 
\family typewriter
NAME
\family default
 is the operator name, 
\family typewriter
TYPE
\family default
 is the type of the fully-applied operator, and 
\family typewriter
PARAMS
\family default
 is the parameter collection.
 The algebraic properties of this collection are the algebraic properties
 of the operator.
 If the 
\family typewriter
#type
\family default
 is 
\emph on
not
\emph default
 declared, it is assumed to be 
\family typewriter
ANY
\family default
.
\end_layout

\begin_layout Standard
The following are some examples of common operators.
\end_layout

\begin_layout LyX-Code
{ operator #name=iadd #type=INTEGER
\end_layout

\begin_layout LyX-Code
  #params=%AC!ID[0]($x:INTEGER, $y:INTEGER) }
\end_layout

\begin_layout LyX-Code
{ operator #name=imul #type=INTEGER
\end_layout

\begin_layout LyX-Code
  #params=%AC!ID[1]B[0]($x:INTEGER, $y:INTEGER) }
\end_layout

\begin_layout LyX-Code
{ operator #name=and #type=BOOLEAN
\end_layout

\begin_layout LyX-Code
  #params=%ACID[true]B[false]($P:BOOLEAN, $Q:BOOLEAN) }
\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
To create a definition of a symbolic operator, use
\end_layout

\begin_layout Itemize

\family typewriter
core.TypedSymbolicOperator(name, type, parameters, description, detail)
\end_layout

\begin_layout Plain Layout
where 
\family typewriter
name
\family default
 is the operator's name (a string), 
\family typewriter
type
\family default
 is the type of the fully-applied operator (an atom), 
\family typewriter
parameters
\family default
 specifies both the operator's properties and the parameters and their types
 (it is an atom sequence), 
\family typewriter
description
\family default
 is the short one-line description of the operator, and 
\family typewriter
detail
\family default
 is the longer description of the operator and its use.
 The last two (
\family typewriter
description
\family default
 and 
\family typewriter
detail
\family default
) are optional.
 The following code creates the two examples given previously (the 
\family typewriter
or
\family default
 and 
\family typewriter
add
\family default
 operators).
\end_layout

\begin_layout LyX-Code
import ornl.elision.core._
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code
// Make the Boolean inclusive or operator.
\end_layout

\begin_layout LyX-Code
val orOp = TypedSymbolicOperator("or", BOOLEAN,
\end_layout

\begin_layout LyX-Code
  AtomSeq(Associative(true) and Commutative(true) and Idempotent(true)
\end_layout

\begin_layout LyX-Code
          and Absorber(true) and Identity(false),
\end_layout

\begin_layout LyX-Code
          Variable(BOOLEAN,"P"), Variable(BOOLEAN,"Q")),
\end_layout

\begin_layout LyX-Code
  "Compute the Boolean inclusive OR.",
\end_layout

\begin_layout LyX-Code
  """|This operator computes the Boolean inclusive OR of its arguments.
\end_layout

\begin_layout LyX-Code
     |All arguments must be Boolean values.""".stripMargin)
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code
// Make the integer add operator definition.
\end_layout

\begin_layout LyX-Code
val addOp = TypedSymbolicOperator("add", INTEGER,
\end_layout

\begin_layout LyX-Code
  AtomSeq(Associative(true) and Commutative(true) and Idempotent(false)
\end_layout

\begin_layout LyX-Code
          and Identity(0), Variable(INTEGER,"x"), Variable(INTEGER,"y")),
\end_layout

\begin_layout LyX-Code
  "Compute the integer sum of the arguments.",
\end_layout

\begin_layout LyX-Code
  """|Compute the integer sum of the arguments.""".stripMargin)
\end_layout

\begin_layout Plain Layout
Operator definitions should be installed in an instance of 
\family typewriter
core.OperatorLibrary
\family default
, typically found in an instance of 
\family typewriter
core.Context
\family default
.
 A context is automatically created and provided by the REPL, so if you
 are interacting with the REPL you do not need to worry about this.
 Contexts and operator libraries are explained in more detail in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Contexts"

\end_inset

.
 If you have a context instance, you can install a new operator by first
 getting the operator library from the context with 
\family typewriter
operatorLibrary
\family default
, and then invoking 
\family typewriter
add(opdef)
\family default
 on the instance, where 
\family typewriter
opdef
\family default
 is the operator definition.
\end_layout

\begin_layout Plain Layout
For instance, if 
\family typewriter
context
\family default
 is an instance of 
\family typewriter
core.Context
\family default
, then the operators defined above can be installed with the following lines
 of code.
\end_layout

\begin_layout LyX-Code
// Install definitions.
\end_layout

\begin_layout LyX-Code
context.operatorLibrary.add(orOp)
\end_layout

\begin_layout LyX-Code
context.operatorLibrary.add(addOp)
\end_layout

\begin_layout Plain Layout
The operator library is also where you register a closure for a symbolic
 operator.
 The closure must take an instance of 
\family typewriter
core.ApplyData
\family default
 and return an instance of 
\family typewriter
core.BasicAtom
\family default
.
 More details on this are given in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Native-Handlers"

\end_inset

.
 You register the native handler using the 
\family typewriter
core.OperatorLibrary.register(name, handler)
\family default
 instance method, where 
\family typewriter
name
\family default
 is the (string) name of the operator, and 
\family typewriter
handler
\family default
 is the closure described above.
 The following registers a native constructor for 
\family typewriter
add
\family default
, but does use some methods not explained just yet.
\end_layout

\begin_layout LyX-Code
// Define add as a symbolic operator.
\end_layout

\begin_layout LyX-Code
context.operatorLibrary.register("add",
\end_layout

\begin_layout LyX-Code
  (data: ApplyData) => {
\end_layout

\begin_layout LyX-Code
    // Accumulate the integer literals found.
\end_layout

\begin_layout LyX-Code
	var lits:BigInt = 0
\end_layout

\begin_layout LyX-Code
	// Accumulate other atoms found.
\end_layout

\begin_layout LyX-Code
	var other = IndexedSeq[BasicAtom]()
\end_layout

\begin_layout LyX-Code
	// Traverse the list and divide the atoms.
\end_layout

\begin_layout LyX-Code
	data.args.foreach {
\end_layout

\begin_layout LyX-Code
	  x => x match {
\end_layout

\begin_layout LyX-Code
	    case IntegerLiteral(_, value) => lits += value
\end_layout

\begin_layout LyX-Code
	    case _ => other :+= x
\end_layout

\begin_layout LyX-Code
	  }
\end_layout

\begin_layout LyX-Code
	}
\end_layout

\begin_layout LyX-Code
	// Now add the accumulated literals to the list.
\end_layout

\begin_layout LyX-Code
	other :+= Literal(INTEGER, lits)
\end_layout

\begin_layout LyX-Code
	// Construct and return a new operator application.
\end_layout

\begin_layout LyX-Code
	Apply(op, AtomSeq(NoProps, other), true)
\end_layout

\begin_layout LyX-Code
})
\end_layout

\begin_layout Plain Layout
It is the job of the 
\family typewriter
core.Apply
\family default
 class to create operator (and other) applications.
 While this is explained in more detail in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:The-Applicative-Dot"

\end_inset

, we note some important things here.
\end_layout

\begin_layout Plain Layout
First, 
\family typewriter
core.Apply
\family default
 understands how to use the operator to process absorbers and identities,
 etc., and this processing is performed 
\emph on
first
\emph default
.
 Thus it is possible to attempt to construct a symbolic operator application
 with a native constructor and never have the native constructor get invoked.
 For instance, 
\family typewriter
add(0)
\family default
 is immediately rewritten to 
\family typewriter
0
\family default
, and the native constructor is never invoked.
\end_layout

\begin_layout Plain Layout
Second, the native constructor may 
\emph on
re
\emph default
-invoke 
\family typewriter
core.Apply
\family default
, as is done in the handler for 
\family typewriter
add
\family default
 shown above.
 This can simplify the native constructor since it does not have to worry
 about identities, etc.
 In the 
\family typewriter
add
\family default
 constructor, the result for 
\family typewriter
lits
\family default
 might be zero.
 By re-invoking 
\family typewriter
core.Apply
\family default
 it will get correctly processed.
\end_layout

\begin_layout Plain Layout
This second case leads to a potential problem.
 The 
\family typewriter
core.Apply
\family default
 processing will invoke the native constructor, and our native constructor
 invokes 
\family typewriter
core.Apply
\family default
.
 To prevent this recursion we pass 
\family typewriter
true
\family default
 as the optional third argument to 
\family typewriter
core.Apply
\family default
 to prevent re-invoking the native constructor.
 It is thus possible to write a native constructor that does some processing,
 lets itself get re-invoked, does more processing, etc., until it finally
 terminates the cycle.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The properties specified for the operator are interpreted a bit differently
 from how they are interpreted for collections.
 
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:Operator-Properties"

\end_inset

 explains how they are interpreted.
\end_layout

\begin_layout Standard
Symbolic operators can be defined using a much more terse syntax.
 In this form the prototype is written directly, and the name, parameters,
 and type are pulled from it.
 For instance, the prototype 
\family typewriter
imul($x:INTEGER, $y:INTEGER):INTEGER
\family default
 specifies the name, parameters and their types, and the type of the fully-appli
ed operator.
 Note that it does 
\emph on
not
\emph default
 specify the properties of the operator.
 Those are optionally specified by following the prototype with 
\family typewriter
is
\family default
 and then the algebraic properties specification.
 Use 
\family typewriter
{!
\family default
...
\family typewriter
}
\family default
 to enclose the entire operator definition.
 The three operators given previously can be written as follows using this
 new syntax.
\end_layout

\begin_layout LyX-Code
{! iadd($x:INTEGER, $y:INTEGER):INTEGER is %AC!ID[0] }
\end_layout

\begin_layout LyX-Code
{! imul($x:INTEGER, $y:INTEGER):INTEGER is %AC!ID[1]B[0] }
\end_layout

\begin_layout LyX-Code
{! and($P:BOOLEAN, $Q:BOOLEAN):BOOLEAN is %ACID[true]B[false] }
\end_layout

\begin_layout Standard
If you use long property specifications (see 
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:Long-Property-Specifications"

\end_inset

) then you are allowed to drop the leading 
\family typewriter
%
\family default
.
\end_layout

\begin_layout LyX-Code
{! iadd($x:INTEGER, $y:INTEGER):INTEGER is
\end_layout

\begin_layout LyX-Code
   associative, commutative, not idempotent, identity 0}
\end_layout

\begin_layout LyX-Code
{! imul($x:INTEGER, $y:INTEGER):INTEGER is
\end_layout

\begin_layout LyX-Code
   associative, commutative, not idempotent,
\end_layout

\begin_layout LyX-Code
   identity 1, absorber 0}
\end_layout

\begin_layout LyX-Code
{! and($P:BOOLEAN, $Q:BOOLEAN):BOOLEAN is
\end_layout

\begin_layout LyX-Code
   associative, commutative, idempotent,
\end_layout

\begin_layout LyX-Code
   identity true, absorber false}
\end_layout

\begin_layout Standard
This is much more readable, but also much longer.
\end_layout

\begin_layout Standard
After specifying the prototype the description and details may be specified
 as usual.
 In fact, the type can be specified in the usual manner (with 
\family typewriter
#type
\family default
), if desired.
\end_layout

\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Operator-Properties"

\end_inset

Operator Properties
\end_layout

\begin_layout Standard
As with collections, operators have associated algebraic properties; in
 fact, they are the same as those for sequences, and are specified in the
 same manner.
 For example, addition is associative, commutative, not idempotent, and
 has an identity of zero: 
\family typewriter
%AC!ID[0]
\family default
.
 Multiplication is associative, commutative, not idempotent, has an identity
 of one, and an absorber of zero: 
\family typewriter
%d[1]b[0]!ica
\family default
.
 Boolean logical or is associative, commutative, idempotent, has an identity
 of false and an absorber of true: 
\family typewriter
%ACID[false]B[true]
\family default
.
\end_layout

\begin_layout Standard
Each property is described in more detail in the following subsections as
 it applies to operators.
 There are restrictions on the properties of operators that are not present
 for collections (specifically, associativity is required in many cases),
 and these are discussed in the following subsections.
\end_layout

\begin_layout Subsection
Associativity
\end_layout

\begin_layout Standard
An associative operator 
\begin_inset Formula $f$
\end_inset

 can have its arguments grouped arbitrarily.
 Thus 
\begin_inset Formula $f(a,b,c)=f(f(a,b),c)=f(a,f(b,c))$
\end_inset

.
 Note that any argument could be replaced with another application, so any
 number of arguments is possible.
\end_layout

\begin_layout Standard
Suppose we define operator 
\begin_inset Formula $f$
\end_inset

 to have prototype 
\begin_inset Formula $f(a:A,b:B):F$
\end_inset

.
 Since we can replace either 
\begin_inset Formula $a$
\end_inset

 or 
\begin_inset Formula $b$
\end_inset

 with another application of 
\begin_inset Formula $f$
\end_inset

, we conclude that 
\begin_inset Formula $F\subseteq A$
\end_inset

 and 
\begin_inset Formula $F\subseteq B$
\end_inset

.
 We further note the following, by associativity.
\begin_inset Formula 
\[
f(f(c:A,d:B),b:B)=f(c:A,f(d:B,b:B))
\]

\end_inset

Thus it must be the case that 
\begin_inset Formula $B\subseteq A$
\end_inset

.
 By a similar argument we conclude that 
\begin_inset Formula $A\subseteq B$
\end_inset

, and thus 
\begin_inset Formula $A=B$
\end_inset

.
 For these reasons we require that all parameters of an associative operator
 have the same type, and that the parameter type must be the same as the
 overall operator type.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> { operator #name=bad1 #type=INTEGER
\end_layout

\begin_layout Plain Layout

 >   #params=%A($x: INTEGER, $y: STRING) }
\end_layout

\begin_layout Plain Layout

ERROR: The operator bad1 is marked as associative, but all parameters
\end_layout

\begin_layout Plain Layout

do not hae the same type, as required: %A($x:INTEGER, $y:STRING)
\end_layout

\begin_layout Plain Layout

e> { operator #name=bad2 #type=STRING
\end_layout

\begin_layout Plain Layout

 >   #params=%A($x: INTEGER, $y: INTEGER) }
\end_layout

\begin_layout Plain Layout

ERROR: The operator bad2 is marked as associative, but the parameter
\end_layout

\begin_layout Plain Layout

type (INTEGER) is not the same as the fully-applied type (STRING).
\end_layout

\end_inset


\end_layout

\begin_layout Standard
An associative operator must declare 
\emph on
exactly
\emph default
 two parameters.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> { operator #name=bad3 #type=INTEGER
\end_layout

\begin_layout Plain Layout

 >   #params=%A($x: INTEGER) }
\end_layout

\begin_layout Plain Layout

ERROR: The operator bad3 is marked as associative, but does not have
\end_layout

\begin_layout Plain Layout

exactly two parameters, as required: %A($x:INTEGER)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Associativity is 
\emph on
required
\emph default
 by idempotency, any identity, and any absorber.
\end_layout

\begin_layout Subsection
Commutativity
\end_layout

\begin_layout Standard
A commutative (or abelian) operator 
\begin_inset Formula $f$
\end_inset

 can have its arguments re-ordered arbitrarily.
 Thus 
\begin_inset Formula $f(a,b)=f(b,a)$
\end_inset

.
 If we provide type information, we see the following: 
\begin_inset Formula $f(a:A,b:B)=f(b:B,a:A)$
\end_inset

, and we conclude that 
\begin_inset Formula $A\subseteq B$
\end_inset

 and 
\begin_inset Formula $B\subseteq A$
\end_inset

, or 
\begin_inset Formula $A=B$
\end_inset

.
 We thus require that all arguments to a commutative operator have the same
 type, though this need not be the type of the fully-applied operator.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> { operator #name=bad #type=STRING
\end_layout

\begin_layout Plain Layout

 >   #params=%C($x: INTEGER, $y: STRING) }
\end_layout

\begin_layout Plain Layout

ERROR: The operator bad is marked as commutative, but all parameters
\end_layout

\begin_layout Plain Layout

do not hae the same type, as required: %C($x:INTEGER, $y:STRING)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
A commutative operator must declare 
\emph on
at least
\emph default
 two parameters.
\end_layout

\begin_layout Subsection
Idempotency
\end_layout

\begin_layout Standard
An idempotent operator 
\begin_inset Formula $f$
\end_inset

 has the property that 
\begin_inset Formula $f(a,a)=f(a)$
\end_inset

, so repeated arguments are discarded.
 Because the length of the argument list can change, idempotent operators
 are required to be associative.
 An example of an idempotent operator is the Boolean inclusive 
\emph on
or
\emph default
, since 
\begin_inset Formula $\mbox{or}(x,y,x)=\mbox{or}(x,y)$
\end_inset

.
 Idempotency imposes no additional restrictions on an operator beyond those
 imposed by associativity, which is required.
\end_layout

\begin_layout Standard
As an example, we implement multisets and sets using symbolic operators.
 A 
\emph on
multiset
\emph default
 allows repeated elements to be present.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> def({ operator #name=mset #params=%AC($x,$y) })
\end_layout

\begin_layout Plain Layout

e> mset(7, fred, "James", blue, 7, blue)
\end_layout

\begin_layout Plain Layout

$_repl18 = mset(7, fred:SYMBOL, "James", blue:SYMBOL, 7, blue:SYMBOL)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
A 
\emph on
set
\emph default
 does not allow repeated elements.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> def({ operator #name=set #params=%ACI($x,$y) })
\end_layout

\begin_layout Plain Layout

e> set(7, fred, "James", blue, 7, blue)
\end_layout

\begin_layout Plain Layout

$_repl19 = set(7, fred:SYMBOL, "James", blue:SYMBOL)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Including idempotency in the list of properties allows a simple implementation
 of sets.
 Examples of idempotent operators are the logical 
\emph on
or
\emph default
 and 
\emph on
and
\emph default
.
\end_layout

\begin_layout Subsection
Identity
\end_layout

\begin_layout Standard
An operator 
\begin_inset Formula $f$
\end_inset

 can have an associated named identity element 
\begin_inset Formula $e$
\end_inset

, with the property that 
\begin_inset Formula $f(x,e)=f(e,x)=f(x)=x$
\end_inset

.
 Instances of a named identity are discarded from the argument list.
 Because the length of the argument list can change, only associative operators
 can have a named identity.
\end_layout

\begin_layout Standard
Named identity elements include 
\emph on
zero
\emph default
 for addition, 
\emph on
one
\emph default
 for multiplication, 
\emph on
false
\emph default
 for Boolean inclusive 
\emph on
or
\emph default
, and 
\emph on
true
\emph default
 for Boolean 
\emph on
and
\emph default
.
\end_layout

\begin_layout Standard
Further, 
\begin_inset Formula $f()$
\end_inset

 is regarded as an alternate name for a named identity 
\begin_inset Formula $e$
\end_inset

.
 The type of the identity must match the parameter type.
\end_layout

\begin_layout Subsection
Absorber
\end_layout

\begin_layout Standard
An operator 
\begin_inset Formula $f$
\end_inset

 can have an associated absorber element 
\begin_inset Formula $z$
\end_inset

, with the property that 
\begin_inset Formula $f(x,z)=f(z,x)=z$
\end_inset

.
 If an absorber is present in the argument list then the entire operator
 application is reduced to the absorber.
 Elision currently requires that operators with absorbers be associative,
 though this is not essential for any mathematical reason.
\end_layout

\begin_layout Standard
Absorber elements include zero for multiplication, true for Boolean inclusive
 or, and false for Boolean and.
 The type of the absorber must match the parameter type.
\end_layout

\begin_layout Subsection
Construction
\end_layout

\begin_layout Standard
Atoms are transformed when entered, based on their properties, before any
 other processing, including a native handler, is performed.
 Suppose we have the following definitions.
\end_layout

\begin_layout LyX-Code
decl.{operator #name=foo
\end_layout

\begin_layout LyX-Code
      #params=%AD[0]($x:INTEGER,$y:INTEGER)
\end_layout

\begin_layout LyX-Code
      #type=INTEGER}
\end_layout

\begin_layout LyX-Code
decl.{operator #name=bar
\end_layout

\begin_layout LyX-Code
      #params=%AB[true]($x:BOOLEAN,$y:BOOLEAN)
\end_layout

\begin_layout LyX-Code
      #type=BOOLEAN}
\end_layout

\begin_layout Standard
We observe the following based on these definitions.
\end_layout

\begin_layout Itemize

\family typewriter
foo($x:INTEGER, foo($y:INTEGER, $z:INTEGER))
\family default
 becomes 
\family typewriter
foo($x:INTEGER, $y:INTEGER, $z:INTEGER)
\family default
 because associative applications are 
\begin_inset Quotes eld
\end_inset

flattened.
\begin_inset Quotes erd
\end_inset


\end_layout

\begin_layout Itemize

\family typewriter
foo(5,0,2)
\family default
 becomes 
\family typewriter
foo(5,2)
\family default
 because identities are discarded.
\end_layout

\begin_layout Itemize

\family typewriter
bar(true, false, $x:BOOLEAN)
\family default
 becomes 
\family typewriter
true
\family default
 because 
\family typewriter
true
\family default
 is an absorber.
\end_layout

\begin_layout Itemize

\family typewriter
foo(0,0,0)
\family default
 becomes 
\family typewriter
0
\family default
 because discarding identities leaves 
\family typewriter
foo()
\family default
, which is equal to the identity 
\family typewriter
0
\family default
.
\end_layout

\begin_layout Standard
Once this processing is complete, the system applies any native handler
 (see 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Native-Handlers"

\end_inset

).
\end_layout

\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Operator-Applications"

\end_inset

Operator Applications
\end_layout

\begin_layout Standard
Once an operator is defined, it can be applied to arguments.
 If the arguments match the parameters then the operator is fully applied
 and a new atom is created called an 
\emph on
apply
\emph default
.
 Assuming the 
\family typewriter
and
\family default
, 
\family typewriter
or
\family default
, and 
\family typewriter
typeof
\family default
 operators given in the previous section are defined, the following are
 all valid applications.
\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="1" columns="4">
<features tabularvalignment="middle" tabularwidth="80col%">
<column alignment="left" valignment="top" width="0pt">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0pt">
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
add(4,5,$x)
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
or($x,false)
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
typeof(6)
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
typeof(add($x,9))
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Standard
Because of the properties of the 
\family typewriter
or
\family default
 operator, the second term 
\family typewriter
or($x,false)
\family default
 immediately reduces to 
\family typewriter
$x
\family default
.
 The last two reduce immediately to 
\family typewriter
INTEGER
\family default
.
\end_layout

\begin_layout Standard
Operator applications can be nested, provided types match.
 The following is an example.
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
Note that this example is immediately reduced to 
\family typewriter
false
\family default
 independent of any bindings for 
\family typewriter
$x
\family default
 and 
\family typewriter
$y
\family default
 because 
\family typewriter
equal
\family default
 is evaluated with constructed, and thus prior to the result being rewritten
 with the current bindings.
 To prevent this, use metavariables (see 
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:Metavariables"

\end_inset

).
\end_layout

\end_inset


\end_layout

\begin_layout LyX-Code
or(equal(add($x,21),64),equal(add($y,17),32))
\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
Operator application is explained in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:The-Applicative-Dot"

\end_inset

.
\end_layout

\begin_layout Plain Layout
Before an operator can be applied, you must get an instance of that operator.
 If you have installed the operator definition in an operator library, you
 can retrieve it via either the 
\family typewriter
get(name)
\family default
 instance method of 
\family typewriter
core.OperatorLibrary
\family default
, or via the 
\family typewriter
apply(name)
\family default
 instance method, where 
\family typewriter
name
\family default
 is the operator name.
 The 
\family typewriter
get(name)
\family default
 method returns an optional 
\family typewriter
core.OperatorRef
\family default
, returning 
\family typewriter
None
\family default
 if the operator is not known.
 The 
\family typewriter
apply(name)
\family default
 method will will return an instance of 
\family typewriter
core.OperatorRef
\family default
, or throw an exception if the operator is not known.
\end_layout

\begin_layout Plain Layout
The operator itself can be obtained from the 
\family typewriter
core.OperatorRef
\family default
 instance via its 
\family typewriter
operator
\family default
 field.
 The following are two ways to obtain the 
\family typewriter
add
\family default
 operator, given a context instance 
\family typewriter
context
\family default
.
\end_layout

\begin_layout LyX-Code
context.operatorLibrary.get("add") match {
\end_layout

\begin_layout LyX-Code
  case Some(opref) => // Do something with the operator opref.operator
\end_layout

\begin_layout LyX-Code
  case None => // The operator is not known!
\end_layout

\begin_layout LyX-Code
}
\end_layout

\begin_layout LyX-Code
// The following throws an UndefinedOperatorException if
\end_layout

\begin_layout LyX-Code
// add is not known.
\end_layout

\begin_layout LyX-Code
context.operatorLibrary("add").operator
\end_layout

\begin_layout Plain Layout
Of course, you probably don't need (or even want) the actual operator; a
 reference to the operator is sufficient.
\end_layout

\begin_layout Plain Layout
Once you have the operator reference, you can apply it to arguments by just
 listing the arguments in parentheses after the reference, thus implicitly
 invoking the operator's (or reference's) 
\family typewriter
apply
\family default
 method.
 You can also use the 
\family typewriter
core.Apply
\family default
 class as explained in the next section.
 The following adds some numbers.
\end_layout

\begin_layout LyX-Code
context.operatorLibrary("add")(2,2,9)
\end_layout

\end_inset


\end_layout

\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:The-Applicative-Dot"

\end_inset

The Applicative Dot
\end_layout

\begin_layout Standard
Operator applications can be written in two forms: 
\family typewriter
add(4,5,$x)
\family default
 and 
\family typewriter
add.%(4,5,$x)
\family default
.
 This second form uses the 
\emph on
applicative dot
\emph default
 and a collection to apply an operator to arguments.
 The two forms are equivalent; they are alternative ways to represent the
 same atom.
 The first form is actually a shorthand notation for the second.
 Both operators and atom lists are themselves atoms, and can be manipulated
 by the system.
 In 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Matching-and-Rewriting"

\end_inset

 the applicative dot notation will turn out to be very useful.
\end_layout

\begin_layout Standard
While operators are atoms, if you just evaluate 
\family typewriter
add
\family default
 by itself Elision will usually interpret this as a symbol of type 
\family typewriter
SYMBOL
\family default
.
 To force Elision to look this operator up, write 
\family typewriter
add:OPREF
\family default
.
 The 
\family typewriter
OPREF
\family default
 is not actually the type of the operator, but just a hint to force the
 Elision parser to look up the operator in the parser's context.
 If the operator is not known, an error is reported.
 The built in operator 
\family typewriter
getop
\family default
 can be used to get the actual operator from an operator reference.
\end_layout

\begin_layout Standard
The type of an operator
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
There are two exceptions.
 The operators 
\family typewriter
MAP
\family default
 and 
\family typewriter
xx
\family default
 are used to represent the type of operators, so they get special treatment.
 Their type is 
\family typewriter
ANY
\family default
.
\end_layout

\end_inset

 is a 
\emph on
mapping
\emph default
 from some domain to some range, deduced from the operator prototype.
 This can be obtained using the lambda trick presented in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:Lambdas"

\end_inset

.
 With 
\family typewriter
add
\family default
 defined in the current REPL session, try the following.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> 
\backslash
$x:$T.$T.getop(add:OPREF)
\end_layout

\begin_layout Plain Layout

repl0 = MAP(xx(INTEGER, INTEGER), INTEGER)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The type for the 
\family typewriter
add
\family default
 operator is a mapping from pairs of integers to integers.
 The above expression parses correctly because the applicative dot binds
 the most weakly of all connectors; more weakly than the lambda dot, for
 instance, which binds more weakly than the type colon.
 Thus the expression is equal to the following.
\end_layout

\begin_layout LyX-Code
(
\backslash
$x:$T.$T).(getop(add:OPREF))
\end_layout

\begin_layout Standard
The applicative dot can be used to 
\begin_inset Quotes eld
\end_inset

glue
\begin_inset Quotes erd
\end_inset

 any two atoms together.
 The atom to the left of the dot is the 
\emph on
left-hand side (lhs)
\emph default
, while the atom to the right of the dot is the 
\emph on
right-hand side (rhs)
\emph default
.
 For instance the following are perfectly legal applications, though it
 is not entirely clear what the first and last examples 
\begin_inset Quotes eld
\end_inset

mean.
\begin_inset Quotes erd
\end_inset

 The parentheses are used in the first example to prevent 
\family typewriter
7.

\family default
 from being interpreted as a floating point number; a space between the
 
\family typewriter
7
\family default
 and the dot would also work.
\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="1" columns="4">
<features tabularvalignment="middle" tabularwidth="80col%">
<column alignment="left" valignment="top" width="0pt">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0pt">
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
(7).$x
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
(
\backslash
$x:$T.$T).getop(add:OPREF)
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
add.%(5,6)
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
$x.$y
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Standard
In 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Special-Forms"

\end_inset

 we will introduce several other uses of the applicative dot.
\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
To create an apply using the applicative dot, use the 
\family typewriter
core.Apply(lhs,rhs)
\family default
 constructor, where 
\family typewriter
lhs
\family default
 is the left-hand side, and 
\family typewriter
rhs
\family default
 is the right-hand side.
 Here are the Scala code equivalents for the apply examples given previously.
\end_layout

\begin_layout LyX-Code
// (7).$x
\end_layout

\begin_layout LyX-Code
Apply(7,'x)
\end_layout

\begin_layout LyX-Code

\family typewriter
// (
\backslash
$x:$T.$T).getop(add:OPREF)
\end_layout

\begin_layout LyX-Code
Apply(Lambda(Variable('T,"x"),'T),
\end_layout

\begin_layout LyX-Code
  context.operatorLibrary("getop")(Literal(OPREF,'add)))
\end_layout

\begin_layout LyX-Code
// add.%(5,6)
\end_layout

\begin_layout LyX-Code
Apply(context.operatorLibrary("add"), AtomSeq(NoProps, 5, 6))
\end_layout

\begin_layout LyX-Code
// $x.$y
\end_layout

\begin_layout LyX-Code
Apply('x,'y)
\end_layout

\end_inset


\end_layout

\begin_layout Section
Operators, Symbols, and Naked Symbols
\end_layout

\begin_layout Standard
If you type a symbol at the REPL prompt without type, this is regarded as
 a 
\begin_inset Quotes eld
\end_inset

naked
\begin_inset Quotes erd
\end_inset

 symbol, and is subject to special treatment.
 If the naked symbol appears on the left-hand side of an apply, the system
 will attempt to interpret it as an operator reference, and will look it
 up in the context.
 If it is not found, it will issue an error.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> fred
\end_layout

\begin_layout Plain Layout

$_repl14 = fred:SYMBOL
\end_layout

\begin_layout Plain Layout

e> fred(5)
\end_layout

\begin_layout Plain Layout

ERROR: The operator fred is not known.
\end_layout

\begin_layout Plain Layout

e> fred.james
\end_layout

\begin_layout Plain Layout

ERROR: The operator fred is not known.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To overcome this explicitly give the type of the symbol.
 Any type will suppress this behavior, but the most common (and obvious)
 type is 
\family typewriter
SYMBOL
\family default
.
 Enclosing the symbol in parentheses only helps with the simple operator
 application, and not with the applicative dot.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> fred:SYMBOL.james
\end_layout

\begin_layout Plain Layout

$_repl15 = (fred:SYMBOL.james:SYMBOL)
\end_layout

\begin_layout Plain Layout

e> (fred)(5)
\end_layout

\begin_layout Plain Layout

$_repl16 = fred:SYMBOL
\end_layout

\begin_layout Plain Layout

$_repl17 = 5
\end_layout

\begin_layout Plain Layout

e> (fred).5
\end_layout

\begin_layout Plain Layout

ERROR: The operator fred is not known.
\end_layout

\begin_layout Plain Layout

e> (fred:SYMBOL).5
\end_layout

\begin_layout Plain Layout

$_repl18 = (fred:SYMBOL.5)
\end_layout

\begin_layout Plain Layout

e> fred:SYMBOL(5)
\end_layout

\begin_layout Plain Layout

ERROR: The operator SYMBOL is not known.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The last line above is included just to emphasize that types are themselves
 atoms, and are subject to the same parsing rules.
 Entering 
\family typewriter
fred:SYMBOL:^TYPE(5)
\family default
 does, however, yield two atoms because 
\family typewriter
^TYPE
\family default
 is treated specially.
\end_layout

\begin_layout Standard
The opposite of this is to explicitly state that a symbol is an operator
 reference, using 
\family typewriter
OPREF
\family default
.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> (fred:OPREF)(5)
\end_layout

\begin_layout Plain Layout

ERROR: The operator fred is not known.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
You may be wondering why Elision doesn't simply treat a naked symbol as
 a simple symbol when there is no operator with that name, so 
\family typewriter
fred.5
\family default
 would be accepted.
 The reason is that if an operator with name 
\family typewriter
fred
\family default
 were later defined then the interpretation would be fundamentally changed
 (from a symbol to an operator), and the Elision design seeks to avoid that.
 This could 
\begin_inset Quotes eld
\end_inset

break
\begin_inset Quotes erd
\end_inset

 existing files of definitions and terms.
\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
The special type 
\family typewriter
OPREF
\family default
 is one place where the Scala API and REPL deviate.
 Consider the following code.
\end_layout

\begin_layout LyX-Code
Apply(Literal(OPREF, 'fred), Literal(5)).toParseString
\end_layout

\begin_layout Plain Layout
This yields the output 
\begin_inset Quotes eld
\end_inset


\family typewriter
(fred:OPREF.5)
\family default
,
\begin_inset Quotes erd
\end_inset

 but this fails the 
\begin_inset Quotes eld
\end_inset

round trip
\begin_inset Quotes erd
\end_inset

 test; parsing this string results in an attempt to look up the 
\family typewriter
fred
\family default
 operator in the current context.
\end_layout

\begin_layout Plain Layout
This difficulty arises from the fact that there is no 
\begin_inset Quotes eld
\end_inset

universal
\begin_inset Quotes erd
\end_inset

 context.
 The REPL and the parser have a context where they can look up 
\family typewriter
fred
\family default
, but the overall API does not.
\end_layout

\begin_layout Plain Layout
To prevent this future versions of Elision may do away with 
\family typewriter
OPREF
\family default
 at the API level, and more rigorously dispose of it during parsing, but
 for now remember that 
\family typewriter
OPREF
\family default
 is a piece of parser 
\begin_inset Quotes eld
\end_inset

magic.
\begin_inset Quotes erd
\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Case-Operators"

\end_inset

Case Operators
\end_layout

\begin_layout Standard
A case operator declaration must have the following elements.
\end_layout

\begin_layout Itemize
A 
\emph on
name
\emph default
, specified as a symbol.
 For example, 
\family typewriter
sum
\family default
.
\end_layout

\begin_layout Itemize
An optional 
\emph on
type
\emph default
, which is the type of the fully-applied operator.
 If not specified, 
\family typewriter
ANY
\family default
 is used.
\end_layout

\begin_layout Itemize
A 
\emph on
case list
\emph default
, which specifies the alternatives for the operator.
\end_layout

\begin_layout Standard
To specify a case operator, give these three items in the following form:
\end_layout

\begin_layout LyX-Code
{ operator #name=NAME #type=TYPE #cases CASES }
\end_layout

\begin_layout Standard
where 
\family typewriter
NAME
\family default
 is the operator name, 
\family typewriter
TYPE
\family default
 is the type of the fully-applied operator, and 
\family typewriter
CASES
\family default
 is the comma-separated list of alternatives.
 Again, if the 
\family typewriter
#type
\family default
 is 
\emph on
not
\emph default
 declared, it is assumed to be 
\family typewriter
ANY
\family default
.
\end_layout

\begin_layout Standard
A case definition defines an operator by explicitly giving the interpretation
 of the operator in terms of its argument.
 When the operator symbol appears on the left of an applicative dot (even
 when implicit) then each of the alternatives is considered, in order.
\end_layout

\begin_layout Standard
The alternatives can be any atom, but some atoms are special.
\end_layout

\begin_layout Itemize
If the atom is a 
\emph on
rewriter
\emph default
 (the 
\begin_inset Quotes eld
\end_inset

map pair
\begin_inset Quotes erd
\end_inset

 is the most common), then the rewrite is attempted.
 If it succeeds, then the result is the value of the operator application.
 If it fails, then the next alternative is tried.
\end_layout

\begin_layout Itemize
If the atom is an 
\emph on
applicable
\emph default
 (operators are the most common, but also algebraic property specifications),
 then the applicable is placed on the left hand side of the applicative
 dot, and the arguments on the right hand side.
 The result is the value of the operator and no further alternatives are
 considered.
\end_layout

\begin_layout Itemize
Otherwise the atom is the value of the operator.
\end_layout

\begin_layout Standard
The second and third cases are very simple, so we consider them first.
 The following creates an alias for the 
\family typewriter
add
\family default
 operator.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> def({operator #name=`+` #cases add:OPREF})
\end_layout

\begin_layout Plain Layout

Defined operator `+`.
\end_layout

\begin_layout Plain Layout

e> `+`(5,4,3)
\end_layout

\begin_layout Plain Layout

$_repl20 = 12
\end_layout

\end_inset

The following creates a constant function that yields the value one no matter
 what the arguments.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> def({operator #name=one #cases 1})
\end_layout

\begin_layout Plain Layout

Defined operator one.
\end_layout

\begin_layout Plain Layout

e> one(4,5)
\end_layout

\begin_layout Plain Layout

$_repl0 = 1 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The first case uses a rewritable, which will be more fully explained in
 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Matching-and-Rewriting"

\end_inset

.
 Here we consider a simple one: the 
\emph on
map pair
\emph default
.
 A map pair consists of a pattern against which the argument list is matched,
 a text arrow (
\family typewriter
->
\family default
), and an atom specifying the value of the operator when the pattern matches
 the argument list.
 It is advisable to use metavariables on the right-hand side, and we will
 do that by convention.
\end_layout

\begin_layout Standard
The following is a general definition using cases.
\end_layout

\begin_layout LyX-Code
{operator #name=sum #cases
\end_layout

\begin_layout LyX-Code
          %($x: INTEGER) -> $$x,
\end_layout

\begin_layout LyX-Code
          %($x: STRING) -> $$x,
\end_layout

\begin_layout LyX-Code
          %AC($x: INTEGER, $y: INTEGER) -> add($$x,$$y),
\end_layout

\begin_layout LyX-Code
          %A($x: STRING, $y: STRING) -> ($$x.$$y)}
\end_layout

\begin_layout Standard
This definition allows adding both integers (via 
\family typewriter
add
\family default
) and strings (via the applicative dot).
 Note that the lists can specify properties to facilitate proper matching.
 Note also that 
\family typewriter
sum(5,"Fred")
\family default
 results in an error, as this does not match any case.
 Likewise, 
\family typewriter
sum()
\family default
 does not match any case, either.
 Suppose we want to allow the no-argument case but to leave it as 
\family typewriter
sum()
\family default
.
 We add an alternative with the form 
\family typewriter
%() -> _
\family default
.
 This matches the empty argument list.
 The value in this case is the underscore, which is a synonym for 
\family typewriter
ANY
\family default
, and is interpreted here to mean that the argument list should be left
 as it was at the start, yielding 
\family typewriter
sum()
\family default
 as the final answer.
\end_layout

\begin_layout Standard
Suppose we never want an undefined case; when we do not match a given case,
 we want to accept and leave the operator application unchanged, perhaps
 for symbolic manipulation.
 We can use 
\family typewriter
ANY
\family default
 as the pattern to catch this case.
 Consider the following alternate definition of 
\family typewriter
add
\family default
.
\end_layout

\begin_layout LyX-Code
{operator #name=sum #cases
\end_layout

\begin_layout LyX-Code
          %($x: INTEGER) -> $$x,
\end_layout

\begin_layout LyX-Code
          %($x: STRING) -> $$x,
\end_layout

\begin_layout LyX-Code
          %AC($x: INTEGER, $y: INTEGER) -> add($$x,$$y),
\end_layout

\begin_layout LyX-Code
          %A($x: STRING, $y: STRING) -> ($$x.$$y),
\end_layout

\begin_layout LyX-Code
          _ -> _}
\end_layout

\begin_layout Standard
In the last line the lone underscore (a synonym for 
\family typewriter
ANY
\family default
) matches anything.
 Thus 
\family typewriter
sum(5,"Fred")
\family default
 falls to this case and the result is 
\family typewriter
sum:OPTYPE.%(5,"Fred")
\family default
, or just 
\family typewriter
sum(5,"Fred")
\family default
, where construction halts.
 Note that we cannot directly refer to 
\family typewriter
sum
\family default
 inside the definition since the operator is not yet defined.
\end_layout

\begin_layout Standard
This generality allows some rather unorthodox things to occur.
 Consider the following.
\end_layout

\begin_layout LyX-Code
{operator #name=typeof #cases $x:$T -> $$T}
\end_layout

\begin_layout Standard
Now we have an operator that generates the type of anything on the right
 of an applicative dot.
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
This is not perfect! The lambda trick described elsewhere is the best way
 to obtain the type of an atom.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> typeof.5
\end_layout

\begin_layout Plain Layout

$_repl4 = INTEGER
\end_layout

\end_inset


\end_layout

\begin_layout Standard
In Elision, 
\family typewriter
help
\family default
 is implemented as a case operator.
 The definition is potentially instructive.
 The 
\family typewriter
help
\family default
 operator takes either no arguments (the 
\begin_inset Quotes eld
\end_inset

all
\begin_inset Quotes erd
\end_inset

 case) or a single operator reference.
 We can write this as follows.
\end_layout

\begin_layout LyX-Code
def({operator #name=help #cases
\end_layout

\begin_layout LyX-Code
  %($op: OPREF) -> _help_op($$op),
\end_layout

\begin_layout LyX-Code
  _help_all: OPREF
\end_layout

\begin_layout LyX-Code
})
\end_layout

\begin_layout Standard
Here 
\family typewriter
_help_op
\family default
 and 
\family typewriter
_help_all
\family default
 are operators that provide native handlers.
 The first case deals with entering an operator reference.
 The second case is an operator reference, which is an 
\emph on
applicable
\emph default
, so Elision applies 
\family typewriter
_help_all
\family default
 to the argument list, whatever it is.
 This results in some non-intuitive error messages.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> help(5)
\end_layout

\begin_layout Plain Layout

ERROR: Incorrect argument for operator _help_all at position 0: 5.
\end_layout

\begin_layout Plain Layout

Sequences are not the same length.
\end_layout

\end_inset

To the end user this mentions a completely different operator, and complains
 about the length of the argument sequence.
\end_layout

\begin_layout Standard
Suppose instead we wanted to still perform the argument check (so we get
 a better error message).
 We can try to write it as follows.
\end_layout

\begin_layout LyX-Code
def({operator #name=help #cases
\end_layout

\begin_layout LyX-Code
  %($op: OPREF) -> _help_op($$op),
\end_layout

\begin_layout LyX-Code
  %() -> _help_all()
\end_layout

\begin_layout LyX-Code
})
\end_layout

\begin_layout Standard
This looks good, and the error messages are better, but now 
\family typewriter
help()
\family default
 doesn't work!
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> help(5)
\end_layout

\begin_layout Plain Layout

ERROR: Applied the operator help to an incorrect argument list: %(5)
\end_layout

\begin_layout Plain Layout

e> help()
\end_layout

\begin_layout Plain Layout

e> 
\end_layout

\end_inset

We got 
\emph on
no
\emph default
 output.
 This is because the output of 
\family typewriter
_help_all()
\family default
 is generated as a side-effect at construction time
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
Why is it done this way? Why not generate a string value? Then this definition
 would work, right? Well, not really.
 The string would be static, and we want to see help for new operators defined
 
\emph on
after
\emph default
 we have defined 
\family typewriter
help
\family default
.
\end_layout

\end_inset

 (when the native handler is invoked).
 Thus 
\family typewriter
_help_all()
\family default
 has already been evaluated in the above.
\begin_inset Foot
status open

\begin_layout Plain Layout
So, what 
\emph on
was
\emph default
 the result of evaluating 
\family typewriter
_help_all()
\family default
, and why wasn't it printed? The result was the symbol 
\family typewriter
_no_show
\family default
, which is treated specially by the REPL.
 Whenever the result of evaluating an atom is 
\family typewriter
_no_show
\family default
 all output is suppressed.
 This does not work from the prompt.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
What we really want is to somehow delay applying the operator to the argument
 list.
 This could be done with metavariables, but we want to use the empty argument
 list here, so it isn't obvious how to do that since no variables are directly
 involved.
 The answer is that, after Elision applies one of the cases and gets a result,
 the result is then rewritten to replace any instances of the variable 
\family typewriter
$_
\family default
 with the entire argument list.
 This means we can do the following.
 (Note that we use the metavariable 
\family typewriter
$$_
\family default
 by convention here.)
\end_layout

\begin_layout LyX-Code
def({operator #name=help #cases
\end_layout

\begin_layout LyX-Code
  %($op: OPREF) -> _help_op($$op),
\end_layout

\begin_layout LyX-Code
  %() -> _help_all.$$_
\end_layout

\begin_layout LyX-Code
})
\end_layout

\begin_layout Standard
This will work as expected.
 Note that this also means it is inadvisable to use the variable 
\family typewriter
$$_
\family default
 elsewhere.
\end_layout

\begin_layout Standard
Case operators are quite powerful, and can help avoid the need for native
 operators in many cases.
 For instance the Boolean 
\family typewriter
not
\family default
 can be implemented as follows.
\end_layout

\begin_layout LyX-Code
def({operator #name=not #type=BOOLEAN #cases
\end_layout

\begin_layout LyX-Code
  true -> false,
\end_layout

\begin_layout LyX-Code
  false -> true,
\end_layout

\begin_layout LyX-Code
  $x:BOOLEAN -> _,
\end_layout

\begin_layout LyX-Code
  %(true) -> false,
\end_layout

\begin_layout LyX-Code
  %(false) -> true,
\end_layout

\begin_layout LyX-Code
  %($x:BOOLEAN) -> _
\end_layout

\begin_layout LyX-Code
})
\end_layout

\begin_layout Standard
This works, performs correct type checking, and is more general because
 it is also directly applicable to Boolean values.
\end_layout

\begin_layout Standard
Because case operators explicitly allow polymorphism their type cannot be
 correctly inferred as simply as it was for symbolic operators.
 For instance, what is the correct type for the 
\family typewriter
help
\family default
 operator? For the fully-applied type, you have two options.
 You can figure out the correct type yourself and include it with 
\family typewriter
#type=
\family default
, or you can omit it and Elision will assign the operator the type 
\family typewriter
ANY
\family default
.
\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
To create a definition of a case operator, use
\end_layout

\begin_layout Itemize

\family typewriter
core.CaseOperator(name, type, cases, description, detail)
\end_layout

\begin_layout Plain Layout
where 
\family typewriter
name
\family default
 is the operator's name (a string), 
\family typewriter
type
\family default
 is the type of the fully-applied operator (an atom), 
\family typewriter
cases
\family default
 specifies the alternatives (it is an atom sequence), 
\family typewriter
description
\family default
 is the short one-line description of the operator, and 
\family typewriter
detail
\family default
 is the longer description of the operator and its use.
 The last two (
\family typewriter
description
\family default
 and 
\family typewriter
detail
\family default
) are optional.
 The following code creates the examples given previously (the 
\family typewriter
sum
\family default
 operator).
\end_layout

\begin_layout LyX-Code
import ornl.elision.core._
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code
// Make the generic sum operator.
\end_layout

\begin_layout LyX-Code
val List(x,y) = List("x","y").map(Variable(INTEGER,_))
\end_layout

\begin_layout LyX-Code
val List(s,t) = List("s","t").map(Variable(STRING,_))
\end_layout

\begin_layout LyX-Code
val List(mx,my) = List("x","y").map(MetaVariable(INTEGER,_))
\end_layout

\begin_layout LyX-Code
val List(ms,mt) = List("s","t").map(MetaVariable(STRING,_))
\end_layout

\begin_layout LyX-Code
val add = context.operatorLibrary("add")
\end_layout

\begin_layout LyX-Code
val sumOp = CaseOperator("sum", ANY,
\end_layout

\begin_layout LyX-Code
  AtomSeq(NoProps,
\end_layout

\begin_layout LyX-Code
    MapPair(AtomSeq(NoProps,x), mx),
\end_layout

\begin_layout LyX-Code
    MapPair(AtomSeq(NoProps,s), ms),
\end_layout

\begin_layout LyX-Code
    MapPair(AtomSeq(Associative(true) and Commutative(true), x, y),
\end_layout

\begin_layout LyX-Code
      add(mx,my)),
\end_layout

\begin_layout LyX-Code
    MapPair(AtomSeq(Associative(true), s, t), Apply(ms, mt)),
\end_layout

\begin_layout LyX-Code
    MapPair(ANY, ANY)),
\end_layout

\begin_layout LyX-Code
  "Compute the generic polymorphic sum.",
\end_layout

\begin_layout LyX-Code
  "This operator computes the polymorphic sum of its arguments.")
\end_layout

\begin_layout Plain Layout
The last two strings provide documentation, as described in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:Documenting-Operators"

\end_inset

.
 As with symbolic operators, the operator definition should be installed
 in an instance of 
\family typewriter
core.OperatorLibrary
\family default
, typically found in an instance of 
\family typewriter
core.Context
\family default
.
\end_layout

\begin_layout Plain Layout
Unlike symbolic operators, case operators should not be given native handlers.
\end_layout

\end_inset


\end_layout

\begin_layout Section
Recursion
\end_layout

\begin_layout Standard
Within an operator definition it is often desirable to express recursion.
 Suppose we define a relation among types, where 
\family typewriter
BYTE
\family default
 is considered a restriction of 
\family typewriter
WORD
\family default
, which is considered a restriction of 
\family typewriter
DWORD
\family default
, which is finally considered a restriction of the general 
\family typewriter
BITSET
\family default
.
 We want an operator 
\family typewriter
is_restriction_of($T,$U)
\family default
 to evaluate to 
\family typewriter
true
\family default
 iff 
\family typewriter
$T
\family default
 is a restriction of 
\family typewriter
$U
\family default
.
 We could try to write this as follows.
\end_layout

\begin_layout LyX-Code
{ operator #name=is_restriction_of #type=BOOLEAN #cases
\end_layout

\begin_layout LyX-Code
  %($T,$T) -> true,
\end_layout

\begin_layout LyX-Code
  %(BYTE,$T) -> is_restriction_of(WORD,$$T),
\end_layout

\begin_layout LyX-Code
  %(WORD,$T) -> is_restriction_of(DWORD,$$T),
\end_layout

\begin_layout LyX-Code
  %(DWORD,$T) -> is_restriction_of(BITSET,$$T),
\end_layout

\begin_layout LyX-Code
  _ -> false
\end_layout

\begin_layout LyX-Code
}
\end_layout

\begin_layout Standard
The notion is that we promote types until the two arguments are equal, or
 we exhaust the cases.
 This will not parse because 
\family typewriter
is_restriction_of
\family default
 is not yet defined.
 To get around this, we use the fact that after a case operator is applied
 the variable 
\family typewriter
$__
\family default
 (two underscores) is rewritten to the operator.
 This means we can write the above as follows.
\end_layout

\begin_layout LyX-Code
{operator #name=is_restriction_of #type=BOOLEAN #cases
\end_layout

\begin_layout LyX-Code
  %($T,$T) -> true,
\end_layout

\begin_layout LyX-Code
  %(BYTE,$T) -> $$__.%(WORD,$$T),
\end_layout

\begin_layout LyX-Code
  %(WORD,$T) -> $$__.%(DWORD,$$T),
\end_layout

\begin_layout LyX-Code
  %(DWORD,$T) -> $$__.%(BITSET,$$T),
\end_layout

\begin_layout LyX-Code
  _ -> false
\end_layout

\begin_layout LyX-Code
}
\end_layout

\begin_layout Standard
This works as we want.
\end_layout

\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Summary:-Case-Operators"

\end_inset

Summary: Case Operators
\end_layout

\begin_layout Standard
We provide a quick summary of properties of case operators.
\end_layout

\begin_layout Itemize
Cases are evaluated in order.
\end_layout

\begin_layout Itemize
A case can be a strategy, such as a map pair.
 If so, then the strategy is applied to the argument.
 If it reports success, the result is the value of the operator (with substituti
ons).
 If the strategy reports failure, then subsequent cases are tried.
\end_layout

\begin_layout Itemize
A case can be an applicable, such as an operator reference or a lambda.
 If so, then the applicable is applied to the argument immediately and the
 result is the value of the operator (with substitutions).
 No further cases are tried.
\end_layout

\begin_layout Itemize
A case can be any other atom, such as a literal.
 If so, then that atom is the value of the operator (with substitutions).
 No further cases are tried.
\end_layout

\begin_layout Itemize
The variable 
\family typewriter
$_
\family default
 is replaced with the argument list.
\end_layout

\begin_layout Itemize
The variable 
\family typewriter
$__
\family default
 is replaced with the operator.
\end_layout

\begin_layout Itemize
If 
\family typewriter
_
\family default
 or 
\family typewriter
ANY
\family default
 is the value of the operator, then the result is the operator applied to
 the arguments with no further expansion or modification.
\end_layout

\begin_layout Itemize
If no case matches the argument, then an error is generated.
\end_layout

\begin_layout Itemize
Case operators cannot have native handlers, but can use operators with native
 handlers in the cases.
\end_layout

\begin_layout Standard
It is possible to have unbounded recursion.
 Note that using 
\family typewriter
_
\family default
 or 
\family typewriter
ANY
\family default
 as the result does not cause the operator to be re-evaluated, but using
 
\family typewriter
$__
\family default
 likely will.
 A simple example is 
\family typewriter
{operator #name=recur #cases $$__.$$_}
\family default
.
 This simply repeats the operator indefinitely.
 Elision will trap this and report that it has detected unbounded recursion
 (or at least recursion that exhausts the stack).
\end_layout

\begin_layout Standard
Recursion can, of course, be quite useful.
 The following shows how one can compute powers of two.
 (Here we use one operator, but to be more safe, we would typically use
 two: 
\family typewriter
pow2
\family default
 and 
\family typewriter
_pow2
\family default
.
 The first would be the 
\begin_inset Quotes eld
\end_inset

public
\begin_inset Quotes erd
\end_inset

 operator that takes a single argument, and the second would be a hidden
 operator with the cases that take two arguments.
 We have to declare 
\family typewriter
_pow2
\family default
 first in this case, so we can refer to it from 
\family typewriter
pow2
\family default
.)
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> decl.{operator #name=pow2 #type=INTEGER #cases
\end_layout

\begin_layout Plain Layout

 > %($x: INTEGER) -> $$__.%($$x,1),
\end_layout

\begin_layout Plain Layout

 > %(0, $y: INTEGER) -> $$y,
\end_layout

\begin_layout Plain Layout

 > %($x: INTEGER, $y:INTEGER) -> $$__.%(add(-1,$$x),add($$y,$$y))}
\end_layout

\begin_layout Plain Layout

Declared operator pow2.
\end_layout

\begin_layout Plain Layout

e> pow2(4)
\end_layout

\begin_layout Plain Layout

$_repl1 = 16
\end_layout

\begin_layout Plain Layout

e> pow2(8)
\end_layout

\begin_layout Plain Layout

$_repl2 = 256
\end_layout

\begin_layout Plain Layout

e> pow2(20)
\end_layout

\begin_layout Plain Layout

$_repl3 = 1048576 
\end_layout

\end_inset


\end_layout

\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Documenting-Operators"

\end_inset

Documenting Operators
\end_layout

\begin_layout Standard
Operators may include two additional elements.
 A short one-line description of the operator can be given via 
\family typewriter
#description
\family default
, while a longer description of the operator can be given via 
\family typewriter
#detail
\family default
.
 If these are included, they will be used by Elision's help system.
 The general style is to describe the operator in abstract terms in its
 
\family typewriter
#description
\family default
 and not mention parameters by name.
 Then in the 
\family typewriter
#detail
\family default
 the parameters may be mentioned directly.
\end_layout

\begin_layout LyX-Code
{operator #name=sum #cases
\end_layout

\begin_layout LyX-Code
          %($x: INTEGER) -> $$x,
\end_layout

\begin_layout LyX-Code
          %($x: STRING) -> $$x,
\end_layout

\begin_layout LyX-Code
          %AC($x: INTEGER, $y: INTEGER) -> add($$x,$$y),
\end_layout

\begin_layout LyX-Code
          %A($x: STRING, $y: STRING) -> ($$x.$$y),
\end_layout

\begin_layout LyX-Code
          _ -> _
\end_layout

\begin_layout LyX-Code
#description="Compute the generic polymorphic sum."
\end_layout

\begin_layout LyX-Code
#detail="This operator computes the polymorphic sum of its arguments."
\end_layout

\begin_layout LyX-Code
}
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> decl.{operator #name=sum #cases
\end_layout

\begin_layout Plain Layout

 >           %($x: INTEGER) -> $$x,
\end_layout

\begin_layout Plain Layout

 >           %($x: STRING) -> $$x,
\end_layout

\begin_layout Plain Layout

 >           %AC($x: INTEGER, $y: INTEGER) -> add($$x,$$y),
\end_layout

\begin_layout Plain Layout

 >           %A($x: STRING, $y: STRING) -> ($$x.$$y),
\end_layout

\begin_layout Plain Layout

 >           _ -> _
\end_layout

\begin_layout Plain Layout

 > #description="Compute the generic polymorphic sum."
\end_layout

\begin_layout Plain Layout

 > #detail="This operator computes the polymorphic sum of its arguments."
\end_layout

\begin_layout Plain Layout

 > }
\end_layout

\begin_layout Plain Layout

Defined operator sum.
\end_layout

\begin_layout Plain Layout

e> help(sum:OPREF)
\end_layout

\begin_layout Plain Layout

Operator: sum
\end_layout

\begin_layout Plain Layout

Compute the generic polymorphic sum.
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

Prototype:
\end_layout

\begin_layout Plain Layout

  sum .
 (case)
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

Cases:
\end_layout

\begin_layout Plain Layout

  (%($x:INTEGER) -> $$x)
\end_layout

\begin_layout Plain Layout

  (%($x:STRING) -> $$x)
\end_layout

\begin_layout Plain Layout

  (%AC($x:INTEGER, $y:INTEGER) -> add($$x, $$y))
\end_layout

\begin_layout Plain Layout

  (%A($x:STRING, $y:STRING) -> ($$x.$$y))
\end_layout

\begin_layout Plain Layout

  (ANY -> ANY)
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

This operator computes the polymorphic sum of its arguments.
\end_layout

\end_inset


\end_layout

\begin_layout Section
Closures
\end_layout

\begin_layout Standard
Returning to the 
\family typewriter
pow2
\family default
 example given in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:Summary:-Case-Operators"

\end_inset

, we try the following.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> decl.{operator #name=pow2 #type=INTEGER #cases
\end_layout

\begin_layout Plain Layout

 > %(0, $y: INTEGER) -> $$y,
\end_layout

\begin_layout Plain Layout

 > %($x: INTEGER, $y: INTEGER) -> $$__.%(add(-1,$$x),add($$y,$$y))}
\end_layout

\begin_layout Plain Layout

Declared operator pow2.
\end_layout

\begin_layout Plain Layout

e> decl.{operator #name=pow2 #type=INTEGER #cases
\end_layout

\begin_layout Plain Layout

 > %($x: INTEGER) -> pow2($$x,1)}
\end_layout

\begin_layout Plain Layout

WARNING: Redefining operator pow2.
\end_layout

\begin_layout Plain Layout

WARNING: Prior definition: {: operator:SYMBOL { binds name -> pow2:SYMBOL
 type -> INTEGER
\end_layout

\begin_layout Plain Layout

cases -> %((%(0, $y:INTEGER) -> $$y), (%($x:INTEGER, $y:INTEGER) -> ($$__.%((add:
OPREF.%(-1, $$x)),
\end_layout

\begin_layout Plain Layout

(add:OPREF.%($$y, $$y)))))) } :}
\end_layout

\begin_layout Plain Layout

Declared operator pow2.
\end_layout

\begin_layout Plain Layout

e> pow2(8)
\end_layout

\begin_layout Plain Layout

$_repl1 = 256
\end_layout

\end_inset

Here we define the two-argument version of the operator first, then re-define
 the 
\family typewriter
pow2
\family default
 in what looks like a recursive form.
 In fact what has happened is that the second definition uses the 
\emph on
first
\emph default
 definition.
 When Elision creates a term using an operator reference, it captures and
 stores the operator's definition in the term.
 This means that re-defining known operators will not 
\begin_inset Quotes eld
\end_inset

break
\begin_inset Quotes erd
\end_inset

 the system.
 In short, Elision creates a small closure for every operator reference.
\end_layout

\begin_layout Chapter
\begin_inset CommandInset label
LatexCommand label
name "chap:Special-Forms"

\end_inset

Special Forms
\end_layout

\begin_layout Standard
Elision provides an atom called the 
\emph on
special form
\emph default
 that has some associated 
\begin_inset Quotes eld
\end_inset

syntactic sugar
\begin_inset Quotes erd
\end_inset

 and is widely used for many purposes.
 This short chapter describes this form.
\end_layout

\begin_layout Section
The Basic Special Form
\end_layout

\begin_layout Standard
The special form is really just an ordered pair of atoms, and can be represented
 as 
\family typewriter
{: atom atom :}
\family default
, where the two atoms can be anything.
 Because of this structure, it is easy to match and rewrite special forms
 (see 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Matching-and-Rewriting"

\end_inset

).
 The first atom of a special form is called the 
\emph on
tag
\emph default
, and the second atom is called the 
\emph on
content
\emph default
.
 The tag is subject to special interpretation when it is a symbol.
 In this case Elision will perform a lookup and expect the content to have
 a specific structure.
 This representation is called the 
\emph on
two atom
\emph default
 
\emph on
form
\emph default
.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> {: 5 6 :}
\end_layout

\begin_layout Plain Layout

$_repl0 = {: 5 6 :}
\end_layout

\begin_layout Plain Layout

e> {: $x $y :}
\end_layout

\begin_layout Plain Layout

$_repl1 = {: $x $y :}
\end_layout

\begin_layout Plain Layout

e> {: fred $y :}
\end_layout

\begin_layout Plain Layout

$_repl2 = {: fred:SYMBOL $y :}
\end_layout

\begin_layout Plain Layout

e> {: operator $y :}
\end_layout

\begin_layout Plain Layout

ERROR: Form operator:SYMBOL expected bindings as content, but instead found:
 $y.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Many known special forms consist of a symbol as the tag, and bindings as
 the content.
 In fact, this is common enough that there is some 
\begin_inset Quotes eld
\end_inset

syntactic sugar
\begin_inset Quotes erd
\end_inset

 for representing this combination.
 In fact, this alternate form, the 
\emph on
short form
\emph default
, was used to define operators in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Operators"

\end_inset

.
 An opening brace is followed by a symbol tag, then zero or more atoms,
 and then zero or more 
\emph on
bind pairs
\emph default
.
 There are two kinds of bind pairs:
\end_layout

\begin_layout Itemize
A hash mark (
\family typewriter
#
\family default
) followed by a symbol 
\family typewriter
s
\family default
, an equal sign, and an atom 
\family typewriter
a
\family default
.
 This creates the binding 
\family typewriter
s->a
\family default
.
\end_layout

\begin_layout Itemize
A hash mark (
\family typewriter
#
\family default
) followed by a symbol 
\family typewriter
s
\family default
, a space, and then a comma-separated list of atoms 
\family typewriter
a1,a2,
\family default
...
\family typewriter
,aN
\family default
.
 This creates the binding 
\family typewriter
s->%(a1,a2,
\family default
...
\family typewriter
,aN)
\family default
.
\end_layout

\begin_layout Standard
Any number, including zero, bind pairs may be present.
 A list of atoms 
\family typewriter
a1 a2
\family default
 ...

\family typewriter
 aN
\family default
 may be present before any bind pairs.
 If so, then the binding 
\family typewriter
``->a1,a2,
\family default
...
\family typewriter
,aN
\family default
 is created.
\end_layout

\begin_layout Standard
This is really easiest to show with a series of examples.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> {sara}
\end_layout

\begin_layout Plain Layout

$_repl3 = {: sara:SYMBOL { binds  } :}
\end_layout

\begin_layout Plain Layout

e> {sara 6}
\end_layout

\begin_layout Plain Layout

$_repl4 = {: sara:SYMBOL { binds ``->%(6) } :}
\end_layout

\begin_layout Plain Layout

e> {sara 6 7 8}
\end_layout

\begin_layout Plain Layout

$_repl5 = {: sara:SYMBOL { binds ``->%(6, 7, 8) } :}
\end_layout

\begin_layout Plain Layout

e> {sara #first="Sara" #last="Felton"}
\end_layout

\begin_layout Plain Layout

$_repl6 = {: sara:SYMBOL { binds last -> "Felton" first -> "Sara" } :}
\end_layout

\begin_layout Plain Layout

e> {sara #first="Sara" #last="Felton" #chars Zayre, Thorina}
\end_layout

\begin_layout Plain Layout

$_repl7 = {: sara:SYMBOL { binds last -> "Felton" chars ->
\end_layout

\begin_layout Plain Layout

  %(Zayre:SYMBOL, Thorina:SYMBOL) first -> "Sara" } :}
\end_layout

\begin_layout Plain Layout

e> {sara #first="Sara" #last="Felton" #chars=%(Zayre, Thorina)}
\end_layout

\begin_layout Plain Layout

$_repl8 = {: sara:SYMBOL { binds last -> "Felton" chars ->
\end_layout

\begin_layout Plain Layout

  %(Zayre:SYMBOL, Thorina:SYMBOL) first -> "Sara" } :}
\end_layout

\end_inset

So, if you want to bind 
\family typewriter
key
\family default
 to a single 
\family typewriter
value
\family default
, you can use 
\family typewriter
#key=value
\family default
.
 If you want to bind 
\family typewriter
key
\family default
 to a sequence of values, you can use 
\family typewriter
#key v1, v2, 
\family default
...
 Note that a binding is always created, even when it is empty, since the
 special form must always consist of exactly two atoms.
\end_layout

\begin_layout Standard
The purpose of the special form is to unify many different atoms that have
 varied structure, and provide a consistent way to represent them, to match
 them, and to rewrite them.
 As should be evident from the above example, the short form is usually
 much easier to enter and shorter than the two atom form.
 Any short form can be represented in the two atom form, but not all two
 atom forms can be represented in the short form.
\end_layout

\begin_layout Section
Known Special Forms
\end_layout

\begin_layout Standard
There are several known special forms.
 Bindings are not treated the same as other special forms, simply because
 they are themselves used to define special forms.
 Thus the way bindings are interpreted is a bit different, as you can see
 from the first row of the table below.
 Note the additional syntactic sugar for specifying operators.
 This is described in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:Symbolic-Operators"

\end_inset

.
\end_layout

\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status open

\begin_layout Plain Layout
\begin_inset Caption

\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "tab:Known-Special-Forms"

\end_inset

Known Special Forms
\end_layout

\end_inset


\begin_inset Tabular
<lyxtabular version="3" rows="17" columns="2">
<features tabularvalignment="middle">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="75col%">
<row>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tag
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Meaning, Example, and 
\begin_inset Quotes eld
\end_inset

Two Atom
\begin_inset Quotes erd
\end_inset

 Form
\end_layout

\end_inset
</cell>
</row>
<row>
<cell multirow="3" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
binds
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Interpret the content as a list of bindings.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
{binds x->21 y->19}
\end_layout

\end_inset
</cell>
</row>
<row>
<cell multirow="4" alignment="center" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
{: binds:SYMBOL %(x->21, y->19) :}
\end_layout

\end_inset
</cell>
</row>
<row>
<cell multirow="3" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
map
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Map an atom as the left-hand side of an apply to every item in a collection.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
{map add:OPREF}
\end_layout

\end_inset
</cell>
</row>
<row>
<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
{: map:SYMBOL { binds `` -> %(add:OPREF) } :}
\end_layout

\end_inset
</cell>
</row>
<row>
<cell multirow="3" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
match
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Create an atom that matches other atoms against a pattern.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
{match $op.$arg }
\end_layout

\end_inset
</cell>
</row>
<row>
<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
{: match:SYMBOL { binds `` -> %(($op.$arg)) } :}
\end_layout

\end_inset
</cell>
</row>
<row>
<cell multirow="3" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
operator
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Create an operator definition.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell multirow="4" alignment="center" valignment="top" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
{!foo($x,$y)}
\end_layout

\end_inset
</cell>
</row>
<row>
<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
{operator #name=foo #params=%($x,$y)}
\end_layout

\end_inset
</cell>
</row>
<row>
<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
{: operator:SYMBOL { binds name -> foo:SYMBOL params -> %($x, $y) type ->
 ANY } :}
\end_layout

\end_inset
</cell>
</row>
<row>
<cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
rule
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Define a rewrite rule.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
{rule add(neg($x),$y)->0 #rulesets MATH}
\end_layout

\end_inset
</cell>
</row>
<row>
<cell multirow="4" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
{: rule:SYMBOL { binds `` -> %((add(neg($x), $y) -> 0)) rulesets -> %(MATH:SYMBO
L) } :}
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\end_inset


\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
Creating a special form is quite easy.
 Use 
\family typewriter
core.SpecialForm(tag, content)
\family default
, where 
\family typewriter
tag
\family default
 is the tag, and 
\family typewriter
content
\family default
 is the content.
 Invoking this method in the companion object will check the catalog of
 known special forms (shown in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "tab:Known-Special-Forms"

\end_inset

).
 The following code creates each of the atoms shown in the table.
\end_layout

\begin_layout LyX-Code
// Create a binding.
 There are easier ways to do this!
\end_layout

\begin_layout LyX-Code
val binds = SpecialForm(
\end_layout

\begin_layout LyX-Code
  Literal('binds),
\end_layout

\begin_layout LyX-Code
  AtomSeq(NoProps,
\end_layout

\begin_layout LyX-Code
    MapPair(Literal('x), 21),
\end_layout

\begin_layout LyX-Code
    MapPair(Literal('y), 19)))
\end_layout

\begin_layout LyX-Code
// Create {map add:OPREF}.
\end_layout

\begin_layout LyX-Code
val map = SpecialForm(
\end_layout

\begin_layout LyX-Code
  Literal('map),
\end_layout

\begin_layout LyX-Code
  Bindings(""->AtomSeq(NoProps, Literal(OPREF,"add"))))
\end_layout

\begin_layout LyX-Code
// Create {match $op.$arg}.
\end_layout

\begin_layout LyX-Code
val mat = SpecialForm(
\end_layout

\begin_layout LyX-Code
  Literal('match),
\end_layout

\begin_layout LyX-Code
  Bindings(""->AtomSeq(NoProps, Apply('op,'arg))))
\end_layout

\begin_layout LyX-Code
// Create {operator #name=foo #params=%($x,$y)}.
\end_layout

\begin_layout LyX-Code
val foo = SpecialForm(
\end_layout

\begin_layout LyX-Code
  Literal('operator),
\end_layout

\begin_layout LyX-Code
  Bindings("name"->Literal('foo), "params"->AtomSeq(NoProps, 'x, 'y)))
\end_layout

\begin_layout LyX-Code
// Create {rule add(neg($x),$y)->0 #rulesets MATH}.
\end_layout

\begin_layout LyX-Code
val List(add, neg) = List("add","neg").map(context.operatorLibrary(_))
\end_layout

\begin_layout LyX-Code
val rule = SpecialForm(
\end_layout

\begin_layout LyX-Code
  Literal('rule),
\end_layout

\begin_layout LyX-Code
  Bindings(""->AtomSeq(NoProps, MapPair(add(neg('x),'y), 0)),
\end_layout

\begin_layout LyX-Code
           "rulesets"->AtomSeq(NoProps, Literal('MATH))))
\end_layout

\begin_layout Plain Layout
These examples show direct use of the 
\family typewriter
core.SpecialForm
\family default
 object.
 Of course, each of the above has its own simpler, dedicated method of creating
 an instance.
 For example, the simpler method of creating 
\family typewriter
core.Bindings
\family default
 instances is shown several times above.
 The following create the same special form instances.
\end_layout

\begin_layout LyX-Code
// Create a binding.
\end_layout

\begin_layout LyX-Code
val binds = Bindings("x"->21, "y"->19)
\end_layout

\begin_layout LyX-Code
// Create {map add:OPREF}.
\end_layout

\begin_layout LyX-Code
val map = MapStrategy(Literal(OPREF, 'add), AtomSeq(), AtomSeq())
\end_layout

\begin_layout LyX-Code
// Create {match $op.$arg}.
\end_layout

\begin_layout LyX-Code
val mat = MatchAtom(Apply('op, 'arg))
\end_layout

\begin_layout LyX-Code
// Create {operator #name=foo #params=%($x,$y)}.
\end_layout

\begin_layout LyX-Code
val foo = TypedSymbolicOperator("foo", ANY, AtomSeq(NoProps, 'x, 'y), "",
 "")
\end_layout

\begin_layout LyX-Code
// Create {rule add(neg($x),$y)->0 #rulesets MATH}.
\end_layout

\begin_layout LyX-Code
val List(add, neg) = List("add","neg").map(context.operatorLibrary(_))
\end_layout

\begin_layout LyX-Code
val rule = RewriteRule(add(neg('x),'y), 0, Seq(), Set("MATH"))
\end_layout

\begin_layout Plain Layout
There is yet one more way to create a special form.
 You can create and populate an instance of 
\family typewriter
core.SpecialFormHolder
\family default
.
 This is how the parser functions; it detects a special form, populates
 an instance of this object, and then passes it to an apply method that
 creates the appropriate special form.
 Since its primary use is to support parsers, it is not discussed here.
 Note that every special form instance, no matter how created, holds an
 instance of this class.
\end_layout

\end_inset


\end_layout

\begin_layout Chapter
\begin_inset CommandInset label
LatexCommand label
name "chap:Matching-and-Rewriting"

\end_inset

Matching and Rewriting
\end_layout

\begin_layout Standard
Elision is a term rewriter; its primary purpose is matching and rewriting.
 This chapter provides an introduction to matching and rewriting, and to
 the components provided by Elision to perform these tasks.
\end_layout

\begin_layout Section
Bindings
\end_layout

\begin_layout Standard
In Elision, a 
\emph on
binding
\emph default
 associates a variable, such as 
\family typewriter
$x
\family default
 with some atom, such as 
\family typewriter
5
\family default
.
 We say that 
\family typewriter
$x
\family default
 is 
\emph on
bound
\emph default
 to the 
\emph on
value
\emph default
 
\family typewriter
5
\family default
.
 Variables are bound by name only; Elision does not differentiate between
 binding 
\family typewriter
$x:INTEGER
\family default
 and binding 
\family typewriter
$x:STRING
\family default
.
 While this has the potential to cause trouble, in practice it should not,
 and results in a significant performance boost.
 Variable bindings are written in Elision as a bindings atom, which takes
 the form 
\family typewriter
{binds n1->a1 n2->a2 
\family default
...

\family typewriter
 }
\family default
, where 
\family typewriter
n1
\family default
, 
\family typewriter
n2
\family default
, ..., are the variable names (without 
\family typewriter
$
\family default
), and 
\family typewriter
a1
\family default
, 
\family typewriter
a2
\family default
, ..., are the respective values.
 The atom 
\family typewriter
{binds}
\family default
 is legal, and represents the empty bindings set.
 Writing 
\family typewriter
{binds x->5 x->6}
\family default
 is the same as 
\family typewriter
{binds x->6}
\family default
; the last binding of a variable wins.
\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
Bindings behave like Scala 
\family typewriter
Map
\family default
 objects.
 To create a set of bindings, write 
\family typewriter
core.Bindings(s1->a1, s2->a2, 
\family default
...
\family typewriter
)
\family default
, where 
\family typewriter
s1
\family default
, 
\family typewriter
s2
\family default
, ..., are strings that specify the variable names, and 
\family typewriter
a1
\family default
, 
\family typewriter
a2
\family default
, ..., are the atoms.
 It is legal to specify no atoms.
 The following are some examples.
\end_layout

\begin_layout Plain Layout
\begin_inset Tabular
<lyxtabular version="3" rows="4" columns="2">
<features tabularvalignment="middle">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<row>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Elision
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Scala
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
{binds}
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
core.Bindings()
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
{binds x->5}
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
core.Bindings("x"->Literal(5))
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
{binds x->5 y->6}
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
core.Bindings("x"->Literal(5), "y"->Literal(6))
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Plain Layout
It is also possible to incrementally build up a binding.
 The following shows an example.
\end_layout

\begin_layout LyX-Code
var binds = Bindings()
\end_layout

\begin_layout LyX-Code
binds += ("x"->Literal(5))
\end_layout

\begin_layout LyX-Code
binds += ("y"->Literal(6))
\end_layout

\begin_layout LyX-Code
binds.toParseString
\end_layout

\begin_layout Plain Layout
This code will generate the output 
\family typewriter
{ binds x -> 5 y -> 6 }
\family default
.
\end_layout

\begin_layout Plain Layout
Bindings are immutable, and are created and discarded by the system during
 matching.
 Thus the 
\family typewriter
core.Bindings
\family default
 object is explicitly kept 
\begin_inset Quotes eld
\end_inset

lightweight,
\begin_inset Quotes erd
\end_inset

 and is not itself a 
\family typewriter
core.BasicAtom
\family default
.
 Instead, when an atom is needed (such as when we invoke 
\family typewriter
toParseString
\family default
 in the above example) an instance of 
\family typewriter
core.Bindings
\family default
 is automatically transformed into an instance of 
\family typewriter
core.BindingsAtom
\family default
.
 The latter 
\emph on
is
\emph default
 a 
\family typewriter
core.BasicAtom
\family default
.
 To see this transformation you can enter the above four lines to create
 
\family typewriter
binds
\family default
, and then enter 
\family typewriter
binds:BasicAtom
\family default
, or 
\family typewriter
BindingsAtom(binds)
\family default
.
 Likewise, an instance of 
\family typewriter
core.BindingsAtom
\family default
 will be transformed into an instance of 
\family typewriter
core.Bindings
\family default
 when necessary, enabling the use of iterators, etc.
\end_layout

\end_inset


\end_layout

\begin_layout Section
Applying Bindings
\end_layout

\begin_layout Standard
Bindings are an Elision 
\emph on
applicable
\emph default
, meaning that they behave like operators, and generate a new atom, when
 placed on the left-hand side of an applicative dot.
 When bindings are applied to an atom, the atom is 
\emph on
rewritten
\emph default
.
 Every instance of a bound variable in the atom is replaced with the bound
 value.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> {binds x->5 y->6}.$x
\end_layout

\begin_layout Plain Layout

$_repl0 = 5
\end_layout

\begin_layout Plain Layout

e> {binds x->5 y->6}.($x.$y)
\end_layout

\begin_layout Plain Layout

$_repl1 = ((5).6)
\end_layout

\begin_layout Plain Layout

e> {binds x->5 y->6}.add($x,$y)
\end_layout

\begin_layout Plain Layout

$_repl2 = 11
\end_layout

\begin_layout Plain Layout

e> {binds x->5 y->6}.add($x,$y,neg($x))
\end_layout

\begin_layout Plain Layout

$_repl3 = 6
\end_layout

\begin_layout Plain Layout

e> {binds x->5}.{binds y->$x}
\end_layout

\begin_layout Plain Layout

$_repl4 = { binds y -> 5 }
\end_layout

\begin_layout Plain Layout

e> {binds x->5}.{binds y->$x}.$y
\end_layout

\begin_layout Plain Layout

$_repl5 = 5
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\noindent
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 0
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Subsection*
Scala
\end_layout

\begin_layout Plain Layout
Bindings can be applied to atoms in two ways.
 First, they can be applied like any other applicable, using 
\family typewriter
core.Apply
\family default
.
 This causes the bindings to be converted to a 
\family typewriter
core.BindingsAtom
\family default
, which introduces overhead, but also prevents rewriting atoms that contain
 metavariables.
\end_layout

\begin_layout Plain Layout
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

scala> Apply(Bindings("x"->Literal(5), "y"->Literal(6)),'x).toParseString
\end_layout

\begin_layout Plain Layout

res1: String = 5
\end_layout

\begin_layout Plain Layout

scala> Apply(Bindings("x"->Literal(5), "y"->Literal(6)),
\end_layout

\begin_layout Plain Layout

  MetaVariable(ANY,"x")).toParseString
\end_layout

\begin_layout Plain Layout

res2: String = ({ binds x -> 5 y -> 6 }.$$x)
\end_layout

\end_inset

Alternately, every atom has a 
\family typewriter
rewrite(binds)
\family default
 method that accepts a set of bindings and applies the bindings to the atom,
 
\emph on
regardless of any metavariables
\emph default
.
 The return value of this method is a pair of the form 
\family typewriter
(atom,flag)
\family default
, where 
\family typewriter
atom
\family default
 is the rewritten atom, and 
\family typewriter
flag
\family default
 is true iff any rewrites were actually performed.
\end_layout

\begin_layout Plain Layout
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

scala> MetaVariable(ANY,"x").rewrite(Bindings("x"->Literal(5),
\end_layout

\begin_layout Plain Layout

  "y"->Literal(6)))._1.toParseString
\end_layout

\begin_layout Plain Layout

res4: String = 5
\end_layout

\end_inset

In this latter case the bindings are used directly, and no 
\family typewriter
core.BindingsAtom
\family default
 is constructed.
\end_layout

\end_inset


\end_layout

\begin_layout Section
Matching
\end_layout

\begin_layout Standard
The basic principle of matching in Elision can be explained as follows:
 Let 
\begin_inset Formula $s$
\end_inset

 be an atom called the 
\emph on
subject
\emph default
, and let 
\begin_inset Formula $p$
\end_inset

 be an atom called the 
\emph on
pattern
\emph default
.
 Then we say the subject 
\begin_inset Formula $s$
\end_inset

 matches the pattern 
\begin_inset Formula $p$
\end_inset

 iff there is at least one decidable set of bindings 
\begin_inset Formula $b$
\end_inset

 such that 
\begin_inset Formula $b.p=s$
\end_inset

.
 There is one exception to this general rule: 
\family typewriter
ANY
\family default
.
 For instance, the subject 
\family typewriter
5
\family default
 matches the pattern 
\family typewriter
ANY
\family default
, but there is obviously no set of bindings that can transform 
\family typewriter
ANY
\family default
 into 
\family typewriter
5
\family default
, as 
\family typewriter
ANY
\family default
 contains no variables.
\end_layout

\begin_layout Standard
In other words a subject matches a pattern if either the pattern is 
\family typewriter
ANY
\family default
, or if parts of the subject can be bound to variables in the pattern such
 that the subject is equal to the rewritten pattern.
 This is somewhat complicated to explain, but rather easy to show.
 
\begin_inset CommandInset ref
LatexCommand formatted
reference "tab:Examples-of-Matching"

\end_inset

 gives some examples.
\end_layout

\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status open

\begin_layout Plain Layout
\begin_inset Caption

\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "tab:Examples-of-Matching"

\end_inset

Examples of Matching
\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Tabular
<lyxtabular version="3" rows="10" columns="3">
<features tabularvalignment="middle">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<row>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Pattern
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Subject
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Outcome
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
5
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
5
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Match with 
\family typewriter
{binds}
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
ANY
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
5
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Match with 
\family typewriter
{binds}
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
5
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
ANY
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Match with 
\family typewriter
{binds}
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
$x
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
5
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Match with 
\family typewriter
{binds x->5}
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
5
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
$x
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
No matches
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
$x.5
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
joe:SYMBOL.5
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Match with 
\family typewriter
{binds x->joe:SYMBOL}
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
$x.$x
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
(5).6
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
No matches
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
$x.$x
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
(6).6
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Match with 
\family typewriter
{binds x->6}
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
add($x,$y)
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
add($a,$b,$c)
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Multiple matches
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\end_inset

Note that it is possible to match two terms without having to bind any variables
, resulting in an empty binding.
 As the last case 
\begin_inset CommandInset ref
LatexCommand formatted
reference "tab:Examples-of-Matching"

\end_inset

 indicates, it is also possible to have many possible bindings.
 In this last case 
\family typewriter
{binds x->$a y->add($b,$c)}
\family default
 and 
\family typewriter
{binds x->add($a,$b) y->$c}
\family default
 are both acceptable matches, since 
\family typewriter
add
\family default
 is associative.
 However 
\family typewriter
add
\family default
 is also commutative, so additionally we permit 
\family typewriter
{binds x->$b y->add($a,$c)}
\family default
, 
\family typewriter
{binds x->$c y->add($a,$b)}
\family default
, 
\family typewriter
{binds x->add($b,$c) y->$a}
\family default
, and 
\family typewriter
{binds x->add($a,$c) y->$b}
\family default
.
 The outcome of a match attempt can be no match, a single match, or many
 matches.
\end_layout

\begin_layout Standard
Elision provides a simple way to test matching.
 The 
\emph on
match atom
\emph default
 is an applicable (so it works like an operator) that has the form 
\family typewriter
{match pattern}
\family default
, where 
\family typewriter
pattern
\family default
 is the pattern to attempt to match.
 The following examples reproduce the matches from 
\begin_inset CommandInset ref
LatexCommand formatted
reference "tab:Examples-of-Matching"

\end_inset

.
 The result will either be a binding if the subject matches the pattern,
 or 
\family typewriter
NONE
\family default
 if it does not.
 In the case of multiple matches, only the first is returned.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> {match 5}
\end_layout

\begin_layout Plain Layout

$_repl0 = {: match:SYMBOL { binds `` -> %(5) } :}
\end_layout

\begin_layout Plain Layout

e> {match 5}.5
\end_layout

\begin_layout Plain Layout

$_repl1 = { binds  }
\end_layout

\begin_layout Plain Layout

e> {match ANY}.5
\end_layout

\begin_layout Plain Layout

$_repl2 = { binds  }
\end_layout

\begin_layout Plain Layout

e> {match 5}.ANY
\end_layout

\begin_layout Plain Layout

$_repl3 = { binds  }
\end_layout

\begin_layout Plain Layout

e> {match $x}.5
\end_layout

\begin_layout Plain Layout

$_repl4 = { binds x -> 5 }
\end_layout

\begin_layout Plain Layout

e> {match 5}.$x
\end_layout

\begin_layout Plain Layout

$_repl5 = NONE
\end_layout

\begin_layout Plain Layout

e> {match $x.5}.(joe:SYMBOL.5)
\end_layout

\begin_layout Plain Layout

$_repl6 = { binds x -> joe:SYMBOL }
\end_layout

\begin_layout Plain Layout

e> {match $x.$x}.((5).6)
\end_layout

\begin_layout Plain Layout

$_repl7 = NONE
\end_layout

\begin_layout Plain Layout

e> {match $x.$x}.((6).6)
\end_layout

\begin_layout Plain Layout

$_repl8 = { binds x -> 6 }
\end_layout

\begin_layout Plain Layout

e> {match add($x,$y)}.add($a,$b,$c)
\end_layout

\begin_layout Plain Layout

$_repl9 = { binds x -> $a y -> add($b, $c) }
\end_layout

\end_inset


\end_layout

\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Map-Pairs"

\end_inset

Map Pairs
\end_layout

\begin_layout Standard
We can use the result of a match to rewrite another atom.
 The following is one simple example.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> {match add($x,$y,neg($x))}.add($a,neg($a),19)
\end_layout

\begin_layout Plain Layout

$_repl10 = { binds x -> $a y -> 19 }
\end_layout

\begin_layout Plain Layout

e> {match add($x,$y,neg($x))}.add($a,neg($a),19).$y
\end_layout

\begin_layout Plain Layout

$_repl11 = 19
\end_layout

\end_inset

Remember that the applicative dot is left-associative, so the bindings are
 created first, and then used to rewrite the atom 
\family typewriter
$y
\family default
, yielding the result 
\family typewriter
19
\family default
.
 Of course this trick won't work so well when 
\family typewriter
NONE
\family default
 is returned.
 We can build a solution using lambdas, but it will be a bit tedious.
 Elision provides a simpler way: the 
\emph on
map pair
\emph default
.
 The map pair has the form 
\family typewriter
pattern -> newatom
\family default
, where 
\family typewriter
pattern
\family default
 is the pattern to match, and 
\family typewriter
newatom
\family default
 is the atom to rewrite if a match is obtained.
 The map pair is a 
\emph on
rewriter
\emph default
, meaning that it yields a specialized binding of the form 
\family typewriter
{binds atom->newatom flag->theflag}
\family default
, where 
\family typewriter
newatom
\family default
 is the result and 
\family typewriter
theflag
\family default
 indicates whether the rewriter succeeded in some sense.
 For the map pair, 
\family typewriter
theflag
\family default
 is true iff the pattern match succeeded.
\end_layout

\begin_layout Standard
The following is an example.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> (add($x,neg($x),$y)->$y).add($a,neg($a),19)
\end_layout

\begin_layout Plain Layout

$_repl12 = { binds flag -> true atom -> 19 }
\end_layout

\begin_layout Plain Layout

e> (add($x,neg($x),$y)->$y).add($a,neg($a))
\end_layout

\begin_layout Plain Layout

$_repl13 = { binds flag -> false atom -> add($a, neg($a)) }
\end_layout

\begin_layout Plain Layout

e> (add($x,neg($x),$y)->$y).add($a,neg($a)).$atom
\end_layout

\begin_layout Plain Layout

$_repl14 = add($a, neg($a))
\end_layout

\end_inset

In the first case the match succeeds.
 In the second, it fails.
 Note that when the match fails the result is the unmodified subject.
\end_layout

\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Variable-Guards"

\end_inset

Variable Guards
\end_layout

\begin_layout Standard
Variables can be matched based on type information.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> {match $x:INTEGER}."Korra"
\end_layout

\begin_layout Plain Layout

$_repl0 = NONE
\end_layout

\begin_layout Plain Layout

e> {match $x:INTEGER}.5
\end_layout

\begin_layout Plain Layout

$_repl1 = { binds x -> 5 }
\end_layout

\end_inset

This is often sufficient, but sometimes we would like to have greater control
 over the matching process.
 For example, we might like to match only a non-zero integer.
 We can do this with a 
\emph on
variable
\emph default
 
\emph on
guard
\emph default
.
 This is an atom that is attached to a variable using braces.
 The atom is rewritten with the proposed variable binding, and if it evaluates
 to 
\family typewriter
true
\family default
, the binding succeeds.
 Otherwise the entire match is rejected.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> {match $x{not(equal($$x,0))}:INTEGER}.5
\end_layout

\begin_layout Plain Layout

$_repl2 = { binds x -> 5 }
\end_layout

\begin_layout Plain Layout

e> {match $x{not(equal($$x,0))}:INTEGER}.0
\end_layout

\begin_layout Plain Layout

$_repl3 = NONE
\end_layout

\end_inset

Using metavariables in the guards prevents trouble, and we adopt it as a
 convention.
 If we did not use it, 
\family typewriter
equal($x,0)
\family default
 would immediately evaluate to 
\family typewriter
false
\family default
, which would be negated to 
\family typewriter
true
\family default
, making the guard 
\family typewriter
{true}
\family default
.
 This would always succeed, which is not what we want at all.
\end_layout

\begin_layout Standard
We can use this to gain some control when there are many possible matches.
 Consider the following.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> decl.{! foo($x,$y) is %AC}
\end_layout

\begin_layout Plain Layout

Defined operator foo.
\end_layout

\begin_layout Plain Layout

e> {match foo($x:INTEGER, $y)}.foo("Jim",5,"Tim",0)
\end_layout

\begin_layout Plain Layout

$_repl2 = { binds x -> foo("Jim", 5) y -> foo("Tim", 0) }
\end_layout

\begin_layout Plain Layout

e> {match foo($x{equal($$x,0)}:INTEGER, $y)}.foo("Jim",5,"Tim",0)
\end_layout

\begin_layout Plain Layout

$_repl3 = { binds x -> 0 y -> foo("Jim", 5, "Tim") }
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Variable guards are sufficient in most cases, but there are still cases
 in which you want a guard that involves several variables.
 How to do this will be discussed in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Rules-and-Strategies"

\end_inset

.
\end_layout

\begin_layout Chapter
\begin_inset CommandInset label
LatexCommand label
name "chap:Rules-and-Strategies"

\end_inset

Rules and Strategies
\end_layout

\begin_layout Standard
Basic matching and rewriting were introduced in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "chap:Matching-and-Rewriting"

\end_inset

.
 This chapter will explain how to manage rewriting on a much larger scale,
 creating more general rewrite rules, managing them with rulesets, and controlli
ng the process through the use of strategies and the build-in strategy combinato
rs.
\end_layout

\begin_layout Section
Rewrite Rules and Guards
\end_layout

\begin_layout Standard
A rewrite rule generalizes the notion of a map pair a bit by introducing
 additional guards.
\end_layout

\begin_layout Section
Rulesets
\end_layout

\begin_layout Section
Strategies
\end_layout

\begin_layout Standard
In Elision a 
\emph on
strategy
\emph default
 is an atom 
\begin_inset Formula $S$
\end_inset

 that, when applied to another atom 
\begin_inset Formula $A$
\end_inset

 yields two things: a potentially new atom 
\begin_inset Formula $A'$
\end_inset

 and a Boolean value 
\begin_inset Formula $f$
\end_inset

.
 These items are packaged in a binding of the form 
\family typewriter
{bind atom->
\family default

\begin_inset Formula $A'$
\end_inset


\family typewriter
 flag->
\family default

\begin_inset Formula $f$
\end_inset


\family typewriter
}
\family default
.
 Any atom that satisfies this requirement is a strategy.
\end_layout

\begin_layout Standard
There are already several examples of strategies.
 Map pairs and rewrite rules both satisfy this requirement, and are considered
 strategies.
 The following is a simple strategy that takes an atom and returns that
 atom with the flag true.
\end_layout

\begin_layout LyX-Code
{ operator #name=s_noop #type=STRATEGY #cases
\end_layout

\begin_layout LyX-Code
  $a -> {binds atom->$$a flag->true} }
\end_layout

\begin_layout Standard
This illustrates some points about strategies.
 First, the names of strategy operators start with 
\family typewriter
s_
\family default
.
 Second, strategies are given the type 
\family typewriter
STRATEGY
\family default
, even though the result is a binding.
\end_layout

\begin_layout Section
The Map Strategy
\end_layout

\begin_layout Section
Strategy Combinators
\end_layout

\begin_layout Chapter
\begin_inset CommandInset label
LatexCommand label
name "chap:Contexts"

\end_inset

Executors and Contexts
\end_layout

\begin_layout Standard
Rewrite rules, operator definitions, and bindings need to be made persistent
 during a session.
 This means we need some form of mutable data store to hold these.
 That general storage is called the 
\emph on
context
\emph default
, and is explored in more detail in this chapter.
 Also, Elision code must be parsed to obtain atoms, and that is the job
 of an 
\emph on
executor
\emph default
.
\end_layout

\begin_layout Standard
Executors are provided by classes that implement the 
\family typewriter
core.Executor
\family default
 trait, and contexts are instances of 
\family typewriter
core.Context
\family default
.
 Every executor instance also holds an instance of a context.
\end_layout

\begin_layout Standard
Elision atoms are immutable, so 
\end_layout

\begin_layout Chapter
\start_of_appendix
BasicAtom
\end_layout

\begin_layout Chapter
Exceptions
\end_layout

\begin_layout Standard
Elision attempts to handle exceptions rationally, and to 
\emph on
never
\emph default
 allow the system to fail completely.
 Once Elision is up and the REPL is running, exceptions are trapped and
 an attempt is made to dispose of them appropriately.
 The following sections describe how Elision handles exceptions.
\end_layout

\begin_layout Section
Elision Exceptions
\end_layout

\begin_layout Standard
Elision uses a number of exceptions to signal conditions internally.
 These are usually serious conditions, from the point of view of the rewriter,
 but do 
\emph on
not
\emph default
 represent complete failure.
 That is, it should be possible to continue after one of these exceptions.
 All such exceptions extend 
\family typewriter
core.ElisionException
\family default
 and provide a human-readable string as the message.
\end_layout

\begin_layout Description

\family typewriter
core.ArgumentListException
\family default
 An error was detected in the argument list for an operator.
 This is typically a type check error, or the wrong number of arguments,
 as with 
\family typewriter
add(5,"Tim")
\family default
.
\end_layout

\begin_layout Description

\family typewriter
core.LambdaUnboundedRecursionException
\family default
 The stack was exhausted during evaluation of a lambda expression.
 This typically represents unbounded recursion.
\end_layout

\begin_layout Description

\family typewriter
core.LambdaVariableMismatchException
\family default
 The argument provided to a lambda does not match the lambda parameter.
 This is typically a type error, as with 
\family typewriter

\backslash
$x:INTEGER.$x."Not an integer."
\family default
.
\end_layout

\begin_layout Description

\family typewriter
core.NativeHandlerException
\family default
 A native handler for an operator could not be parsed, or represented incomplete
 input (missing a closing parenthesis or brace, for instance).
 For example, 
\family typewriter
{! foo() #handler=
\family default
"
\family typewriter
 for(atom <- args) { 
\family default
"
\family typewriter
}
\family default
.
\end_layout

\begin_layout Description

\family typewriter
core.OperatorDefinitionException
\family default
 An error occurred in evaluating an operator definition.
 Most likely your properties and prototype do not agree, as with 
\family typewriter
{! foo($x:INTEGER):INTEGER is associative}
\family default
.
\end_layout

\begin_layout Description

\family typewriter
core.OperatorRedefinitionException
\family default
 An attempt was made to re-define an operator, but the operator library
 does not allow this.
 Under normal circumstances (i.e., using the REPL), redefinition is allowed
 with a warning.
\end_layout

\begin_layout Description

\family typewriter
core.SpecialFormException
\family default
 A structural error was discovered interpreting a special form.
 Typically this means that the content was missing an required bind pair,
 as with 
\family typewriter
{operator #type=INTEGER}
\family default
.
\end_layout

\begin_layout Section
Java Exceptions and Throwables
\end_layout

\begin_layout Standard
Other exceptions are handled differently by Elision.
\end_layout

\begin_layout Chapter
Reading Elision Files
\end_layout

\begin_layout Standard
Elision provides several mechanisms to read files.
\end_layout

\begin_layout Itemize
The REPL.
 You can pipe input to the REPL, or you can use the 
\family typewriter
read
\family default
 and 
\family typewriter
read_once
\family default
 commands at the prompt.
\end_layout

\begin_layout Itemize
The 
\family typewriter
read(filename: String)
\family default
 method of 
\family typewriter
parse.Processor
\family default
.
\end_layout

\begin_layout Itemize
The 
\family typewriter
elc
\family default
 (Elision compiler) command that reads input, and then generates the Scala
 code to re-create the resulting context.
\end_layout

\begin_layout Standard
These methods all work essentially the same way: input is consumed from
 some source, parsed into a sequence of atoms, and each atom is then handled
 in some appropriate manner.
 All this work is generalized by the 
\family typewriter
parse.Processor
\family default
 class.
 The following sections discuss how to use these to create additional facilities.
\end_layout

\begin_layout Section
Processor
\end_layout

\begin_layout Standard
If you want to process Elision files you should begin with 
\family typewriter
parse.Processor
\family default
.
 This class provides a context, along with several methods to read data.
\end_layout

\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status open

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout
\begin_inset Caption

\begin_layout Plain Layout
Methods to Read Atoms
\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Tabular
<lyxtabular version="3" rows="4" columns="2">
<features tabularvalignment="middle">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<row>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Method
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Use
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
read(filename: String)
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Read the content of the specified file.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
read(stream: Source)
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Read the content of the provided stream.
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family typewriter
execute(text: String)
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Read from the provided string.
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\end_inset

Internally, all text is ultimately processed by the 
\family typewriter
execute(String)
\family default
 method.
 The flow of this method is as follows.
\end_layout

\begin_layout Enumerate
Parse the text, obtaining a sequence of 
\family typewriter
parse.AtomParser.AstNode
\family default
 instances.
\end_layout

\begin_layout Enumerate
For each node, do the following for each registered instance of 
\family typewriter
parse.Processor.Handler
\family default
, in the order registered.
\end_layout

\begin_deeper
\begin_layout Enumerate
Pass the current node to the 
\family typewriter
handleNode(node: AtomParser.AstNode)
\family default
 method.
 This method must return an 
\family typewriter
Option[AtomParser.AstNode]
\family default
.
 If the returned value is 
\family typewriter
None
\family default
, then the node is discarded.
 If the returned value is 
\family typewriter
Some(node)
\family default
, then the returned node becomes the current node.
 A simple default implementation of 
\family typewriter
handleNode
\family default
 is:
\end_layout

\begin_deeper
\begin_layout LyX-Code
def handleNode(node: AtomParser.AstNode) = Some(node)
\end_layout

\end_deeper
\begin_layout Enumerate
Pass the node to all listening actors via 
\family typewriter
actor ! node
\family default
.
\end_layout

\begin_layout Enumerate
Convert the node into an atom by invoking the node's 
\family typewriter
interpret
\family default
 method.
\end_layout

\begin_layout Enumerate
Pass any current atom to the 
\family typewriter
handleAtom(atom: BasicAtom)
\family default
 method.
 This method is responsible for performing any specialized processing of
 the atom 
\emph on
post-construction
\emph default
 (as the atom was already constructed during execution of the 
\family typewriter
interpret
\family default
 method in 
\family typewriter
handleAtom
\family default
), and should return an optional atom.
 If 
\family typewriter
None
\family default
 is returned then the atom is discarded and the system proceeds to the next
 node.
 If the return value is 
\family typewriter
Some(atom)
\family default
, then the returned atom becomes the current atom.
 A simple default implementation of 
\family typewriter
handleAtom
\family default
 is:
\end_layout

\begin_deeper
\begin_layout LyX-Code
def handleAtom(atom: BasicAtom) = Some(atom)
\end_layout

\end_deeper
\begin_layout Enumerate
Pass the atom to all listening actors via 
\family typewriter
actor ! atom
\family default
.
\end_layout

\end_deeper
\begin_layout Standard
Other events can be passed to actors.
 Whenever a new file is provided for processing, a 
\family typewriter
FileStart
\family default
 object is sent to the actors.
 When processing of the file is complete, a 
\family typewriter
FileEnd
\family default
 is sent.
 When a new stream is provided for processing, a 
\family typewriter
StreamStart
\family default
 is sent to all actors.
 When a stream is exhausted, a 
\family typewriter
StreamEnd
\family default
 is sent to all actors.
 The flow of messages thus looks as follows, if a valid filename is provided
 to the 
\family typewriter
read
\family default
 method.
\end_layout

\begin_layout LyX-Code
FileStart
\end_layout

\begin_layout LyX-Code
StreamStart
\end_layout

\begin_layout LyX-Code
AtomParser.AstNode
\end_layout

\begin_layout LyX-Code
BasicAtom
\end_layout

\begin_layout LyX-Code
AtomParser.AstNode
\end_layout

\begin_layout LyX-Code
BasicAtom
\end_layout

\begin_layout LyX-Code
AtomParser.AstNode
\end_layout

\begin_layout LyX-Code
BasicAtom
\end_layout

\begin_layout LyX-Code
...
\end_layout

\begin_layout LyX-Code
AtomParser.AstNode
\end_layout

\begin_layout LyX-Code
BasicAtom
\end_layout

\begin_layout LyX-Code
StreamEnd
\end_layout

\begin_layout LyX-Code
FileEnd
\end_layout

\begin_layout Section
Operators
\end_layout

\begin_layout Standard
The 
\end_layout

\begin_layout Chapter
\begin_inset CommandInset label
LatexCommand label
name "chap:Native-Handlers"

\end_inset

Native Handlers
\end_layout

\begin_layout Standard
This appendix describes how to create native handlers for symbolic operators.
 Native handlers cannot be created for case operators, as they don't really
 make sense.
 If you want a native handler for a case operator, create a symbolic operator,
 provide it with a native handler, and include it as a case.
 The 
\family typewriter
help
\family default
 operator described in 
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:Case-Operators"

\end_inset

 is such an example.
\end_layout

\begin_layout Standard
A short description of creating native handlers is given in the Scala block
 of 
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:Operator-Applications"

\end_inset

.
 This is suitable for creating them programmatically, but Elision provides
 support for providing the definition more directly.
\end_layout

\begin_layout Standard
Consider the operator 
\family typewriter
mod($b,$d)
\family default
 that computes the remainder when 
\family typewriter
$b
\family default
 is divided by 
\family typewriter
$d
\family default
.
 For example, 
\family typewriter
mod(5,2)
\family default
 is 
\family typewriter
1
\family default
, while 
\family typewriter
mod(4,2)
\family default
 is 
\family typewriter
0
\family default
.
 First we give the definition of the operator, without a native handler.
\end_layout

\begin_layout LyX-Code
{! mod($b: INTEGER, $d: INTEGER): INTEGER}
\end_layout

\begin_layout Standard
The definition specifies two parameters: 
\family typewriter
$b
\family default
 and 
\family typewriter
$d
\family default
, both integers.
\end_layout

\begin_layout Standard
A native 
\emph on
handler
\emph default
 consists of a Scala closure.
 It's argument is an instance of 
\family typewriter
core.ApplyData
\family default
, and the handler is expected to return an instance of 
\family typewriter
core.BasicAtom
\family default
.
 There are several fields and methods of 
\family typewriter
core.ApplyData
\family default
 that can be useful in writing a native handler.
\end_layout

\begin_layout Itemize
The field 
\family typewriter
exec
\family default
 provides access to an instance of 
\family typewriter
core.Executor
\family default
.
 This is a class that provides an 
\family typewriter
parse(text)
\family default
 method, where 
\family typewriter
text
\family default
 is a string to be parsed as a sequence of atoms.
 The 
\family typewriter
core.Executor
\family default
 instance also provides access to a 
\family typewriter
core.Context
\family default
 instance, and to a 
\family typewriter
core.Console
\family default
 instance.
\end_layout

\begin_layout Itemize
The field 
\family typewriter
context
\family default
 is the context provided by the executor.
 It provides access to the operator and rule libraries and to the current
 bindings.
\end_layout

\begin_layout Itemize
The field 
\family typewriter
console
\family default
 is the console provided by the executor.
 It has methods 
\family typewriter
error(msg)
\family default
 and 
\family typewriter
warn(msg)
\family default
 to generate errors and warnings, and 
\family typewriter
emit(msg)
\family default
 and 
\family typewriter
emitln(msg)
\family default
 to write arbitrary text to the console.
\end_layout

\begin_layout Itemize
The field 
\family typewriter
_no_show
\family default
 is a special symbol that is used by certain interactive systems, such as
 the REPL, to indicate that no value should be displayed as the result of
 the handler.
 This is the common return value for operators that are executed solely
 for their side effect.
 For example, this is the value returned by the 
\family typewriter
help
\family default
 operator.
 This should be checked by object identity, not equality, so that it is
 possible to use 
\family typewriter
_no_show
\family default
 as a symbol normally.
\end_layout

\begin_layout Itemize
The method 
\family typewriter
as_is
\family default
 indicates that the result should be the application of the operator to
 the argument list without any further processing.
 This is commonly used as the return value for an operator in cases where
 no special processing is required.
\end_layout

\begin_layout Itemize
The field 
\family typewriter
op
\family default
 is the instance of 
\family typewriter
core.SymbolicOperator
\family default
 being applied.
\end_layout

\begin_layout Itemize
The field 
\family typewriter
args
\family default
 is an instance of 
\family typewriter
core.AtomSeq
\family default
 that contains the arguments to the operator, in order.
\end_layout

\begin_layout Itemize
The field 
\family typewriter
binds
\family default
 is an instance of 
\family typewriter
core.Bindings
\family default
 that binds each parameter to its corresponding argument.
 For associative operators the parameters bound are synthetic, and are named
 
\family typewriter
$`:1`
\family default
, 
\family typewriter
$`:2`
\family default
, ...
\end_layout

\begin_layout Standard
Remember that strings and numbers are automatically converted to atoms.
 To take apart the argument list, a special extractor 
\family typewriter
core.Args
\family default
 is provided.
 This is a sequence extractor for 
\family typewriter
core.AtomSeq
\family default
 instances.
 Given all this, we can write the native handler for 
\family typewriter
mod
\family default
 as follows.
\end_layout

\begin_layout LyX-Code
def modHandler(data: ApplyData) = data.args match {
\end_layout

\begin_layout LyX-Code
  case Args(IntegerLiteral(_, b), IntegerLiteral(_, d) => b mod d
\end_layout

\begin_layout LyX-Code
  case _ => as_is
\end_layout

\begin_layout LyX-Code
}
\end_layout

\begin_layout Standard
Now if 
\family typewriter
context
\family default
 is the context where the operator is defined we can register the handler
 as follows.
 Note that we convert the function into a closure and pass the closure.
\end_layout

\begin_layout LyX-Code
context.operatorLibrary.register("mod", modHandler _)
\end_layout

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Plain Layout

%
\end_layout

\end_inset


\end_layout

\begin_layout Standard
It is possible to declare a native handler for an operator from the REPL.
 This is done by adding a 
\family typewriter
#handler
\family default
 bind pair to the definition of the operator.
 The value for 
\family typewriter
#handler
\family default
 must be a string literal.
 The string literal executes in the following context.
\end_layout

\begin_layout LyX-Code
import ornl.elision.core._
\end_layout

\begin_layout LyX-Code
def _handler(_data: ApplyData): BasicAtom = {
\end_layout

\begin_layout LyX-Code
  import _data._
\end_layout

\begin_layout LyX-Code
  import ApplyData._
\end_layout

\begin_layout LyX-Code
  // The #handler value is placed here.
\end_layout

\begin_layout LyX-Code
}
\end_layout

\begin_layout Standard
The result is a function whose closure is stored as the native handler for
 the operator.
 Note that the operator need not be declared in any context; it is possible
 to use this to execute arbitrary Scala code.
 Consider the following.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

e> {! _() #handler=""" "hello world!" """}.%()
\end_layout

\begin_layout Plain Layout

$_repl0 = "hello world!"
\end_layout

\begin_layout Plain Layout

e> {! _() #handler=""" println("hello world!") ; _no_show """}.%()
\end_layout

\begin_layout Plain Layout

hello world!
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Returning to the closure for the 
\family typewriter
mod
\family default
 operator, we can define it as follows.
\end_layout

\begin_layout LyX-Code
{! mod($b: INTEGER, $d: INTEGER): INTEGER
\end_layout

\begin_layout LyX-Code
   #description="Compute the remainder of integer division."
\end_layout

\begin_layout LyX-Code
   #detail="""Compute the remainder when $b is divided by $d."""
\end_layout

\begin_layout LyX-Code
   #handler="""|args match {
\end_layout

\begin_layout LyX-Code
               |  case Args(IntegerLiteral(_, b), IntegerLiteral(_, d))
 =>
\end_layout

\begin_layout LyX-Code
               |    b mod d
\end_layout

\begin_layout LyX-Code
               |  case _ => as_is
\end_layout

\begin_layout LyX-Code
               |}"""
\end_layout

\begin_layout LyX-Code
}
\end_layout

\begin_layout Standard
As with 
\family typewriter
#detail
\family default
, if the first character is the pipe symbol (
\family typewriter
|
\family default
), then the margin is stripped.
 Note that handler does not need to refer to 
\family typewriter
_data.args
\family default
, as everything in 
\family typewriter
_data
\family default
 is imported.
 If other classes are required, you may add an 
\family typewriter
import
\family default
 statement to obtain them.
\end_layout

\begin_layout Standard
Some examples follow.
 First we write a 
\begin_inset Quotes eld
\end_inset

hello world
\begin_inset Quotes erd
\end_inset

 operator.
\end_layout

\begin_layout LyX-Code
{! foo() #handler=""" "hello world!" """}
\end_layout

\begin_layout Standard
Next we create a much more complex operator that evaluates its string argument.
 If the argument evaluates to one or more atoms, then the last atom is returned.
 Alternately we could return a collection of atoms.
 This makes use of the executor, console, and some of the special fields
 (like 
\family typewriter
_no_show
\family default
 and 
\family typewriter
as_is
\family default
).
\end_layout

\begin_layout LyX-Code
{! evaluate($text: STRING)
\end_layout

\begin_layout LyX-Code
   #handler="""|import ornl.elision.core._
\end_layout

\begin_layout LyX-Code
               |args match {
\end_layout

\begin_layout LyX-Code
               |  case Args(StringLiteral(_, text)) =>
\end_layout

\begin_layout LyX-Code
               |    exec.parse(text) match {
\end_layout

\begin_layout LyX-Code
               |      case exec.ParseFailure(msg) =>
\end_layout

\begin_layout LyX-Code
               |        console.error(msg)
\end_layout

\begin_layout LyX-Code
               |        _no_show
\end_layout

\begin_layout LyX-Code
               |      case exec.ParseSuccess(atoms) =>
\end_layout

\begin_layout LyX-Code
               |        if (atoms.length > 0) atoms(atoms.length-1)
\end_layout

\begin_layout LyX-Code
               |        else _no_show
\end_layout

\begin_layout LyX-Code
               |    }
\end_layout

\begin_layout LyX-Code
               |  case _ => as_is
\end_layout

\begin_layout LyX-Code
               |}"""
\end_layout

\begin_layout LyX-Code
}
\end_layout

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Plain Layout

%
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Finally, we will use a few language features to create a 
\family typewriter
_decl
\family default
 operator that can be used to declare other operators and rules.
\end_layout

\begin_layout LyX-Code
// Create the def operator.
\end_layout

\begin_layout LyX-Code
{! _decl($item)
\end_layout

\begin_layout LyX-Code
#handler=
\end_layout

\begin_layout LyX-Code
"""
\end_layout

\begin_layout LyX-Code
  args(0) match {
\end_layout

\begin_layout LyX-Code
    case op: Operator =>
\end_layout

\begin_layout LyX-Code
      context.operatorLibrary.add(op)
\end_layout

\begin_layout LyX-Code
      console.emitln("Declared operator " + toESymbol(op.name) + ".")
\end_layout

\begin_layout LyX-Code
      _no_show
\end_layout

\begin_layout LyX-Code
    case rule: RewriteRule =>
\end_layout

\begin_layout LyX-Code
      context.ruleLibrary.add(rule)
\end_layout

\begin_layout LyX-Code
      console.emitln("Declared rule.")
\end_layout

\begin_layout LyX-Code
      _no_show
\end_layout

\begin_layout LyX-Code
    case _ =>
\end_layout

\begin_layout LyX-Code
      as_is
\end_layout

\begin_layout LyX-Code
  }
\end_layout

\begin_layout LyX-Code
"""
\end_layout

\begin_layout LyX-Code
#evenmeta=true
\end_layout

\begin_layout LyX-Code
#description="Declare a rule or operator in the current context."
\end_layout

\begin_layout LyX-Code
#detail=
\end_layout

\begin_layout LyX-Code
"Given a rewrite rule, add the rewrite rule to the rule library in the ".
\end_layout

\begin_layout LyX-Code
"current context.
  Given an operator, add the operator to the operator ".
\end_layout

\begin_layout LyX-Code
"library in the current context."
\end_layout

\begin_layout LyX-Code
}
\end_layout

\begin_layout Standard
There is one field in the above that requires some explanation.
 The 
\family typewriter
#evenmeta=true
\family default
 forces evaluation of this operator even when the argument is a metaterm.
 Since both operator definitions and rewrite rules typically contain metaterms,
 this is essential.
 This feature breaks the general model of 
\begin_inset Quotes eld
\end_inset

metaterms prevent evaluation,
\begin_inset Quotes erd
\end_inset

 so its use is not recommended.
 In fact, it only exists to address cases like the above.
\end_layout

\begin_layout Standard
An interesting question is how to get 
\family typewriter
_decl
\family default
 itself declared without the use of another operator.
 That is, how could we 
\begin_inset Quotes eld
\end_inset

bootstrap
\begin_inset Quotes erd
\end_inset

 the system? Since 
\family typewriter
_decl
\family default
 is capable of declaring operators, we 
\emph on
could
\emph default
 use it to declare itself.
 We do this with a lambda.
\end_layout

\begin_layout LyX-Code

\backslash
$op.($op.%($op)).{! _decl($item) ...
 }
\end_layout

\begin_layout Standard
This yields 
\family typewriter
_decl
\family default
 applied to an argument list containing itself, and thus results in the
 operator declaring itself, as we want.
\end_layout

\begin_layout Chapter
\begin_inset CommandInset label
LatexCommand label
name "chap:De-Bruijn-Indices"

\end_inset

De Bruijn Indices
\end_layout

\begin_layout Standard
Elision converts lambdas into a representation using a form of De Bruijn
 indices.
 This appendix describes how they are implemented in Elision.
\end_layout

\begin_layout Standard
A 
\begin_inset Quotes eld
\end_inset

proper
\begin_inset Quotes erd
\end_inset

 De Bruijn index indicates the the number of binds that are in scope.
 Thus the lambda 
\begin_inset Formula $\lambda x.\lambda y.x$
\end_inset

 should correctly produce the De Bruijn term 
\begin_inset Formula $\lambda\lambda2$
\end_inset

, as the body binds to the outermost lambda.
 Elision does not actually use proper De Bruijn indices, but uses a very
 similar concept somewhere in between symbolic names and De Bruijn indices.
\end_layout

\begin_layout Standard
In Elision every atom has an associated De Bruijn index.
 Literals and (most) variables have index zero.
 Other terms have De Bruijn index equal to the maximum index of their parts.
\end_layout

\begin_layout Standard
Suppose we are given a lambda term such as 
\family typewriter

\backslash
$x.add($x,$y)
\family default
.
 The body contains no lambdas or De Bruijn indices, so it has De Bruijn
 index zero.
 The lambda parameter also contains no lambdas or De Bruijn indices, so
 it also has De Bruijn index zero.
 Thus the maximum De Bruijn index of the parts is zero.
 Since we are constructing a lambda, we increment the maximum index, obtaining
 one.
 The system constructs a special variable 
\family typewriter
$`:1`
\family default
 representing the De Bruijn index, and then rewrites lambda parameter and
 body with 
\family typewriter
$x -> $`:1`
\family default
, obtaining the result 
\family typewriter

\backslash
$`:1`.add($`:1`, $y)
\family default
.
\end_layout

\begin_layout Standard
Next consider 
\family typewriter

\backslash
$x.
\backslash
$y.$x
\family default
.
 First 
\family typewriter

\backslash
$y.$x
\family default
 is constructed, yielding 
\family typewriter

\backslash
$`:1`.$x
\family default
, whose Dr Bruijn index (assigned by Elision) is one.
 Next we construct 
\family typewriter

\backslash
$x.(
\backslash
$`:1`.$x)
\family default
.
 The De Bruijn index of the parameter is zero, and of the body is one, so
 the De Bruijn index to use for the new expression is 
\family typewriter
$`:2`
\family default
, and we rewrite with 
\family typewriter
$x -> $`:2`
\family default
.
 The trick is that the rewrite actually causes us to re-build the lambdas.
 Rewriting the body 
\family typewriter

\backslash
$`:1`.$x
\family default
 results in a new lambda whose body is 
\family typewriter

\backslash
$`:2`
\family default
 with De Bruijn index of two, and thus the entire lambda constructs a new
 
\end_layout

\begin_layout Chapter
The Elision Directory Structure
\end_layout

\begin_layout Standard
The Elision repository contains several files and folders.
 This appendix explains what these items are, where to find them, and where
 to put stuff if you want to contribute.
 The description here contains items that are 
\emph on
not
\emph default
 part of the built distribution, since many of these are not required by
 the distribution.
 This description also contains items that are 
\emph on
not
\emph default
 found in the repository, but are created during the build process.
\end_layout

\begin_layout Section
In the Distribution
\end_layout

\begin_layout Standard
The folders described in the following subsections are part of the Elision
 distribution, created by the 
\family typewriter
dist
\family default
 target in 
\family typewriter
build.xml
\family default
.
\end_layout

\begin_layout Subsection
The Root Folder
\end_layout

\begin_layout Standard
The root of the distribution is reserved for a few files.
\end_layout

\begin_layout Itemize
The 
\family typewriter
README.txt
\family default
 file that describes the distribution and how to build it and start the
 REPL.
 You should only modify this if you need to correct information or document
 a new build.
\end_layout

\begin_layout Itemize
The 
\family typewriter
CHANGES.txt
\family default
 file that describes changes from one version to the next.
\end_layout

\begin_layout Itemize
The 
\family typewriter
LICENSE.txt
\family default
 file that contains the license for Elision.
\end_layout

\begin_layout Itemize
The 
\family typewriter
build.xml
\family default
 file that is used by Ant to compile the system and generate the API documentati
on.
 You should only modify this if you need to change how the system is built.
 This is not needed if you are just adding new source files or third-party
 libraries.
\end_layout

\begin_layout Standard
There are scripts present in this folder.
\end_layout

\begin_layout Itemize
The 
\family typewriter
elision.sh
\family default
 script sets up the 
\family typewriter
CLASSPATH
\family default
 and invokes the Elision REPL.
 This is a Bash script that is only useful on UNIX, Mac OS X, and Linux
 machines, or on Windows machines with Cygwin.
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
Elision is developed on Mac OS X and Linux platforms, and only occasionally
 tested on Windows, so YMMV.
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
The 
\family typewriter
run.sh
\family default
 script sets up the 
\family typewriter
CLASSPATH
\family default
 and then starts the Scala interpreter.This is a Bash script that is only
 useful on UNIX, Mac OS X, and Linux machines, or on Windows machines with
 Cygwin.
\end_layout

\begin_layout Standard
In general do not place any other items in the root folder.
 Instead, put them in the appropriate subfolder.
\end_layout

\begin_layout Subsection
The 
\family typewriter
etc
\family default
 Folder
\end_layout

\begin_layout Standard
This folder is reserved for the following items.
\end_layout

\begin_layout Itemize
The 
\family typewriter
config.xml
\family default
 file that provides the template for the system's runtime configuration,
 and the 
\family typewriter
elision_configuration.dtd
\family default
 that describes the format of the configuration file.
 You should not need to modify either of these unless you are modifying
 the 
\family typewriter
ornl.elision.Version
\family default
 object.
\end_layout

\begin_layout Itemize
Files that provide Elision support for editors or IDE's, such as Emacs
\begin_inset Foot
status open

\begin_layout Plain Layout
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://www.gnu.org/software/emacs/
\end_layout

\end_inset


\end_layout

\end_inset

, Eclipse
\begin_inset Foot
status open

\begin_layout Plain Layout
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://www.eclipse.org/
\end_layout

\end_inset


\end_layout

\end_inset

, and Sublime
\begin_inset Foot
status open

\begin_layout Plain Layout
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://www.sublimetext.com/2
\end_layout

\end_inset


\end_layout

\end_inset

.
 See the 
\family typewriter
editors
\family default
 folder.
\end_layout

\begin_layout Itemize
Miscellaneous files, such as properties files for use in Eclipse, if desired.
\end_layout

\begin_layout Standard
If you have a file or files you need to add, and have no other place to
 put it, this is the place it belongs.
\end_layout

\begin_layout Subsection
The 
\family typewriter
doc
\family default
 Folder
\end_layout

\begin_layout Standard
This folder contains the Elision documentation, other than the 
\family typewriter
README.txt
\family default
 file.
 Specifically, it contains the following.
\end_layout

\begin_layout Itemize
This file, 
\family typewriter
elision.pdf
\family default
.
\end_layout

\begin_layout Itemize
The 
\family typewriter
elision.lyx
\family default
 file.
 This is a LyX
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
LyX is an editor that is backed by 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
LaTeX
\end_layout

\end_inset

.
 If you want to edit this document, you need LyX.
 Fortunately it runs on almost every platform out there.
 Visit 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://lyx.org
\end_layout

\end_inset

 for more information and links to the latest version.
\end_layout

\end_inset

 source file that is converted into 
\family typewriter
elision.pdf
\family default
, and contains the user and developer documentation you are reading right
 now.
\end_layout

\begin_layout Itemize
The 
\family typewriter
makedoc.sh
\family default
 script that will compile the API documentation without requiring you to
 have Ant.
 This file runs the Scaladoc command and puts the documentation in the 
\family typewriter
api
\family default
 subfolder, the same as the 
\family typewriter
build.xml
\family default
 script does.
 This is a Bash script, and should work on UNIX and Mac OS X, Linux, and
 possibly on Windows under Cygwin.
\end_layout

\begin_layout Itemize
The 
\family typewriter
index.html
\family default
 file used by the Elision web site.
\end_layout

\begin_layout Itemize
If the API documentation has been built, either by running the 
\family typewriter
makedoc.sh
\family default
 script or by running the Ant build and specifying the 
\family typewriter
doc
\family default
 target, then there will be an 
\family typewriter
api
\family default
 folder containing the API documentation.
 Point your browser to 
\family typewriter
doc/api/index.html
\family default
 to view the documentation.
\end_layout

\begin_layout Standard
Other documentation files should be put in this folder.
\end_layout

\begin_layout Subsection
The 
\family typewriter
lib
\family default
 Folder
\end_layout

\begin_layout Standard
This folder contains third party code necessary to compile and run the system.
 There is a simple rule for this folder: The build and the Bash scripts
 will search this folder for any jar files, and will add all such files
 found to the class path.
\end_layout

\begin_layout Standard
If you need to use third party code in Elision, and you want to contribute
 back to the main distribution, you must first clear the inclusion of the
 third-party code with the maintainers to make sure there are no licensing
 conflicts, and then you should place the distribution in this folder.
 This allows for consistent and rational versioning.
 If the user were required to get and install the third party libraries,
 they might obtain incompatible versions.
\end_layout

\begin_layout Subsection
The 
\family typewriter
src
\family default
 Folder
\end_layout

\begin_layout Standard
This folder contains the source code for Elision, organized into folders
 that mirror the package hierarchy.
 All Elision code should be placed in a package rooted under 
\family typewriter
ornl.elision
\family default
.
 This is where you will place new source files, as well as any extra files
 required by Scaladoc.
 The one exception is the 
\family typewriter
src/bootstrap
\family default
 folder that holds the Elision source for bootstrapping the system.
\end_layout

\begin_layout Section
From the Build
\end_layout

\begin_layout Standard
The folders described in the following subsections are created by the build
 process.
\end_layout

\begin_layout Subsection
The 
\family typewriter
bin
\family default
 Folder
\end_layout

\begin_layout Standard
This folder is created by the build process and contains the compiled class
 files and other elements that should be in the class path.
 In fact, the executable jar file is created by compressing this folder
 and adding a manifest, as specified in the 
\family typewriter
build.xml
\family default
 file.
 Anything that should be in the class path should be placed in this folder.
\end_layout

\begin_layout Subsection
The 
\family typewriter
latest
\family default
 Folder
\end_layout

\begin_layout Standard
This folder is created by the build process and contains the most recently
 built executable 
\family typewriter
elision.jar
\family default
 and 
\family typewriter
elision-all.jar
\family default
 files.
 Any jar files in the third-party library folder (
\family typewriter
lib
\family default
) are included in these files, and 
\family typewriter
elision-all.jar
\family default
 also includes some of the Scala distribution's jar files.
 Nothing else should be present in this folder.
\end_layout

\begin_layout Subsection
Date-Stamped Folder(s)
\end_layout

\begin_layout Standard
Every time the system is built, it creates a folder whose name is the current
 date, in 
\family typewriter
YYYYMMDD
\family default
 format.
 This folder contains two items: the same 
\family typewriter
elision.jar
\family default
 file found in the 
\family typewriter
latest
\family default
 folder, and a jar file containing the content of the 
\family typewriter
src
\family default
 folder at the time of the build.
 Because 
\family typewriter
elision-all.jar
\family default
 is so large, it is not included.
 These folders can be deleted if they are not needed.
 Nothing else should be present in these folders.
\end_layout

\begin_layout Chapter
The Elision Coding Guide
\end_layout

\begin_layout Standard
This chapter describes the general style of coding to use for contributions
 to Elision.
\end_layout

\begin_layout Section
Concepts
\end_layout

\begin_layout Standard
The following definition is due to David Parnas.
\end_layout

\begin_layout Definition*
One code entity 
\begin_inset Formula $A$
\end_inset

 
\emph on
uses
\emph default
 another entity 
\begin_inset Formula $B$
\end_inset

 iff the correct functioning of 
\begin_inset Formula $A$
\end_inset

 depends on the availability of a correct implementation of 
\begin_inset Formula $B$
\end_inset

.
\end_layout

\begin_layout Standard
The 
\begin_inset Quotes eld
\end_inset

uses
\begin_inset Quotes erd
\end_inset

 relation is not the same as 
\begin_inset Quotes eld
\end_inset

invokes.
\begin_inset Quotes erd
\end_inset

 
\begin_inset Formula $A$
\end_inset

 may invoke code in 
\begin_inset Formula $B$
\end_inset

 without using 
\begin_inset Formula $B$
\end_inset

 in the manner described above.
 For example, an operating system invokes programs, but the functioning
 of the operating system should not depend on the correct functioning of
 the programs.
\end_layout

\begin_layout Standard
Problems arise when there are loops in the uses relation.
 That is, 
\begin_inset Formula $A$
\end_inset

 uses 
\begin_inset Formula $B$
\end_inset

 and 
\begin_inset Formula $B$
\end_inset

 uses 
\begin_inset Formula $A$
\end_inset

.
 Then neither 
\begin_inset Formula $A$
\end_inset

 nor 
\begin_inset Formula $B$
\end_inset

 work until 
\emph on
both
\emph default
 work.
 This condition is also referred to as a 
\emph on
tangle
\emph default
.
 These are bad because nothing works until everything works.
 The code becomes very brittle, and changes 
\begin_inset Quotes eld
\end_inset

ripple
\begin_inset Quotes erd
\end_inset

 through the system in ways that are hard to trace.
\end_layout

\begin_layout Description
Rule Avoid loops in the use hierarchy.
\end_layout

\begin_layout Section
Architectural Rules
\end_layout

\begin_layout Description
Rule All code must be in packages under 
\family typewriter
ornl.elision
\family default
.
\end_layout

\begin_layout Section
Scaladoc
\end_layout

\begin_layout Standard
In general it is recommended to follow the Scaladoc guidelines found at
 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://docs.scala-lang.org/style/scaladoc.html
\end_layout

\end_inset

.
 We make some revisions here.
\end_layout

\begin_layout Description
Rule The Elision style is to use Java-style documentation comments (first
 asterisks align and comment starts on second line), and not the style recommend
ed for Scaladoc (second asterisks align and comments start on first line).
 There is better tool support for this style at present.
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

/** This is the style from the Scaladoc page.
\end_layout

\begin_layout Plain Layout

  * Please don't use it.
  Most formatters don't
\end_layout

\begin_layout Plain Layout

  * know what to do with it.
\end_layout

\begin_layout Plain Layout

  */
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

/**
\end_layout

\begin_layout Plain Layout

 * This is the common "Javadoc" style.
  Do use it.
\end_layout

\begin_layout Plain Layout

 */
\end_layout

\end_inset


\end_layout

\begin_layout Description
Rule Document every public and protected method and field using Scaladoc.
 It is not necessary to document private methods and fields, but it is probably
 advisable.
\end_layout

\begin_layout Description
Rule Documentation may be omitted when a method or field overrides or implements
 a method from a parent class.
 In some cases you may wish to replace the textual documentation, but may
 omit the documentation of parameters and/or the return value.
\end_layout

\begin_layout Section
Comments
\end_layout

\begin_layout Standard
Comment your code by recording design decisions, your rationale for choices,
 and descriptions of how complicated code sections work.
 Essentially record what you will want to know when you have to understand
 the code five years later, or when someone new to the project has to make
 changes and not break anything.
 If there is an assumptions in your code, you should record them.
\end_layout

\begin_layout Description
Rule Write complete sentences.
 Capitalize and punctuate appropriately, and make a reasonable attempt to
 spell correctly.
\end_layout

\begin_layout Description
Rule Use single-line comments for short comments.
 For long explanations, use the 
\family typewriter
/*
\family default
...
\family typewriter
*/
\family default
 style.
\end_layout

\begin_layout Description
Rule Use comment blocks to delineate logical sections of large classes.
 These take the following form:
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

//======================================================================
\end_layout

\begin_layout Plain Layout

// Section description goes here.
\end_layout

\begin_layout Plain Layout

//======================================================================
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Don't comment every line, and don't just re-state what the line does.
 Assume the person reading the code (probably you) will know how to read
 the code.
 Use comments to explain what is going on.
 The following commentary is useless.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

// get atoms
\end_layout

\begin_layout Plain Layout

val atoms = atomset.filter(!_.isBindable)
\end_layout

\begin_layout Plain Layout

// loop over atoms
\end_layout

\begin_layout Plain Layout

for (atom <- atoms) {
\end_layout

\begin_layout Plain Layout

  // print atom
\end_layout

\begin_layout Plain Layout

  println(atom.toParseString)
\end_layout

\begin_layout Plain Layout

}
\end_layout

\end_inset

This commentary is just a more verbose version of the above commentary.
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

// Get the unbindable atoms.
\end_layout

\begin_layout Plain Layout

val atoms = atomset.filter(!_.isBindable)
\end_layout

\begin_layout Plain Layout

// Print all the atoms.
\end_layout

\begin_layout Plain Layout

for (atom <- atoms) {
\end_layout

\begin_layout Plain Layout

  // Print the next atom on its own line.
\end_layout

\begin_layout Plain Layout

  println(atom.toParseString)
\end_layout

\begin_layout Plain Layout

}
\end_layout

\end_inset

This is actually the recommended style.
 Keep it simple.
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

// Print all unbindables.
\end_layout

\begin_layout Plain Layout

val atoms = atomset.filter(!_.isBindable)
\end_layout

\begin_layout Plain Layout

for (atom <- atoms) {
\end_layout

\begin_layout Plain Layout

  println(atom.toParseString)
\end_layout

\begin_layout Plain Layout

}
\end_layout

\end_inset


\end_layout

\begin_layout Section
Spacing
\end_layout

\begin_layout Description
Rule Use two-space increments for indentation.
 If possible, set your editor to use spaces instead of tab characters, and
 do not use tab characters.
\end_layout

\begin_layout Description
Rule Skip a blank line between any Scaladoc documented items, and between
 classes no matter whether they are documented or not.
\end_layout

\begin_layout Description
Rule Break lines at 80 characters (or just slightly over).
\end_layout

\begin_layout Section
Returning
\end_layout

\begin_layout Chapter
Grammar
\end_layout

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
newcommand{
\backslash
term}[1]{
\backslash
fbox{
\backslash
texttt{#1}}}
\end_layout

\begin_layout Plain Layout


\backslash
newcommand{
\backslash
citerm}[1]{
\backslash
doublebox{
\backslash
texttt{#1}}}
\end_layout

\begin_layout Plain Layout


\backslash
newcommand
\backslash
defntx[1]{~
\backslash

\backslash
[1em]
\backslash
textbf{#1}~::=~}
\end_layout

\begin_layout Plain Layout


\backslash
newcommand
\backslash
defnt[1]{~
\backslash

\backslash
[1em]
\backslash
textbf{#1}~::=~}
\end_layout

\begin_layout Plain Layout


\backslash
newcommand{
\backslash
nt}[1]{
\backslash
emph{#1}}
\end_layout

\begin_layout Plain Layout


\backslash
newcommand{
\backslash
ordef}{~
\backslash

\backslash

\backslash
hspace{0.5in}|~}
\end_layout

\begin_layout Plain Layout


\backslash
newcommand{
\backslash
shortor}{~|~}
\end_layout

\begin_layout Plain Layout


\backslash
newcommand{
\backslash
zeroOrMore}[1]{(#1){*}}
\end_layout

\begin_layout Plain Layout


\backslash
newcommand{
\backslash
optional}[1]{(#1)?}
\end_layout

\begin_layout Plain Layout


\backslash
newcommand{
\backslash
caret}{
\backslash
textasciicircum{}}
\end_layout

\begin_layout Plain Layout


\backslash
newcommand{
\backslash
juxt}{$
\backslash
cdot$}
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The grammar for Elision is described in extended Backus-Naur form (EBNF)
 in this appendix.
 Terminals are indicated with text in fixed font, boxed, as 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
term{terminal}
\end_layout

\end_inset

.
 Elision is normally case-sensitive, but some terminals are case-insensitive.
 These are indicated with a double box, as 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
citerm{terminal}
\end_layout

\end_inset

.
 Nonterminals are indicated with italics, as 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
nt{nonterminal}
\end_layout

\end_inset

.
 Character ranges in unicode are indicated by a dash, so any single nonzero
 digit is 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
term{1}
\end_layout

\end_inset

-
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
term{9}
\end_layout

\end_inset

.
 Productions are indicated with ::=.
 Parentheses indicate grouping.
 If an item may appear zero or more times, this is indicated with a suffixed
 asterisk, as 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
zeroOrMore{
\backslash
nt{atom}}
\end_layout

\end_inset

.
 Optional items are indicated with a suffixed question mark, as 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
optional{
\backslash
nt{atom}}
\end_layout

\end_inset

.
\end_layout

\begin_layout Standard
In general arbitrary white space is allowed.
 When no whitespace is allowed between two elements of the grammar, the
 elements are joined by a dot, as 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
term{
\backslash
#}
\backslash
juxt
\backslash
nt{atom}
\end_layout

\end_inset

.
 The special terminal 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
term{ANY}
\end_layout

\end_inset

 is described at the end, and corresponds to any character other than the
 backslash 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
term{
\backslash
textbackslash}
\end_layout

\end_inset

.
\end_layout

\begin_layout Standard
Though not explicitly in the grammar, comments are allowed in two forms.
 Single line comments starting with
\family typewriter
 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
term{//}
\end_layout

\end_inset


\family default
 and ending with a newline, and multi-line comments starting with
\family typewriter
 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
term{/*}
\end_layout

\end_inset


\family default
 and ending with 
\family typewriter

\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
term{*/}
\end_layout

\end_inset


\family default
.
\end_layout

\begin_layout Standard
\noindent
\align left
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
defnt{atom-seq} 
\backslash
zeroOrMore{
\backslash
nt{atom}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{atom} 
\backslash
nt{first-atom} 
\backslash
term{->} 
\backslash
nt{first-atom}
\end_layout

\begin_layout Plain Layout


\backslash
ordef
\backslash
nt{first-atom} 
\backslash
zeroOrMore{
\backslash
term{.} 
\backslash
nt{first-atom})}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{first-atom} 
\backslash
term{(} 
\backslash
nt{atom} 
\backslash
term{)}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
nt{special-form}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
nt{lambda}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
nt{apply}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
nt{typed-list}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
nt{alg-prop}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
nt{variable}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
nt{operator-symbol}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
nt{literal}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
nt{number}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
term{
\backslash
caret TYPE}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{special-form} 
\backslash
nt{alternate-operator-def}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
term{
\backslash
{:} 
\backslash
nt{atom} 
\backslash
nt{atom} 
\backslash
term{:
\backslash
}}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
term{
\backslash
{} 
\backslash
nt{atom} 
\backslash
zeroOrMore{
\backslash
nt{atom}}
\end_layout

\begin_layout Plain Layout

		
\backslash
zeroOrMore{
\backslash
nt{sf-bound-atom}|
\backslash
nt{sf-bound-list}} 
\backslash
term{
\backslash
}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{alternate-operator-def} 
\backslash
term{
\backslash
{!}
\end_layout

\begin_layout Plain Layout

	
\backslash
nt{SYMBOL} 
\backslash
term{(} 
\backslash
nt{atom-sequence} 
\backslash
term{)}
\end_layout

\begin_layout Plain Layout

	
\backslash
optional{:
\backslash
nt{first-atom}}
\end_layout

\begin_layout Plain Layout

	
\backslash
zeroOrMore{
\backslash
nt{sf-bound-atom} | 
\backslash
nt{sf-bound-list}}
\end_layout

\begin_layout Plain Layout

	
\backslash
term{
\backslash
}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{sf-bound-atom} 
\backslash
term{
\backslash
#}
\backslash
juxt
\backslash
nt{SYMBOL} 
\backslash
term{=} 
\backslash
nt{atom}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{sf-bound-list} 
\backslash
term{
\backslash
#}
\backslash
juxt
\backslash
nt{SYMBOL} 
\backslash
zeroOrMore{
\backslash
nt{atom}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{lambda} 
\backslash
term{
\backslash
textbackslash{}} 
\backslash
nt{variable} 
\backslash
term{.} 
\backslash
nt{first-atom}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{apply} 
\backslash
nt{SYMBOL} 
\backslash
term{(} 
\backslash
nt{atom-sequence} 
\backslash
term{)}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{atom-sequence} 
\backslash
nt{atom} 
\backslash
zeroOrMore{
\backslash
term{,} 
\backslash
nt{atom}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{typed-list} 
\backslash
nt{alg-prop} 
\backslash
term{(} 
\backslash
nt{atom-sequence} 
\backslash
term{)}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{alg-prop} 
\backslash
nt{alg-prop-short}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
term{
\backslash
%}
\backslash
nt{alg-prop-long}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{alg-prop-short} 
\backslash
term{
\backslash
%}
\backslash
juxt 
\backslash
zeroOrMore{
\end_layout

\begin_layout Plain Layout

	
\backslash
citerm{A}
\backslash
optional{
\backslash
term{[}
\backslash
nt{atom}
\backslash
term{]}}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
citerm{C}
\backslash
optional{
\backslash
term{[}
\backslash
nt{atom}
\backslash
term{]}}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
citerm{I}
\backslash
optional{
\backslash
term{[}
\backslash
nt{atom}
\backslash
term{]}}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
citerm{!A}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
citerm{!C}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
citerm{!I}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
citerm{B}
\backslash
term{[}
\backslash
nt{atom}
\backslash
term{]}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
citerm{D}
\backslash
term{[}
\backslash
nt{atom}
\backslash
term{]}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{alg-prop-long} 
\backslash
zeroOrMore{
\end_layout

\begin_layout Plain Layout

	
\backslash
term{absorber} 
\backslash
nt{atom}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
term{identity} 
\backslash
nt{atom}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
optional{
\backslash
term{not}} 
\backslash
term{associative}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
optional{
\backslash
term{not}} 
\backslash
term{commutative}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
optional{
\backslash
term{not}} 
\backslash
term{idempotent}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{variable} (
\backslash
term{
\backslash
$}
\backslash
shortor
\backslash
term{
\backslash
$
\backslash
$})
\end_layout

\begin_layout Plain Layout

	
\backslash
nt{SYMBOL}
\end_layout

\begin_layout Plain Layout

	
\backslash
optional{
\backslash
term{
\backslash
{} 
\backslash
nt{atom} 
\backslash
term{
\backslash
}}}
\end_layout

\begin_layout Plain Layout

	
\backslash
optional{
\backslash
term{:} 
\backslash
nt{first-atom}}
\end_layout

\begin_layout Plain Layout

	
\backslash
zeroOrMore{
\backslash
term{@} 
\backslash
nt{SYMBOL}}
\end_layout

\begin_layout Plain Layout

 
\end_layout

\begin_layout Plain Layout


\backslash
defnt{operator-symbol} 
\backslash
nt{SYMBOL} 
\backslash
term{:} 
\backslash
term{OPTYPE}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{literal} 
\backslash
nt{SYMBOL}
\backslash
shortor
\backslash
nt{STRING}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{number} 
\backslash
nt{any-number} 
\backslash
optional{
\backslash
term{:} 
\backslash
nt{first-atom}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{any-number} 
\backslash
nt{hex-number}
\end_layout

\begin_layout Plain Layout

	
\backslash
shortor 
\backslash
nt{hex-number}
\end_layout

\begin_layout Plain Layout

	
\backslash
shortor 
\backslash
nt{binary-number}
\end_layout

\begin_layout Plain Layout

	
\backslash
shortor 
\backslash
nt{decimal-number}
\end_layout

\begin_layout Plain Layout

	
\backslash
shortor 
\backslash
nt{octal-number}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{hex-number} 
\backslash
nt{hex-integer}
\end_layout

\begin_layout Plain Layout

	
\backslash
optional{
\backslash
juxt
\backslash
term{.}
\backslash
nt{hex-digit}}
\end_layout

\begin_layout Plain Layout

	
\backslash
optional{
\backslash
juxt
\backslash
citerm{P}
\backslash
juxt
\backslash
nt{exponent}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{binary-number}
\backslash
nt{binary-integer}
\end_layout

\begin_layout Plain Layout

	
\backslash
optional{
\backslash
juxt
\backslash
term{.}
\backslash
juxt
\backslash
nt{binary-digit}}
\end_layout

\begin_layout Plain Layout

	
\backslash
optional{
\backslash
juxt(
\backslash
citerm{E}
\backslash
shortor
\backslash
citerm{P})
\backslash
juxt
\backslash
nt{exponent}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{decimal-number}
\backslash
nt{decimal-integer}
\end_layout

\begin_layout Plain Layout

	
\backslash
optional{
\backslash
juxt
\backslash
term{.}
\backslash
juxt
\backslash
nt{decimal-digit}}
\end_layout

\begin_layout Plain Layout

	
\backslash
optional{
\backslash
juxt(
\backslash
citerm{E}
\backslash
shortor
\backslash
citerm{P})
\backslash
juxt
\backslash
nt{exponent}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{octal-number}
\backslash
nt{octal-integer}
\end_layout

\begin_layout Plain Layout

	
\backslash
optional{
\backslash
juxt
\backslash
term{.}
\backslash
juxt
\backslash
nt{octal-digit}}
\end_layout

\begin_layout Plain Layout

	
\backslash
optional{
\backslash
juxt(
\backslash
citerm{E}
\backslash
shortor
\backslash
citerm{P})
\backslash
juxt
\backslash
nt{exponent}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{exponent} 
\backslash
optional{
\backslash
term{-}
\backslash
shortor
\backslash
term{+}} 
\backslash
juxt
\backslash
nt{any-integer}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{any-integer} 
\backslash
nt{hex-integer}
\end_layout

\begin_layout Plain Layout

	
\backslash
shortor 
\backslash
nt{hex-integer}
\end_layout

\begin_layout Plain Layout

	
\backslash
shortor 
\backslash
nt{binary-integer}
\end_layout

\begin_layout Plain Layout

	
\backslash
shortor 
\backslash
nt{decimal-integer}
\end_layout

\begin_layout Plain Layout

	
\backslash
shortor 
\backslash
nt{octal-integer}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{hex-integer} 
\backslash
citerm{0X} 
\backslash
juxt
\backslash
zeroOrMore{
\backslash
nt{hex-digit}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{binary-integer} 
\backslash
citerm{0B} 
\backslash
juxt
\backslash
zeroOrMore{
\backslash
term{0}
\backslash
shortor
\backslash
term{1}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{decimal-integer} 
\backslash
term{1}-
\backslash
term{9} 
\backslash
juxt
\backslash
zeroOrMore{
\backslash
nt{digit}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{octal-integer} 
\backslash
term{0} 
\backslash
juxt
\backslash
zeroOrMore{
\backslash
term{0}-
\backslash
term{7}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{hex-digit} 
\backslash
citerm{A}-
\backslash
citerm{F}
\backslash
shortor
\backslash
nt{digit}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{SYMBOL} (
\backslash
nt{letter}
\backslash
shortor
\backslash
term{
\backslash
_}) 
\backslash
juxt
\backslash
zeroOrMore{
\backslash
nt{letter}
\backslash
shortor
\backslash
nt{digit}
\backslash
shortor
\backslash
term{
\backslash
_}}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
term{`} 
\backslash
juxt
\backslash
zeroOrMore{
\backslash
nt{escape}
\backslash
shortor
\backslash
nt{ANY}} 
\backslash
juxt
\backslash
term{`}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{STRING} 
\backslash
term{"} 
\backslash
juxt
\backslash
zeroOrMore{
\backslash
nt{escape}
\backslash
shortor 
\backslash
nt{ANY}} 
\backslash
juxt
\backslash
term{"}
\end_layout

\begin_layout Plain Layout

	
\backslash
ordef
\backslash
term{"""} 
\backslash
juxt
\backslash
zeroOrMore{
\backslash
nt{ANY}} 
\backslash
juxt
\backslash
term{"""}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{escape} 
\backslash
term{
\backslash
textbackslash{}"}
\end_layout

\begin_layout Plain Layout

	
\backslash
shortor
\backslash
term{
\backslash
textbackslash{}"}
\end_layout

\begin_layout Plain Layout

	
\backslash
shortor
\backslash
term{
\backslash
textbackslash{}'}
\end_layout

\begin_layout Plain Layout

	
\backslash
shortor
\backslash
term{
\backslash
textbackslash{}n}
\end_layout

\begin_layout Plain Layout

	
\backslash
shortor
\backslash
term{
\backslash
textbackslash{}r}
\end_layout

\begin_layout Plain Layout

	
\backslash
shortor
\backslash
term{
\backslash
textbackslash{}t}
\end_layout

\begin_layout Plain Layout

	
\backslash
shortor
\backslash
term{
\backslash
textbackslash{}
\backslash
textbackslash{}}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{letter} 
\backslash
citerm{A}-
\backslash
citerm{Z}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{digit} 
\backslash
term{0}-
\backslash
term{9}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout


\backslash
defnt{ANY} 
\backslash
emph{Any character other than} 
\backslash
term{
\backslash
textbackslash{}}.
\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\end_body
\end_document