1Math::Symbolic::CompileUrs(e3r)Contributed Perl DocumentMaattiho:n:Symbolic::Compiler(3)
2
3
4

NAME

6       Math::Symbolic::Compiler - Compile Math::Symbolic trees to Perl code
7

SYNOPSIS

9         use Math::Symbolic::Compiler;
10
11         # A tree to compile
12         my $tree = Math::Symbolic->parse_from_string('a^2 + b * c * 2');
13
14         # The Math::Symbolic::Variable 'a' will be evaluated to $_[1], etc.
15         my $vars = [qw(b a c)];
16
17         my ($closure, $code, $trees) =
18           Math::Symbolic::Compiler->compile($tree, $vars);
19
20         print $closure->(2, 3, 5); # (b, a, c)
21         # prints 29 (= 3^2 + 2 * 5 * 2)
22
23         # or:
24         ($closure, $trees) =
25           Math::Symbolic::Compiler->compile_to_sub($tree, $vars);
26
27         ($code, $trees) = Math::Symbolic::Compiler->compile_to_code($tree, $vars);
28

DESCRIPTION

30       This module allows one to compile Math::Symbolic trees to Perl code
31       and/or anonymous subroutines whose arguments will be positionally
32       mapped to the variables of the compiled Math::Symbolic tree.
33
34       The reason you'd want to do this is that evaluating a Math::Symbolic
35       tree to its numeric value is extremely slow. So is compiling, but once
36       you've done all necessary symbolic calculations, you can take advantage
37       of the speed gain of invoking a closure instead of evaluating a tree.
38
39   UNCOMPILED LEFTOVER TREES
40       Not all, however, is well in the land of compiled Math::Symbolic trees.
41       There may occasionally be trees that cannot be compiled (such as a
42       derivative) which need to be included into the code as trees. These
43       trees will be returned in a referenced array by the compile*() methods.
44       The closures will have access to the required trees as a special
45       variable '@_TREES inside the closure's scope, so you need not worry
46       about them in that case. But if you plan to use the generated code
47       itself, you need to supply an array named @_TREES that contains the
48       trees as returned by the compile*() methods in the scope of the eval()
49       you evaluate the code with.
50
51       Note that you give away all performance benefits compiling the tree
52       might have if the closure contains uncompiled trees. You can tell there
53       are any by checking the length of the referenced array that contains
54       the trees. If it's 0, then there are no trees left to worry about.
55
56   AVOIDING LEFTOVER TREES
57       In most cases, this is pretty simple. Just apply all derivatives in the
58       tree to make sure that there are none left in the tree. As of version
59       0.130, there is no operator except derivatives that cannot be compiled.
60       There may, however, be some operators you cannot get rid of this easily
61       some time in the future.  If you have problems getting a tree to
62       compile, try using the means of simplification provided by
63       Math::Symbolic::* to get a simpler tree for compilation.
64
65   EXPORT
66       None by default, but you may choose to import the compile(),
67       compile_to_sub(), and compile_to_code() subroutines to your namespace
68       using the standard Exporter semantics including the ':all' tag.
69

SUBROUTINES

