1Imager::Expr(3)       User Contributed Perl Documentation      Imager::Expr(3)
2
3
4

NAME

6       Imager::Expr - implements expression parsing and compilation for the
7       expression evaluation engine used by Imager::transform2()
8

SYNOPSIS

10       my $code = Imager::Expr->new({rpnexpr=>$someexpr})
11         or die "Cannot compile $someexpr: ",Imager::Expr::error();
12

DESCRIPTION

14       This module is used internally by the Imager::transform2() function.
15       You shouldn't have much need to use it directly, but you may want to
16       extend it.
17
18       To create a new Imager::Expr object, call:
19
20        my %options;
21        my $expr = Imager::Expr->new(\%options)
22          or die Imager::Expr::error();
23
24       You will need to set an expression value and you may set any of the
25       following:
26
27       •   constants
28
29           A hashref defining extra constants for expression parsing.  The
30           names of the constants must be valid identifiers (/[^\W\d]\w*/) and
31           the values must be valid numeric constants (that Perl recognizes in
32           scalars).
33
34           Imager::Expr may define it's own constants (currently just pi.)
35
36       •   variables
37
38           A reference to an array of variable names.  These are allocated
39           numeric registers starting from register zero.
40
41       By default you can define a "rpnexpr" key (which emulates RPN) or
42       "expr" (an infix expression).  It's also possible to write other
43       expression parsers that will use other keys.  Only one expression key
44       should be defined.
45
46   Instance methods
47       The Imager::Expr::error() method is used to retrieve the error if the
48       expression object cannot be created.
49
50   Methods
51       Imager::Expr provides only a few simple methods meant for external use:
52
53       Imager::Expr->type_registered($keyword)
54           Returns true if the given expression type is available.  The
55           parameter is the key supplied to the new() method.
56
57             if (Imager::Expr->type_registered('expr')) {
58               # use infix expressions
59             }
60
61       $expr->code()
62           Returns the compiled code.
63
64       $expr->nregs()
65           Returns a reference to the array of numeric registers.
66
67       $expr->cregs()
68           Returns a reference to the array of color registers.
69
70       $expr->dumpops()
71           Returns a string with the generated VM "machine code".
72
73       $expr->dumpcode()
74           Returns a string with the disassembled VM "machine code".
75
76   Creating a new parser
77       I'll write this one day.
78
79       Methods used by parsers:
80
81       compile
82           This is the main method you'll need to implement in a parser.  See
83           the existing parsers for a guide.
84
85           It's supplied the following parameters:
86
87           •   $expr - the expression to be parsed
88
89           •   $options - the options hash supplied to transform2.
90
91           Return an array ref of array refs containing opcodes and operands.
92
93       @vars = $self->_variables()
94           A list (not a reference) of the input variables.  This should be
95           used to allocate as many registers as there are variable as input
96           registers.
97
98       $self->error($message)
99           Set the return value of Imager::Expr::error()
100
101       @ops = $self->stack_to_reg(@stack_ops)
102           Converts marginally parsed RPN to register code.
103
104       assemble()
105           Called to convert op codes into byte code.
106
107       numre()
108           Returns a regular expression that matches floating point numbers.
109
110       optimize()
111           Optimizes the assembly code, including attempting common
112           subexpression elimination and strength reducing division by a
113           constant into multiplication by a constant.
114
115       register_type()
116           Called by a new expression parser implementation to register
117           itself, call as:
118
119             YourClassName->register_type('type code');
120
121           where type code is the parameter that will accept the expression.
122
123   Future compatibility
124       Try to avoid doing your own optimization beyond literal folding - if we
125       add some sort of jump, the existing optimizer will need to be
126       rewritten, and any optimization you perform may well be broken too
127       (well, your code generation will probably be broken anyway <sigh>).
128

AUTHOR

130       Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
131
132
133
134perl v5.36.0                      2022-07-22                   Imager::Expr(3)
Impressum