1Imager::Expr(3) User Contributed Perl Documentation Imager::Expr(3)
2
6 Imager::Expr - implements expression parsing and compilation for the
7 expression evaluation engine used by Imager::transform2()
8
10 my $code = Imager::Expr->new({rpnexpr=>$someexpr})
11 or die "Cannot compile $someexpr: ",Imager::Expr::error();
12
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 To create a new Imager::Expr object, call:
19 my %options;
21 my $expr = Imager::Expr->new(\%options)
22 or die Imager::Expr::error();
23 You will need to set an expression value and you may set any of the
25 following:
26 • constants
28 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 Imager::Expr may define it's own constants (currently just pi.)
35 • variables
37 A reference to an array of variable names. These are allocated
39 numeric registers starting from register zero.
40 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 Instance methods
47 The Imager::Expr::error() method is used to retrieve the error if the
48 expression object cannot be created.
49 Methods
51 Imager::Expr provides only a few simple methods meant for external use:
52 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 if (Imager::Expr->type_registered('expr')) {
58 # use infix expressions
59 }
60 $expr->code()
62 Returns the compiled code.
63 $expr->nregs()
65 Returns a reference to the array of numeric registers.
66 $expr->cregs()
68 Returns a reference to the array of color registers.
69 $expr->dumpops()
71 Returns a string with the generated VM "machine code".
72 $expr->dumpcode()
74 Returns a string with the disassembled VM "machine code".
75 Creating a new parser
77 I'll write this one day.
78 Methods used by parsers:
80 compile
82 This is the main method you'll need to implement in a parser. See
83 the existing parsers for a guide.
84 It's supplied the following parameters:
86 • $expr - the expression to be parsed
88 • $options - the options hash supplied to transform2.
90 Return an array ref of array refs containing opcodes and operands.
92 @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 $self->error($message)
99 Set the return value of Imager::Expr::error()
100 @ops = $self->stack_to_reg(@stack_ops)
102 Converts marginally parsed RPN to register code.
103 assemble()
105 Called to convert op codes into byte code.
106 numre()
108 Returns a regular expression that matches floating point numbers.
109 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 register_type()
116 Called by a new expression parser implementation to register
117 itself, call as:
118 YourClassName->register_type('type code');
120 where type code is the parameter that will accept the expression.
122 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
130 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
131perl v5.36.0 2022-07-22 Imager::Expr(3)