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