1Math::Symbolic::CompileUrs(e3r)Contributed Perl DocumentMaattiho:n:Symbolic::Compiler(3)
2
6 Math::Symbolic::Compiler - Compile Math::Symbolic trees to Perl code
7
9 use Math::Symbolic::Compiler;
10 # A tree to compile
12 my $tree = Math::Symbolic->parse_from_string('a^2 + b * c * 2');
13 # The Math::Symbolic::Variable 'a' will be evaluated to $_[1], etc.
15 my $vars = [qw(b a c)];
16 my ($closure, $code, $trees) =
18 Math::Symbolic::Compiler->compile($tree, $vars);
19 print $closure->(2, 3, 5); # (b, a, c)
21 # prints 29 (= 3^2 + 2 * 5 * 2)
22 # or:
24 ($closure, $trees) =
25 Math::Symbolic::Compiler->compile_to_sub($tree, $vars);
26 ($code, $trees) = Math::Symbolic::Compiler->compile_to_code($tree, $vars);
28
30 This module allows to compile Math::Symbolic trees to Perl code and/or
31 anonymous subroutines whose arguments will be positionally mapped to
32 the variables of the compiled Math::Symbolic tree.
33 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 UNCOMPILED LEFTOVER TREES
40 Not all, however, is well in the land of compiled Math::Symbolic trees.
42 There may occasionally be trees that cannot be compiled (such as a de‐
43 rivative) which need to be included into the code as trees. These trees
44 will be returned in a referenced array by the compile*() methods. The
45 closures will have access to the required trees as a special variable
46 '@_TREES inside the closure's scope, so you need not worry about them
47 in that case. But if you plan to use the generated code itself, you
48 need to supply an array named @_TREES that contains the trees as
49 returned by the compile*() methods in the scope of the eval() you eval‐
50 uate the code with.
51 Note that you give away all performance benefits compiling the tree
53 might have if the closure contains uncompiled trees. You can tell there
54 are any by checking the length of the referenced array that contains
55 the trees. If it's 0, then there are no trees left to worry about.
56 AVOIDING LEFTOVER TREES
58 In most cases, this is pretty simple. Just apply all derivatives in the
60 tree to make sure that there are none left in the tree. As of version
61 0.130, there is no operator except derivatives that cannot be compiled.
62 There may, however, be some operators you cannot get rid of this easily
63 some time in the future. If you have problems getting a tree to com‐
64 pile, try using the means of simplification provided by Math::Sym‐
65 bolic::* to get a simpler tree for compilation.
66 EXPORT
68 None by default, but you may choose to import the compile(), com‐
70 pile_to_sub(), and compile_to_code() subroutines to your namespace
71 using the standart Exporter semantics including the ':all' tag.
72
74 ($code, $trees) = compile_to_code($tree, $vars)
75 The compile_to_code() class method takes one mandatory argument which
77 is the Math::Symbolic tree to be compiled. Second argument is optional
78 and an array reference to an array of variable mappings. See "VARIABLE
79 PASSING STYLES" for details on how this works.
80 compile_to_code() returns a string and an array reference. The string
82 contains the compiled Perl code that uses the values stored in @_ as
83 described in the section on positional variable passing. It also
84 accesses a special variable @_TREES if there were any sub-trees (inside
85 the tree that has been compiled) that were impossible to compile. The
86 array reference returned by this method contains any of the aforemen‐
87 tioned trees that failed to compile.
88 If there are any such trees that did not compile, you may put them into
90 the @_TREES variable in scope of the eval() that evaluates the compiled
91 code in the same order that they were returned by this method. If you
92 do that, the code will run and determine the value of the tree at
93 run-time. Needless to say, that is slow.
94 ($sub, $trees) = compile_to_sub($tree, $vars)
96 The compile_to_sub() class method takes one mandatory argument which is
98 the Math::Symbolic tree to be compiled. Second argument is optional and
99 an array reference to an array of variable mappings. See "VARIABLE
100 PASSING STYLES" for details on how this works.
101 compile_to_sub() returns a list of two elements, the first being the
103 compiled anonymous subroutine. For details on the second element,
104 please refer to the docs on the compile_to_code() subroutine.
105 ($sub, $code, $trees) = compile($tree, $vars)
107 The compile() class method takes one mandatory argument which is the
109 Math::Symbolic tree to be compiled. Second argument is optional and an
110 array reference to an array of variable mappings. See "POSITIONAL
111 VARIABLE PASSING" for details on how this works.
112 compile() returns a list of three elements, the first being the com‐
114 piled anonymous subroutine, the second being the compiled code. For
115 details on the second and third elements, please refer to the docs on
116 the compile_to_code() subroutine.
117 VARIABLE PASSING STYLES
119 Currently, the Math::Symbolic compiler only supports compiling to subs
121 with positional variable passing. At some point, the user should be
122 able to choose between positional- and named variable passing styles.
123 The difference is best explained by an example:
124 # positional:
126 $sub->(4, 5, 1);
127 # named: (NOT IMPLEMENTED!)
129 $sub->(a => 5, b => 4, x => 1);
130 With positional variable passing, the subroutine statically maps its
132 arguments to its internal variables. The way the subroutine does that
133 has been fixed at compile-time. It is determined by the second argument
134 to the various compile_* functions found in this package. This second
135 argument is expected to be a reference to an array of variable names.
136 The order of the variable names determines which parameter of the com‐
137 piled sub will be assigned to the variable. Example:
138 my ($sub) =
140 Math::Symbolic::Compiler->compile_to_sub($tree, [qw/c a b/]);
141 # First argument will be mapped to c, second to a, and third to b
143 # All others will be ignored.
144 $sub->(4, 5, 6, 7);
145 # Variable mapping: a = 5, b = 6, c = 4
147 One important note remains: if any (or all) variables in the tree are
149 unaccounted for, they will be lexicographically sorted and appended to
150 the variable mapping in that order. That means if you don't map vari‐
151 ables yourself, they will be sorted lexicographically.
152 Thanks to Henrik Edlund's input, it's possible to pass a hash reference
154 as second argument to the compile* functions instead of an array refer‐
155 ence. The order of the mapped variables is then determined by their
156 associated value, which should be an integer starting with 0. Example:
157 Math::Symbolic::Compiler->compile_to_sub($tree, {b => 2, a => 1, c => 0});
159 Would result in the order c, a, b.
161
163 Please send feedback, bug reports, and support requests to the
164 Math::Symbolic support mailing list: math-symbolic-support at lists dot
165 sourceforge dot net. Please consider letting us know how you use
166 Math::Symbolic. Thank you.
167 If you're interested in helping with the development or extending the
169 module's functionality, please contact the developers' mailing list:
170 math-symbolic-develop at lists dot sourceforge dot net.
171 List of contributors:
173 Steffen Müller, symbolic-module at steffen-mueller dot net
175 Stray Toaster, mwk at users dot sourceforge dot net
176 Oliver Ebenhöh
177
179 New versions of this module can be found on http://steffen-mueller.net
180 or CPAN. The module development takes place on Sourceforge at
181 http://sourceforge.net/projects/math-symbolic/
182 Math::Symbolic
184perl v5.8.8 2008-02-22 Math::Symbolic::Compiler(3)