NAME

Language::FormulaEngine::Namespace - Object holding function and variable names

VERSION

version 0.06

SYNOPSIS

  my $ns= Language::FormulaEngine::Namespace->new( values => \%val_by_name );

DESCRIPTION

A FormulaEngine Namespace is an object that provides a set of functions and named values. It can also affect language semantics through it's implementation of those functions.

The default implementation provides all functions of its own namespace which begin with the prefix "fn_" or "eval_", and provides them case-insensitive. Named values are provided from hashrefs of "constants" and "variables", also case-insensitive.

You can subclass this (or just write a class with the same interface) to provide more advanced lookup for the functions or values.

ATTRIBUTES

variables

A hashref of name => value which formulas may reference. The keys should be lowercase, and incoming variable requests will be converted to lowercase before checking this hash. Variables will not be "compiled" into perl coderefs, and will be looked up from the namespace every time a formula is evaluated.

constants

Same as "variables", but these may be compiled into coderefs.

die_on_unknown_value

Controls behavior of "get_value". If false (the default) unknown symbol names will resolve as perl undef values. If true, unknown symbol names will throw an ErrREF exception.

METHODS

clone

  my $ns2= $ns1->clone(variables => \%different_vars);

Return a copy of the namespace, optionally with some attributes overridden.

clone_and_merge

  my $ns2= $ns1->clone_and_merge(variables => \%override_some_vars);

Return a copy of the namespace, with any new attributes merged into the existing ones.

get_constant

  my $val= $ns->get_constant( $symbolic_name );

Mehod to check for availability of a named constant, before assuming that a name is a variable. This never throws an exception; it returns undef if no constant exists by that name.

get_value

  my $val= $ns->get_value( $symbolic_name );

Lowercases $symbolic_name and then looks in variables or constants. May die depending on setting of "die_on_unknown_value".

get_function

  $ns->get_function( $symbolic_name );
  
  # Returns:
  # {
  #   native         => $coderef,
  #   evaluator      => $method,
  #   perl_generator => $method,
  # }

If a function by this name is available in the namespace, ths method returns a hashref of information about it. It may include some or all of the following:

native

A native perl implementation of this function. Speficially, a non-method plain old function that takes a list of values (not parse nodes) and returns the computed value.

Note that if Sub::Util::subname($native) returns a name with colons in it, the compiler will assume it is safe to inline this function name into the generated perl code. (but this only happens if perl_generator was not available)

evaluator

A coderef or method name which will be called on the namespace to evaluate a parse tree for this function.

  $value= $namespace->$evaluator( $parse_node );

perl_generator

A coderef or method name which will be called on the namespace to convert a parse tree into perl source code.

  $perl= $namespace->$generator( $compiler, $parse_node );

The default implementation lowercases the $symbolic_name and then checks for three method names: $self->can("fn_$name"), $self->can("nodeval_$name") and $self->can("perlgen_$name").

evaluate_call

  my $value= $namespace->evaluate_call( $Call_parse_node );

Evaluate a function call, passing it either to a specialized evaluator or performing a more generic evaluation of the arguments followed by calling a native perl function.

find_methods

Find methods on this object that match a regex.

  my $method_name_arrayref= $ns->find_methods(qr/^fn_/);

FUNCTION LIBRARY

Theis base Namespace class does not contain any user-visible functions; those are found within the sub-classes such Language::FormulaEngine::Namespace::Default.

AUTHOR

Michael Conrad <mconrad@intellitree.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by Michael Conrad, IntelliTree Solutions llc.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Language::FormulaEngine

perl -MCPAN -e shell
install Language::FormulaEngine