NAME

JE::Parser - Framework for customising JE's parser

SYNOPSIS

  use JE;
  use JE::Parser;
  $je = new JE;
  $p = new JE::Parser $je; # or: $p = $je->new_parser
  $p->delete_statement('for', 'while', 'do'); # disable loops
  $p->add_statement(try => \&parser); # replace existing 'try' statement

DESCRIPTION

This allows one to change the list of statement types that the parser looks for. For instance, one could disable loops for a mini-JavaScript, or add extensions to the language, such as the 'catch-if' clause of a "try" statement.

As yet, "delete_statement" works, but I've not finished designing the API for "add_statement".

I might provide an API for extending expressions, if I can resolve the complications caused by the 'new' operator. If anyone else wants to have a go at it, be my guest. :-)

METHODS

$p = new JE::Parser

Creates a new parser object.

$p->add_statement($name, \&parser);

This adds a new statement (source element, to be precise) type to the list of statements types the parser supports. If a statement type called $name already exists, it will be replaced. Otherwise, the new statement type will be added to the top of the list.

($name ought to be optional; it should only be necessary if one wants to delete it afterwards or rearrange the list.)

If the name of a statement type begins with a hyphen, it is only allowed at the 'program' level, not within compound statements. Function declarations use this. Maybe this convention is too unintuitive.... (Does anyone think I should change it? What should I change it too?)

&parser will need to parse code contained in $_ starting at "pos()", then either return an object, list or coderef (see below) and set "pos()" to the position of the next token[1], or, if it could not parse anything, return undef and reset "pos()" to its initial value if it changed.

[1] I.e., it is expected to move "pos" past any trailing whitespace.

The return value of &parser can be one of the following:

$p->delete_statement(@names);

Deletes the given statement types and returns $p.

$p->statement_list

(Not yet implemented.)

Returns an array ref of the names of the various statement types. You can rearrange this list, but it is up to you to make sure you do not add to it any statement types that have not been added via "add_statement" (or were not there by default). The statement types in the list will be tried in order, except that items beginning with a hyphen always come before other items.

The default list is "qw/-function block empty if while with for switch try labelled var do continue break return throw expr/"

$p->parse($code)

Parses the $code and returns a parse tree (JE::Code object).

$p->eval($code)

Shorthand for $p->parse($code)->execute;

EXPORTS

None by default. You may choose to export the following:

SYNTAX ERRORS

(To be written)

  expected 'aaaa'; # will be changed to 'Expected aaaa but found....'
  die \\"You can't put a doodad after a frombiggle!"; # complete message
  die 'aoenstuhoeanthu'; # big no-no (the error is propagated)

EXAMPLES

  use JE;
  $j = new JE;
  $p = $j->new_parser;
  $p->delete_statement('for','while','do','-function');

  $j->prop({ name     => 'Function',
             value    => undef,
             readonly => 1,
             dontdel  => 1 });

  use JE;
  use JE::Parser qw'$s ident expr statement expected';
  
  $j = new JE;
  $p = $j->new_parser;
  $p->add_statement('for-list',
      sub {
          /\Gfor$s/cog or return;
          my $loopvar = ident or return;
          /\G$s\($s/cog or return;
          my @expressions;
          do {
              # This line doesn't actually work properly because
              # 'expr' will gobble up all the commas
              @expressions == push @expressions, expr
                  and return; # If nothing gets pushed on  to  the
                              # list,  we need to give the default
                              # 'for' handler a chance, instead of
                              # throwing an error.
          } while /\G$s,$s/cog;
          my $statement = statement or expected 'statement';
          return bless {
              var => $loopvar,
              expressions => \@expressions,
              statement => $statement
          }, 'Local::JEx::ForList';
      }
  );
  
  package Local::JEx::ForList;
  
  sub eval {
      my $self = shift;
      local $JE::Code::scope =
          bless [@$JE::Code::scope], 'JE::Scope';
          # I've got to come up with a better interface than this.
      my $obj = $JE::Code::global->eval('new Object');
      push @$JE::Code::scope, $obj;
      for (@{$self->{expressions}}) {
          $obj->{ $self->{loopvar} } = $_->eval;
          $self->{statement}->execute;
      }
  }

SEE ALSO

JE and JE::Code.