aboutsummaryrefslogtreecommitdiff
path: root/README.adoc
blob: c519ccea9570c6e8ba90d36a13cc88c5abc1b5ed (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
ell
===
:compact-option:

'ell' is a modified subset of Scheme with added syntax sugar, incorporating
ideas from Perl, Tcl and Bourne shell.  The goal was to conceive a programming
language implementable with as little code as possible while still being
reasonably comfortable to use.

This package is an implementation of said language, meant to be self-contained,
portable and reusable.  Performance is specifically not an intent.

The project is currently in a "working proof of concept" stage.

Syntax
------
Owing to its Scheme heritage, 'ell' is homoiconic, that is a program can be
directly expressed using the language's data types.  There are only two of
those: the list and the string.  Any numerical conversions are made on an
as-needed basis.  Similarly, strings act like atoms/symbols when executed.

The parser, however, does a bunch of transformations:

 * `[a b c]` makes a call to `(list a b c)`;
 * `@var` is a shorthand for `(set var)`;
 * `{ code }` is the most complex one.  Each line within the curly braces is
   wrapped in parentheses, and the resulting list is quoted, so that it doesn't
   execute immediately.

As an example, consider the following snippet:

 print (if { eq? @var foo } {
     quote 'Hello world\n'
 } else {
     quote 'Error\n'
 })

which gets expanded to the following:

 ((print (if (quote ((eq? (set var) foo)))
             (quote ((quote 'Hello world\n')))
             else
             (quote ((quote 'Error\n'))))))

Observe that the whole program is enclosed in an implicit pair of `{}` and that
`quote` is a very powerful special form which can replace many others if needed.

Runtime
-------
All variables are put in a single global namespace with no further scoping.
Arguments to a block (which is a list of lists) must be assigned to variables
first using the `arg` special form, and that must happen before they get
overriden by execution of a different block.

When evaluating a command, the first argument is typically a string with its
name and it is resolved as if `set` was called on it.

The last expression in a block is the return value.

Special Forms
-------------
`quote <arg>`

Returns the first argument.

`arg <name>...`

Assigns arguments to the current call in order to given names.

Standard library
----------------
The standard library interprets the empty list and the empty string as false
values, everything else is taken as true.

`set <name> [<value>]`

Retrieve or set a named variable.  The syntax sugar for retrieval is `@`.

`list [<item>]...`

Return a list made of given arguments.  The syntax sugar for lists is `[]`.

`if <cond> <body> [elif <cond> <body>]... [else <body>]`

Conditional evaluation, strings evaluate to themselves.

`for <list> <body>`

Run the body for each element.

`break`

Abort the running loop.

`map <list> <body>`

Transform each element with the given function.

`filter <list> <body>`

Return a new list consisting of matching elements only.

`.. [<string>]...`

Concatenate strings.

`print [<item>]...`

Print all items in sequence--strings directly, lists as source code.

`system <command>`

Run a system command and return its return value.

`+`, `-`, `*`, `/`

Arithmetic operations on floating point numbers.

`=`, `<>`, `<`, `>`, `<=`, `>=`

Arithmetic comparisons on floating point numbers.

`eq?`, `ne?`, `lt?`, `gt?`, `le?`, `ge?`

Simple string comparisons.

Building and Running
--------------------
By default, running `make' will only build the interpreter:

 $ make
 $ ./interpreter greet.ell

Install development packages for GNU Readline to get a REPL for toying around:

 $ make repl
 $ ./repl

Contributing and Support
------------------------
Use this project's GitHub to report any bugs, request features, or submit pull
requests.  If you want to discuss this project, or maybe just hang out with
the developer, feel free to join me at irc://irc.janouch.name, channel #dev.

Bitcoin donations: 12r5uEWEgcHC46xd64tt3hHt9EUvYYDHe9

License
-------
'ell' is written by Přemysl Janouch <p.janouch@gmail.com>.

You may use the software under the terms of the ISC license, the text of which
is included within the package, or, at your option, you may relicense the work
under the MIT or the Modified BSD License, as listed at the following site:

http://www.gnu.org/licenses/license-list.html