fpl features and syntax

Fpl is a lex/yacc/bison alternative, born of my frustration with those tools and of reading about other parser generators (such as https://pdos.csail.mit.edu/~baford/packrat/thesis/).

A more logical excuse for fpl is that at some point jest needs to be rewritten in jest, and if I use existing parser generator languages, I'm going to be tied to c or whatever language those parser generators generate. So I need something which will generate jest (unless I want to code the parser by hand, which is possible).

Key differences from other existing parser generators:

In contrast to how grammars are specified both in academic literature and in most parser-generator languages, in fpl, the tokens to match are specified on the left, and what to do with the match is on the right. I find this infinitely more intuitive - rules are generally read as "<match> is a/an <production name>, and is impemented in such and so a fashion". The language structure is on the left, the first part you read, as it's the important part. The probably-more-mutable (and anyway less important) implementation details go in the least prominent place (on the right), where they belong.
Scanning and parsing are not separate in fpl. Token specifications (e.g. regular expressions) are done in the relevant gramatical rules. Equivalent^* tokens are folded together behind the scenes. In practice, this means fewer files (and scanner/parser languages) to have to deal with.
Comment parsing can be specified in the fpl (see @comment_style, @separator directives, below)
Parsers generated by fpl will attempt to recognize one or more "goal" grammar elements and then halt, leaving the input read position at the end of the last thing recognized. This allows callers to mix top down and bottom up parsing - bottom up constructs can be specified in fpl and used from top-down (or other) parsers to parse specific cases. Among the use cases for this are embedded doc comments, other languages, etc. Maybe I can slap together some examples.

Directives

Valid directives are:

@comment_style
@default_action
@default_main
@post_parse
@produces (required) - tells the parser generator what type is to be returned from code generation rules and from the generated parser itself. For c++, the type must be to_string compatible - if it's not already (and I'm really sorry about this), you must specify a to_string() function in a code block prior to any rules.
For example:
```
          
          +{
              std::string to_string(const &my_type x) {
                  return x.convert_to_string_or_whatever();
              }
          }+
        
```

examples

@separator

Production rules

Production rules are of the form:

        <exprs to match> -> <production name> { <code> }
                   or
        <exprs to match> -> <production name> ;

Expressions may be any of:

quoted string (eg "xxx" or 'yyy')
regular expression within slashes (eg /0x[0-9a-fA-F]+/)
names of other productions as plain text (no spaces)

The first 2 effectively specify scan tokens. Single or double quotes are equivalent, and specify an exact match to look for. Regular expressions can be used to specify The third case specifies

Expressions may be followed directly by (no space) one of *, +, or ? to mean 0-or-more, 1-or-more, or 0-or-1 respectively.

Examples:

        # a very basic calculator

        @produces int

        aexpr '+' mexpr -> aexpr +{ return arg_0 + arg_2; }+
        aexpr '-' mexpr -> aexpr +{ return arg_0 - arg_2; }+
        mexpr           -> aexpr ;

        mexpr '*' term  -> mexpr +{ return arg_0 * arg_2; }+
        mexpr '/' term  -> mexpr +{ return arg_0 / arg_2; }+
        mexpr '%' term  -> mexpr +{ return arg_0 % arg_2; }+
        term            -> mexpr ;

        '-' term        -> term +{ return -arg_1; }+
        '(' aexpr ')'   -> term +{ return arg_1;  }+
        /[0-9]+/        -> term +{
            return std::stoi(arg_0);
        }+

^* With regular expressions, you can trick fpl2cc into having ambiguous, "secretly" equivalent, or overlapping tokens. For example, it won't know that /[1-3]/ and /[123]/ are equivalent or that /[a-z]+/ and

/[a-f]+/ can both
        match some of the same strings.
        In practice this mostly does not matter, but I recommend you
        keep your regexes tidy and minimal to avoid any surprises.