71   ($code, $trees) = compile_to_code($tree, $vars)
72       The compile_to_code() class method takes one mandatory argument which
73       is the Math::Symbolic tree to be compiled. Second argument is optional
74       and an array reference to an array of variable mappings.  See "VARIABLE
75       PASSING STYLES" for details on how this works.
76
77       compile_to_code() returns a string and an array reference. The string
78       contains the compiled Perl code that uses the values stored in @_ as
79       described in the section on positional variable passing. It also
80       accesses a special variable @_TREES if there were any sub-trees (inside
81       the tree that has been compiled) that were impossible to compile. The
82       array reference returned by this method contains any of the
83       aforementioned trees that failed to compile.
84
85       If there are any such trees that did not compile, you may put them into
86       the @_TREES variable in scope of the eval() that evaluates the compiled
87       code in the same order that they were returned by this method. If you
88       do that, the code will run and determine the value of the tree at run-
89       time. Needless to say, that is slow.
90
91   ($sub, $trees) = compile_to_sub($tree, $vars)
92       The compile_to_sub() class method takes one mandatory argument which is
93       the Math::Symbolic tree to be compiled. Second argument is optional and
94       an array reference to an array of variable mappings.  See "VARIABLE
95       PASSING STYLES" for details on how this works.
96
97       compile_to_sub() returns a list of two elements, the first being the
98       compiled anonymous subroutine. For details on the second element,
99       please refer to the docs on the compile_to_code() subroutine.
100
101   ($sub, $code, $trees) = compile($tree, $vars)
102       The compile() class method takes one mandatory argument which is the
103       Math::Symbolic tree to be compiled. Second argument is optional and an
104       array reference to an array of variable mappings.  See "POSITIONAL
105       VARIABLE PASSING" for details on how this works.
106
107       compile() returns a list of three elements, the first being the
108       compiled anonymous subroutine, the second being the compiled code. For
109       details on the second and third elements, please refer to the docs on
110       the compile_to_code() subroutine.
111
112   VARIABLE PASSING STYLES
113       Currently, the Math::Symbolic compiler only supports compiling to subs
114       with positional variable passing. At some point, the user should be
115       able to choose between positional- and named variable passing styles.
116       The difference is best explained by an example:
117
118         # positional:
119         $sub->(4, 5, 1);
120
121         # named: (NOT IMPLEMENTED!)
122         $sub->(a => 5, b => 4, x => 1);
123
124       With positional variable passing, the subroutine statically maps its
125       arguments to its internal variables. The way the subroutine does that
126       has been fixed at compile-time. It is determined by the second argument
127       to the various compile_* functions found in this package. This second
128       argument is expected to be a reference to an array of variable names.
129       The order of the variable names determines which parameter of the
130       compiled sub will be assigned to the variable. Example:
131
132         my ($sub) =
133           Math::Symbolic::Compiler->compile_to_sub($tree, [qw/c a b/]);
134
135         # First argument will be mapped to c, second to a, and third to b
136         # All others will be ignored.
137         $sub->(4, 5, 6, 7);
138
139         # Variable mapping: a = 5, b = 6, c = 4
140
141       One important note remains: if any (or all) variables in the tree are
142       unaccounted for, they will be lexicographically sorted and appended to
143       the variable mapping in that order. That means if you don't map
144       variables yourself, they will be sorted lexicographically.
145
146       Thanks to Henrik Edlund's input, it's possible to pass a hash reference
147       as second argument to the compile* functions instead of an array
148       reference.  The order of the mapped variables is then determined by
149       their associated value, which should be an integer starting with 0.
150       Example:
151
152         Math::Symbolic::Compiler->compile_to_sub($tree, {b => 2, a => 1, c => 0});
153
154       Would result in the order c, a, b.
155

AUTHOR

157       Please send feedback, bug reports, and support requests to the
158       Math::Symbolic support mailing list: math-symbolic-support at lists dot
159       sourceforge dot net. Please consider letting us know how you use
160       Math::Symbolic. Thank you.
161
162       If you're interested in helping with the development or extending the
163       module's functionality, please contact the developers' mailing list:
164       math-symbolic-develop at lists dot sourceforge dot net.
165
166       List of contributors:
167
168         Steffen Mueller, symbolic-module at steffen-mueller dot net
169         Stray Toaster, mwk at users dot sourceforge dot net
170         Oliver Ebenhoeh
171

SEE ALSO

173       New versions of this module can be found on http://steffen-mueller.net
174       or CPAN. The module development takes place on Sourceforge at
175       http://sourceforge.net/projects/math-symbolic/
176
177       Math::Symbolic
178
179
180
181perl v5.32.1                      2021-01-27       Math::Symbolic::Compiler(3)
Impressum