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