Turtorial

[tmbb]

ExSpirit need an awesome tutorial.

I suggest something like this and might even help:

1. Quickstart: pretend ExSpirit is a PEG parser. Explain the combinators and show some simple examples. Everything is based on defrule.

2. In-depth Guide: Part 1: Parsers are just functions that turn a context into a new context. By sheer coincidence, the context can be interpreted on parsing over a string, but this mindset shouldn't be encouraged too much. Develop this idea a little

3. In-depth Guide: Part 2: Beyond PEG parsers. The state system and how it can be useful. How to use userdata to keep state or evaluate rules on demand

4. In-depth guide: Part 3: Writing your own parser primitives. Abstract common patterns with macros makeup_elixir's source is a good example.

5. Examples:

   • lexers for programming languages (makeup). Exercise for the reader: write a lexer for your favourite programming language xD
   • parsing an indentation-specific language
   • writing your own lisp (because it's a classic and lisp is easy to prse lol)

[OvermindDL1]

ExSpirit need an awesome tutorial.

Entirely agree! Maybe even model it on C++'s Spirit library's tutorial. :-) C++ Spirit Documentation (Specifically the Qi and Advanced sections): http://www.boost.org/doc/libs/1_64_0/libs/spirit/doc/html/index.html

Quickstart: pretend ExSpirit is a PEG parser. Explain the combinators and show some simple examples. Everything is based on defrule.

Indeed, though in the intro probably mention very early that it can do a lot more than just PEG grammars, but PEG is the general use-case so this is where it is starting.

2. ...
3. ...
4. ...

:+1:

Examples:

Definitely, C++ Spirit's docs have you build everything from roman numeral parsing to a mini-xml parser to a calculator parser to even a full blown C/C++ Preprocessor parser (pulled out into another repo since it ended up actually being useful on its own ^.^;)

And yep, lisp is so easy, could even show how to interpret it 'while' parsing it too!

[tmbb]

And yep, lisp is so easy, could even show how to interpret it 'while' parsing it too!

You can just port this: https://en.wikibooks.org/wiki/Write_Yourself_a_Scheme_in_48_Hours. I think that's what they do. On the other hand, I'd be more impressed with a lisp compiler that supported lisp macros. I don't know how hard that is, though.

[tmbb]

Entirely agree! Maybe even model it on C++'s Spirit library's tutorial. :-)

The Spirit docs look amazing, but for someone who doesn't read C++ they seem quite impenetrable xD

[OvermindDL1]

On the other hand, I'd be more impressed with a lisp compiler that supported lisp macros. I don't know how hard that is, though.

/me coughs

Stupid-easy. ^.^

https://github.com/OvermindDL1/llixer/tree/master/lib/llixer/simple https://github.com/OvermindDL1/llixer/tree/master/test/llixer/simple

Examples:

iex(1)> import Llixer.Simple
Llixer.Simple
iex(2)> ~L(42)              
** (throw) {:MISSING_REQUIRED_NAME, {:fun, "42"}}
    (llixer) lib/llixer/simple/env.ex:58: Llixer.Simple.Env.get!/2
    (llixer) lib/llixer/simple/evaluator.ex:15: Llixer.Simple.Evaluator.eval_sexpr/2                                                
    (llixer) expanding macro: Llixer.Simple.sigil_L/2                                                                               
    iex:2: (file)                                                                                                                   
iex(2)> ~L(integer 42)
42
iex(3)> # As you can see only two types are known, lists and symbols, not even `42` is an integer                           
nil
iex(4)> # unless you pass it to the `integer` special-form call, which converts a symbol to an integer
nil
iex(5)> ~L(atom test)
:test
iex(6)> # Also supporting read-macro's, I have a read macro that reads a `:` then a symbol and turns it into that above
nil
iex(7)> ~L(:test)u    
:test
iex(8)> # Can quote and unquote and quasiquote all too, with read-macro's that add the usual `,` and `@` and \` as well      
nil
iex(9)> ~L"(quote (test a thing))"u
["test", "a", "thing"]

And it is all able to recursively call back to the parser and all as needed. ^.^

The Spirit docs look amazing, but for someone who doesn't read C++ they seem quite impenetrable xD

That is just C++ template magic. ;-)

[tmbb]

Stupid-easy. ^.^

I meant lisp macros defined in lisp xD Lisp macros defined in elixir (including read macros) are obviously easy.

[OvermindDL1]

I meant lisp macros defined in lisp xD Lisp macros defined in elixir (including read macros) are obviously easy.

I havn't made a function for it yet but it would be fairly trivial to do so. Just a function definition that that loads itself into the quote table instead of the function table.

[tmbb]

I've just noticed that the title of this issue reads "Turtorial". Please don't change it. I like it.

[OvermindDL1]

I've just noticed that the title of this issue reads "Turtorial". Please don't change it. I like it.

Lol, I noticed it as well when its notification popped up. ^.^