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
49 expression object cannot be created.
50 Methods
52 Imager::Expr provides only a few simple methods meant for external use:
54 Imager::Expr->type_registered($keyword)
56 Returns true if the given expression type is available. The param‐
57 eter is the key supplied to the new() method.
58 if (Imager::Expr->type_registered('expr')) {
60 # use infix expressions
61 }
62 $expr->code()
64 Returns the compiled code.
65 $expr->nregs()
67 Returns a reference to the array of numeric registers.
68 $expr->cregs()
70 Returns a reference to the array of colour registers.
71 $expr->dumpops()
73 Returns a string with the generated VM "machine code".
74 $expr->dumpcode()
76 Returns a string with the unassembled VM "machine code".
77 Creating a new parser
79 I'll write this one day.
81 Methods used by parsers:
83 compile
85 This is the main method you'll need to implement in a parser. See
86 the existing parsers for a guide.
87 It's supplied the following parameters:
89 * $expr - the expression to be parsed
91 * $options - the options hash supplied to transform2.
93 Return an array ref of array refs containing opcodes and operands.
95 @vars = $self->_variables()
97 A list (not a reference) of the input variables. This should be
98 used to allocate as many registers as there are variable as input
99 registers.
100 $self->error($message)
102 Set the return value of Imager::Expr::error()
103 @ops = $self->stack_to_reg(@stack_ops)
105 Converts marginally parsed RPN to register code.
106 assemble
108 Called to convert op codes into byte code.
109 numre
111 Returns a regular expression that matches floating point numbers.
112 optimize
114 Optimizes the assembly code, including attempting common subexpres‐
115 sion elimination and strength reducing division by a constant into
116 multiplication by a constant.
117 register_type
119 Called by a new expression parser implementation to register
120 itself, call as:
121 YourClassName->register_type('type code');
123 where type code is the parameter that will accept the expression.
125 Future compatibility
127 Try to avoid doing your own optimization beyond literal folding - if we
129 add some sort of jump, the existing optimizer will need to be rewrit‐
130 ten, and any optimization you perform may well be broken too (well,
131 your code generation will probably be broken anyway <sigh>).
132perl v5.8.8 2008-03-28 Imager::Expr(3)