1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
=head1 NAME
CPerlBase - a base class encapsulating a Perl interpreter
=head1 SYNOPSIS
// in your App.mmp
USERINCLUDE \symbian\perl\x.y.z\include
LIBRARY perlXYZ.lib
// in your App
#include "PerlBase.h" // includes also EXTERN.h and perl.h
CPerlBase* perl = CPerlBase::NewInterpreterLC();
...
delete perl;
=head1 DESCRIPTION
CPerlBase is a simple Symbian C++ class that wraps a Perl
interpreter; its creation, use, and destroying. To understand
what this is doing, and how to use the interpreter, a fair knowledge
of L<perlapi>, L<perlguts>, and L<perlembed> is recommended.
One useful thing CPerlBase does compared with just using the raw
Perl C API is that it redirects the "std streams" (STDOUT et alia)
to a text console implementation which while being very basic
is marginally more usable than the Symbian basic text console.
=head2 The Basics
=over 4
=item *
CPerlBase* NewInterpreterL();
The constructor that does not keep the object in the Symbian "cleanup stack".
perl_alloc() and perl_construct() are called behind the curtains.
Accepts the same arguments as NewInterpreterLC().
=item *
CPerlBase* NewInterpreterLC();
The constructor that keeps the object in the Symbian "cleanup stack".
perl_alloc() and perl_construct() are called behind the curtains.
Can have three arguments:
=over 8
=item *
TBool aCloseStdlib = ETrue
Should a CPerlBase close the Symbian POSIX STDLIB when closing down.
Good for one-shot script execution, probably less good for longer term
embedded interpreter.
=item *
void (*aStdioInitFunc)(void*) = NULL
If set, called with aStdioInitCookie, and the default console is
not created. You may want to set the iReadFunc() and iWriteFunc().
=item *
void *aStdioInitCookie = NULL
Used as the argument for aStdioInitFunc().
=back
=item *
void Destroy();
The destructor of the interpreter. The class destructor calls
first this and then the Symbian CloseSTDLIB().
perl_destruct(), perl_free(), and PERL_SYS_TERM() are called
behind the curtains.
=back
=head2 Utility functions
=over 4
=item *
int Parse(int argc = 0, char *argv[] = 0, char *envp[] = 0);
Prepare an interpreter for executing by parsing input as if a C main()
had been called. For example to parse a script, use argc of 2 and argv
of { "perl", script_name }.
All arguments are optional: in case either argc or argv are zero,
argc of 3 and argv of { "perl", "-e", "0" } is assumed.
PERL_SYS_INIT() and perl_parse() are called behind the curtains.
Note that a call to Parse() is required before Run().
Returns zero if parsing was successful, non-zero if not (and the stderr
will get the error).
=item *
int Run()
Start executing an interpreter. A Parse() must have been called before
a Run(): use 3 and { "", "-e", 0 } if you do not have an argv.
Note that a call to Parse() is required before Run().
perl_run() is called behind the curtains.
Returns zero if execution was successful, non-zero if not (and the stderr
will get the error).
=item *
int ParseAndRun(int argc, char *argv[], char *envp[]);
Combined Parse() and Run(). The Run() is not run if the Parse() fails.
Returns zero if parsing and execution were successful, non-zero if not.
=item *
TInt RunScriptL(TDesC& aFileName, int argc, char **argv, char *envp[])
Like ParseAndRun() but works for Symbian filenames (UTF-16LE).
The UTF-8 version of aFileName is always argv[argc-1], and argv[0]
is always "perl".
=head2 Macros
=over 4
=item *
diTHX
Set up my_perl from the current object (like dTHX).
=item *
diVAR
Set up my_vars from the current object (like dVAR).
=back
=head2 Extending CPerlBase (subclassing, deriving from)
Note that it probably isn't worth the trouble to try to wrap the
whole, rather large, Perl C API into a C++ API. Just use the C API.
The protected members of the class are:
=over 4
=item *
PerlInterpreter* iPerl
The Perl interpreter.
=item *
struct perl_vars* iVars
The global variables of the interpreter.
=item *
TPerlState iState
The state of the Perl interpreter. TPerlState is one of EPerlNone,
EPerlAllocated, EPerlConstructed, EPerlParsed, EPerlRunning,
EPerlTerminated, EPerlPaused (these two are currently unused
but in the future they might be used to indicate that the interpreter
was stopped either non-resumably or resumably for some reason),
EPerlSuccess (perl_run() succeeded), EPerlFailure (perl_run() failed),
EPerlDestroying.
=back
=head1 COPYRIGHT
Copyright (c) 2004-2005 Nokia. All rights reserved.
=head1 LICENSE
The CPerlBase class is licensed under the same terms as Perl itself.
=cut
|
