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