package Positron::Expression; our $VERSION = 'v0.0.3'; # VERSION =head1 NAME Positron::Expression - a simple language for template parameters =head1 VERSION version v0.0.3 =head1 SYNOPSIS use Positron::Expression; my $env = Positron::Environment->new({ key => 'value' }); my $value = Positron::Expression::evaluate($string, $env); =head1 DESCRIPTION A simple expression language for templating constructs. The main function, C, takes an expression as a string and a L object, and evaluates the two. The result is a scalar value. =head1 GRAMMAR The grammar is basically built up of the following rules. The exact grammar is available as a package variable C<$Positron::Expression::grammar>; this is a string which is fed to L starting at the token C. =head2 Whitespace Whitespace is generally allowed between individual parts of the grammar. =head2 Literals 4 , -3.8 , "A string" , 'another string' , `a third string` The grammar allows for literal strings and numbers. Numbers are integers or floating point numbers. Notations with exponents or with different bases are not supported. Negative numbers are possible. Strings are delimited by double quotes, single quotes, or backticks. Strings cannot contain their own delimiters; with three delimiters to choose from, though, this should cover most use cases. =head2 Variable lookups a , key0 , ListValues , flag_not_possible A single, non-deliminated word is looked up in the environment; that value is returned. This may be C if the environment does not contain such a key. Words follow the rules for identifiers in most C-like languages (and Perl), in that they may start with a letter or an underscore, and contain only letters or underscores. Currently, only ASCII letters are supported; this will hopefully change in the future. =head2 Function calls a() , b(0) , find_file("./root", filename) Functions are looked up in the environment, like variables. They obey the same rules for identifiers, and are expected to return an anonymous function (a sub reference). This function is then called with the evaluated arguments. In the last example above, C is looked up in the environment, and the resulting value passed as the second argument to the function. All function calls are made in scalar context. =head2 Subselects Subselects allow you to to select a part of something else, like getting the value for a given key in a hash, or an indexed entry in a list, or call a method on an object etc. In C, these are denoted with a dot, C<.>, hence the alternative name "dotted expression". Subselects can be chained. The following subselects are possible: =head3 Array index a.0 , b.4.-1 , c.$i Arrays are indexed by appending an integer to the variable or expression holding the array. Like Perl, indices start with 0, and negative indices count from the back. The form C<< $ >> can be used to take any expression that evaluates to an integer as an index. =head3 Hash index pos.x , , authors."Ben Deutsch" , names.$current Hashes are indexed by appending a key, an identifier or string, to the variable or expression holding the hash. Most keys in practice will fit the form of an identifier as above (letters, digits, underscores). If not, a quoted string can be used. The form C<< $ >> can again be used to take any expression that evaluates to a string as the key. =head3 Object attributes obj.length , task.parent.priority , obj.$attr Object attributes work just like hash indices above, except they are called on an object and look up that attribute. (In Perl, this is the same as a method call without parameters.) =head3 Object method calls img.make_src(320, 240) , abs(int(-4.2)) Method calls work like a mixture between attributes and function calls. The method name is restricted to an actual key, however, and not a free-form string or a C<$>-expression. Like functions, methods are called in scalar context. =head2 Nested expressions hash.(var).length , ports.(resource.server) Expressions can be nested with parentheses. The C expression above is equivalent to C, since C as an expression is a variable lookup in the environment. =head2 Boolean combinations a ? !b , if ? then : else , !!empty The C, C<:> and C operands stand for "and", "or" and "not", respectively. This terminology, while a bit obscure, is the mirror of Python's C ternary operator replacement. In practice, this allows for some common use cases: =head3 Not The C operator has a higher precedence than C or C<:>, binding closer. It reverses the "truth" of the expression it precedes. B: unlike pure Perl, a reference to an empty array or an empty hash counts as false! In Perl, it would be true because all references are true, barring overloading; only non-reference empty arrays and hashes are false. Positron's use is closer related to the Perl usages of C than C, and is typically what you mean. =head3 Conditional values: And only_if ? value , first_cond ? second_cond ? result The C operator is a short-circuiting C<&&> or C equivalent. If the left hand side is false, it is returned, otherwise the right hand side is returned. It is chainable, and left associative. The most common use case is text insertion with a condition which is C<''> when false; the right hand text is only inserted if the condition is true. =head3 Defaults: Or first_try : second_try : third_try The C<:> operator is a short-circuiting C<||> or C equivalent. If the left hand side is true, it is returned, otherwise the right hand side is returned. It is chainable, left associative, and has the same precedence as C. The most common use case is to provide a chain of fallback values, selecting the first fitting (i.e. true) one. =head3 Ternary Operator if ? then : else Taken together, the C and C<:> operators form the well-known ternary operator: if the left-most term is true, the middle term is chosen; else the right-most term is. =cut use v5.10; use strict; use warnings; use Carp qw(croak); use Data::Dump qw(dump); use Positron::Environment; use Parse::RecDescent; use Scalar::Util qw(blessed); # The following grammer creates a "parse tree" our $grammar = <<'EOT'; # We start with our "boolean / ternary" expressions expression: { @{$item[1]} == 1 ? $item[1]->[0] : ['expression', @{$item[1]}]; } alternative: '!' alternative { ['not', $item[2]]; } | operand # strings and numbers cannot start a dotted expression # in fact, numbers can have decimal points. operand: string | number | lterm ('.' rterm)(s) { ['dot', $item[1], @{$item[2]}] } | lterm # The first part of a dotted expression is looked up in the environment. # The following parts are parts of whatever came before, and consequently looked # up there. lterm: '(' expression ')' { $item[2] } | funccall | identifier | '$' lterm { ['env', $item[2]] } rterm: '(' expression ')' { $item[2] } | methcall | key | string | integer | '$' lterm { $item[2] } # Strings currently cannot contain their delimiters, sorry. string: '"' /[^"]*/ '"' { $item[2] } | /\'/ /[^\']*/ /\'/ { $item[2] } | '`' /[^`]*/ '`' { $item[2] } identifier: /[a-zA-Z_]\w*/ {['env', $item[1]]} key: /[a-zA-Z_]\w*/ { $item[1] } number: /[+-]?\d+(?:\.\d+)?/ { $item[1] } integer: /[+-]?\d+/ { $item[1] } # We need "function calls" and "method calls", since with the latter, the function # is *not* looked up in the environment. funccall: identifier '(' expression(s? /\s*,\s*/) ')' { ['funccall', $item[1], @{$item[3]}] } methcall: key '(' expression(s? /\s*,\s*/) ')' { ['methcall', $item[1], @{$item[3]}] } EOT our $parser = undef; =head1 FUNCTIONS =head2 evaluate my $value = Positron::Expression::evaluate($string, $environment); Evaluates the expression in C<$string> with the L C<$env>. The result is always a scalar value, which may be a true scalar or a reference. For example, the expression C with the environment C<< { x => [1] } >> will evaluate to a reference to an array with one element. =cut sub evaluate { my ($string, $environment) = @_; my $tree = parse($string); # Force scalar context, always return scalar(_evaluate($tree, $environment)); } =head2 parse my $tree = Positron::Expression::parse($string); Parses the string in the first argument, and returns an abstract parse tree. The exact form of the tree is not important, it is usually a structure made of nested array references. The important part is that it contains no blessed references, only strings, numbers, arrays and hashes (that is, references to those). This makes it easy to serialize the tree, for distributed caching or persistant storage, if parsing time is critical. See also C to continue the evaluation. =cut sub parse { my ($string) = @_; # lazy build, why not if (not $parser) { $parser = Parse::RecDescent->new($grammar); } return $parser->expression($string); } =head2 reduce my $value = Positron::Expression::reduce($tree, $environment); The companion of C, this function takes an abstract parse tree and returns a scalar value. Essentially, my $tree = Positron::Expression::parse($string); my $value = Positron::Expression::reduce($tree, $environment); is equivalent to my $value = Positron::Expression::evaluate($string, $environment); =cut sub reduce { my ($tree, $environment) = @_; return scalar(_evaluate($tree, $environment)); } =head2 true In Perl, empty lists and hashes count as false. The only way for C to contain lists and hashes is as array or hash references. However, these count as C in Perl, even if they reference an empty array or hash. To aid decisions in templates, the function C returns a false value for references to empty arrays or hashes, and a true value for non-empty ones. Other values, such as plain scalars, blessed references, subroutine references or C, are returned verbatim. Their truth values are therefore up to Perl (a reference blessed into a package with an overloaded C method may still return false, for example. =cut sub true { my ($it) = @_; if (ref($it)) { if (ref($it) eq 'ARRAY') { return @$it; } elsif (ref($it) eq 'HASH') { return scalar(keys %$it); } else { return $it; } } else { return $it; } } sub _evaluate { my ($tree, $env, $obj) = @_; if (not ref($tree)) { return $tree; } else { my ($operand, @args) = @$tree; if ($operand eq 'env') { my $key = _evaluate($args[0], $env); return $env->get($key); } elsif ($operand eq 'funccall') { my $func = shift @args; # probably [env] $func = _evaluate($func, $env); @args = map _evaluate($_, $env), @args; return $func->(@args); } elsif ($operand eq 'methcall') { # Needs $obj argument my $func = shift @args; # probably literal $func = _evaluate($func, $env); @args = map _evaluate($_, $env), @args; return ($obj->can($func))->($obj, @args); } elsif ($operand eq 'not') { my $what = _evaluate($args[0], $env); return ! true($what); } elsif ($operand eq 'expression') { my $left = _evaluate(shift @args, $env); while (@args) { my $op = shift @args; my $right = shift @args; if ($op eq '?') { # and if (true($left)) { $left = _evaluate($right, $env); } } else { # or if (!true($left)) { $left = _evaluate($right, $env); } } } return $left; } elsif ($operand eq 'dot') { my $left = _evaluate(shift @args, $env); while (@args) { if (blessed($left)) { my $key = shift @args; if (ref($key) and ref($key) eq 'ARRAY' and $key->[0] eq 'methcall' ) { # Method, like 'funccall' but pass the object as extra parameter $left = _evaluate($key, $env, $left); } else { # Attribute or similar. # In Perl, still a method (without additional arguments) $key = _evaluate($key, $env); $left = ($left->can($key))->($left); } } elsif (ref($left) eq 'HASH') { my $key = _evaluate(shift @args, $env); $left = $left->{$key}; } elsif (ref($left) eq 'ARRAY') { my $key = _evaluate(shift @args, $env); $left = $left->[ $key ]; } else { die "Asked to subselect a scalar"; } } return $left; } } } 1; # End of Positron::Expression __END__ =head1 AUTHOR Ben Deutsch, C<< >> =head1 BUGS None known so far, though keep in mind that this is alpha software. Please report any bugs or feature requests to C, or through the web interface at L. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. =head1 SUPPORT This module is part of the Positron distribution. You can find documentation for this distribution with the perldoc command. perldoc Positron You can also look for information at: =over 4 =item * RT: CPAN's request tracker (report bugs here) L =item * AnnoCPAN: Annotated CPAN documentation L =item * CPAN Ratings L =item * Search CPAN L =back =head1 LICENSE AND COPYRIGHT Copyright 2013 Ben Deutsch. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See L for more information. =cut