PERL_UNUSED_CONTEXT -> remove interp context where possible
[perl.git] / symbian / PerlBase.pod
1 =head1 NAME
2
3 CPerlBase - a C++ base class encapsulating a Perl interpreter in Symbian
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 interpreter.  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 =back
141
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