paulstansifer / unseemly

Macros have types!
http://unseemly.github.io/
MIT License
129 stars 5 forks source link

Improve documentation by including concrete examples next to syntax definitions #34

Open colelawrence opened 4 years ago

colelawrence commented 4 years ago

Hi Paul,

I'm highly interested in understanding how unseemly works, and have been studying the notes and examples in the repo for an hour with the REPL open trying out different things. Currently, I'm having a lot of trouble figuring out some of the basics like what an expression is and isn't, and how, when, and where I am supposed to use types.

So, my suggestion is that, for new comers, I think we could make the onboarding experience much easier by adding concrete code samples for each piece of syntax so it's easy to see syntax punctuations next to usages.

For example:

## Expressions
* `(expr expr ⋯)` is function application.

Examples

    (plus one one) # => 2
    (zero? one) # => +[False]+

Adding things that can be put into the REPL for trying and remixing would be helpful to understand these other basic constructs:

* `.[ x: Type  ⋯ . expr ].` is lambda.

* `match expr { pat => expr  ⋯ }` is a pattern match.

* `+[Choice expr ⋯]+ : Type` constructs an enumerated value.
    The type annotation is weird, but it helps keep the typechecker simple.

* `*[component: expr ⋯]*` constructs a structure value.

* `forall X ⋯ . expr` abstracts over a type. It is typically used around lambdas.

* `unfold expr` pulls one layer of `mu` off a recursively-typed value.
    It is almost exclusively used for the scrutinee in `match`.

An aside, I don't see ::= documented anywhere, yet it seems to be a building block of the language.

Thanks!