S_del_body is sufficiently small that inlining it is a space win.
[p5sagit/p5-mst-13.2.git] / symbian / PerlBase.pod
1 =head1 NAME
2
3 CPerlBase - a base class encapsulating a Perl interpreter
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
114 Start executing an interpeter.  A Parse() must have been called before
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
140 =head2 Macros
141
142 =over 4
143
144 =item *
145
146 diTHX
147
148 Set up my_perl from the current object (like dTHX).
149
150 =item *
151
152 diVAR
153
154 Set up my_vars from the current object (like dVAR).
155
156 =back
157
158 =head2 Extending CPerlBase (subclassing, deriving from)
159
160 Note that it probably isn't worth the trouble to try to wrap the
161 whole, rather large, Perl C API into a C++ API.  Just use the C API.
162
163 The protected members of the class are:
164
165 =over 4
166
167 =item *
168
169 PerlInterpreter* iPerl
170
171 The Perl interpreter.
172
173 =item *
174
175 struct perl_vars* iVars
176
177 The global variables of the interpreter.
178
179 =item *
180
181 TPerlState iState
182
183 The state of the Perl interpreter. TPerlState is one of EPerlNone,
184 EPerlAllocated, EPerlConstructed, EPerlParsed, EPerlRunning,
185 EPerlTerminated, EPerlPaused (these two are currently unused
186 but in the future they might be used to indicate that the interpreter
187 was stopped either non-resumably or resumably for some reason),
188 EPerlSuccess (perl_run() succeeded), EPerlFailure (perl_run() failed),
189 EPerlDestroying.
190
191 =back
192
193 =head1 COPYRIGHT
194
195 Copyright (c) 2004-2005 Nokia.  All rights reserved.
196
197 =head1 LICENSE
198
199 The CPerlBase class is licensed under the same terms as Perl itself.
200
201 =cut
202