/ 
Language-FormulaEngine-0.08
River stage zero No dependents
/ Language::FormulaEngine::Namespace

NAME

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

VERSION

version 0.08

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.

simplify_call

$new_tree= $namespace->simplify_call( $parse_tree );

Create a simplified formula by reducing variables and evaluating functions down to constants. If all variables required by the formula are defined, and true functions without side effects, this will return a single parse node which is a constant the same as evaluate() would return.

simplify_symref

$parse_node= $namespace->simplify_symref( $parse_node );

This is a helper for the "simplify" mechanism that returns a parse node holding the constant value of $self->get_value($name) if the value is defined, else passes-through the same parse node.

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) 2023 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.