diff --git a/docs/grammar.md b/docs/grammar.md index e709858..40d7643 100644 --- a/docs/grammar.md +++ b/docs/grammar.md @@ -6,18 +6,18 @@ The actual parser may do something slightly different (but equivalent) than this ## The Grammar * program ::= expr_list? _end_ * expr_list ::= expr+ -* expr ::= atom | invocation -* atom ::= _number_ | _boolean_ | _string_ | _symbol_ | lambda | _identifier_ | special_form -* invocation ::= **(** (_identifier_ | special_form) expr_list? **)** +* expr ::= atom \| invocation +* atom ::= _number_ \| _boolean_ \| _string_ \| _symbol_ \| lambda \| _identifier_ \| special_form +* invocation ::= **(** (_identifier_ \| special_form) expr_list? **)** * lambda ::= **{** params? expr **}** -* params ::= **|** identifier+ **|** -* special_form ::= **if** | **cond** | **define** | **do** | **and** | **or** +* params ::= **\|** identifier+ **\|** +* special_form ::= **if** \| **cond** \| **define** \| **do** \| **and** \| **or** ### Tokens Above, all words/characters **in bold** are token literals, while all words _in italics_ are "specially defined tokens": * _end_ is the end of the input stream. * _number_ is any "word" that can be parsed as a Rust `f64`. -* _boolean_ ::= **true** | **false** +* _boolean_ ::= **true** \| **false** * _string_ ::= **"** _c_* **"**, where _c_ is any character except `"`. There are also the escape sequences `\\`, `\n`, `\r`, `\t`, `\"`. Strings such as `"\"` and "\z" are considered invalid tokens. * _symbol_ ::= **#**_c_+, where _c_ is any character excluding whitespace. * _identifier_ is pretty much any word that doesn't conflict with another token. diff --git a/docs/index.md b/docs/index.md index a2ced8c..2d95c9a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,6 +4,7 @@ This is the main page for Psil. NOTE: most of this documentation is automatically generated! This is done using `cargo run -- --dump-docs`. To update it, update the associated Psil code, and then regenerate the docs. ## Subpages +* [A 5-minute (or less?) introduction to Psil](intro.md) * [A description of Psil's grammar](grammar.md) * modules * [boolean](modules/boolean.md) diff --git a/docs/intro.md b/docs/intro.md new file mode 100644 index 0000000..612f18a --- /dev/null +++ b/docs/intro.md @@ -0,0 +1,65 @@ +# An Introduction to Psil +This brief guide is written in the style of ["Learn X in Y minutes"](https://learnxinyminutes.com/). + +```lisp +;;; 0. Intro +; Comments are started with a semi-colon. +; Currently, there are no multiline comments. + +; Psil is a Lisp-like programming language written in Rust. +; Nothing about it is too crazy, as long as you've programmed before. +; The command `psil` without any arguments will start a Psil REPL. +; `psil file.lisp` will load and run a particlar psil file. + +;;; 1. Basic types +; We have numbers, +5 ; 5 + +; booleans, +true ; true +false ; false + +; strings, +"Hello" ; Hello + +; symbols, +#symbol ; #symbol + +; and lastly... + +;;; 2. Procedures +; The standard library includes many procedures, such as... ++ ; +put ; + +; Procedures are first-class citizens, and are their own type, as you can see. +; But obviously, they are most useful in being directly invoked, as follows: +(+ 5 5) ; 10 +(put "Hello World") ; Hello World + +; Psil uses "S-expression" syntax for these invocations. +; An invocation has the following grammar: +; (proc arg1 arg2) +; An invocation starts and ends with matching parentheses. +; Like Polish notation, the procedure being invoked goes first, then the arguments. +; A procedure might have multiple arguments, or none at all. +; Arguments may have type restrictions as well. +; As usual, consult the documentation: https://eric-unc.tech/psil/ + +; Every procedure returns something. +; If there is nothing interesting to return, returning `#void` is conventional. +; You can combine invocations together to do interesting things, like this: +(put "5*5 + 8 is... " (+ (* 5 5) 8)) ; 5*5 + 8 is... 33 + +;;; 3. Special forms +; Special forms are special kinds of procedures, but more like "keywords" from other languages. +; They are as first-class, just like other precedures, which may be unusual from other backgrounds. +; As of the current version, Psil has the following special forms: +define ; +cond ; +if ; +and ; +or ; + +; Special forms generally have special parsing or execution. +```