PerlSharp : Perl Namespace
Interpreter

A Perl interpreter context. This is the main class for executing Perl code in the managed world.

public class Interpreter

Remarks
An example will come at some point.
Members

See Also: Inherited members from object.

Constructors
Interpreter()
Creates a new instance of a Perl interpreter with taint checking and warnings.
Interpreter(bool, bool)
Creates a new instance of a Perl interpreter.
Interpreter(Interpreter)
Creates a new Perl interpreter whose state is cloned from the given interpreter.
Fields
WarnHandler
 WarnHandler. The handler for when warnings are emitted by Perl code.
Methods
AddExtension(object, System.Reflection.MethodInfo)
Defines a named Perl sub that interfaces into the managed world.
AddExtension(string, object, System.Reflection.MethodInfo)
Defines a Perl sub in the named package that interfaces into the managed world.
AddExtension(Delegate)
Defines a Perl sub that is a callback to a delegate.
AddExtension(string, Delegate)
Defines a Perl sub that is a callback to a delegate.
AddExtensionObject(object)
Defines a Perl package that interfaces into the managed world.
AddExtensionObject(string, object)
Defines a Perl package that interfaces into the managed world.
AddSimpleExtension(object, System.Reflection.MethodInfo)
Defines a Perl sub in the main package that interfaces into the managed world.
AddSimpleExtension(object, string)
Defines a Perl sub in the main package that interfaces into the managed world.
Call(string, object[] ) : Value
Calls a subroutine.
Call(Value, object[] ) : Value
Calls a subroutine.
CallParams(string, params object[] ) : Value
Calls a sub, with parameters passed as a param array.
Convert(object) : Value
Converts a managed object into one of the Value types.
static Convert(Value) : object
Converts a Value object to the usual managed equivalent.
static Convert(Value, Type) : object
Converts a Value object to another type.
Eval(string) : Value
Evaluates the Perl expression.
EvalUnwrap(string) : Value
Evaluates the expression and unwraps the return value if it is a reference.
GetArray(string) : Array
Returns the global array with the given name.
GetArray(string, bool) : Array
Returns the global array with the given name.
GetHash(string) : Hash
Returns the global hash with the given name.
GetHash(string, bool) : Hash
Returns the global hash with the given name.
GetReference(string) : Value
Returns the global reference (ref, blessed object, code ref) with the given name.
GetScalar(string) : Scalar
Returns the global scalar with the given name.
GetScalar(string, bool) : Scalar
Returns the global scalar with the given name.
Require(string)
Loads (require's) in the specified file.
Use(string)
Loads a package to be used.
Member Details
Interpreter Constructor
public Interpreter ()

Creates a new instance of a Perl interpreter with taint checking and warnings.

Interpreter Constructor
public Interpreter (bool taintcheck, bool warnings)

Creates a new instance of a Perl interpreter.

Parameters
taintcheck
Whether taint checking should be performed.
warnings
Whether warnings should be enabled.
Interpreter Constructor
public Interpreter (Interpreter clonedFrom)

Creates a new Perl interpreter whose state is cloned from the given interpreter.

Parameters
clonedFrom
The interpreter whose state is to be cloned.
WarnHandler
public WarnHandler WarnHandler

The handler for when warnings are emitted by Perl code.

Remarks

WarnHandler is set to a default handler which prints warnings to Console.Error, much like Perl itself would do. Set this field to trap warnings.

A warn signal handler (in Perl) is installed by PerlSharp when an interpreter is created. If the signal handler is removed, WarnHandler will never be called.

Require
public void Require (string file)

Loads (require's) in the specified file.

Parameters
file
The name of the Perl file to load. Either an absolute path or relative to something in @INC.
Exceptions
Type Condition
Perl.PerlEvalException If an error occured during the require.
Remarks
This is equivalent to Perl's "require" statement. Perl will search @INC, just like if Eval("require $file") was called.
Use
public void Use (string package)

Loads a package to be used.

Parameters
package
The name of the package to use (i.e. XML::LibXML)
Remarks
This is equivalent to Perl's use statement.
Eval
public Value Eval (string expression)

Evaluates the Perl expression.

Parameters
expression
The string expression to evaluate.
Returns
The value of the expression, as a Perl.Value.
Exceptions
Type Condition
ArgumentException If expression is an empty string.
Perl.PerlEvalException If an error occured during the eval.
Remarks
Expressions are evaluated in a "scalar context." Expressions that return arrays or hashes will come back into the managed world as a single scalar, possibly the number of elements returned. Use references to array or hashes to pass them back to managed code.
Call
public Value Call (string subroutine, object[] args)

Calls a subroutine.

Parameters
subroutine
The name of the sub to call.
args
The arguments to pass to the sub. Managed objects will be converted to Perl.Value's.
Returns
The return value of calling the sub.
Exceptions
Type Condition
Perl.PerlEvalException If an error occured during the call.
Remarks
See Eval.
CallParams
public Value CallParams (string subroutine, params object[] args)

Calls a sub, with parameters passed as a param array.

Parameters
subroutine
The name of the sub to call.
args
The arguments to pass to the sub. Managed objects will be converted to Perl.Value's.
Returns
The return value of calling the sub.
Exceptions
Type Condition
Perl.PerlEvalException If an error occured during the call.
Remarks
See Call(string,object[]).
Call
public Value Call (Value subroutine, object[] args)

Calls a subroutine.

Parameters
subroutine
The subroutine to call. This can be a string-valued scalar with the name of the subroutine, or a Code object that references a sub.
args
The arguments to pass to the sub. Managed objects will be converted to Perl.Value's.
Returns
The return value of the call to the sub.
Exceptions
Type Condition
Perl.PerlEvalException If an error occured during the call.
Remarks
See Call(string,object[]).
EvalUnwrap
public Value EvalUnwrap (string expression)

Evaluates the expression and unwraps the return value if it is a reference.

Parameters
expression
The expression to evaluate.
Returns
The result of evaluating the expression. If a reference results, it is dereferenced first.
Exceptions
Type Condition
Perl.PerlEvalException If an error occured during the eval.
Remarks
This is a helper function that merely wraps Eval(string).
GetArray
public Array GetArray (string name)

Returns the global array with the given name.

Parameters
name
The name of the variable. Omit the "@".
Returns
The variable "@name".
Remarks
The actual variable is returned. Modifications to the return of this function will alter the variable itself. The variable is created if it doesn't exist.
GetArray
public Array GetArray (string name, bool create)

Returns the global array with the given name.

Parameters
name
The name of the variable. Omit the "@".
create
Whether to create the variable if it is not already defined.
Returns
The variable "@name", or null if it is not defined and create is false.
Remarks
The actual variable is returned. Modifications to the return of this function will alter the variable itself.
GetHash
public Hash GetHash (string name)

Returns the global hash with the given name.

Parameters
name
The name of the variable. Omit the "%".
Returns
The variable "%name".
Remarks
The actual variable is returned. Modifications to the return of this function will alter the variable itself. The variable is created if it doesn't exist.
GetHash
public Hash GetHash (string name, bool create)

Returns the global hash with the given name.

Parameters
name
The name of the variable. Omit the "%".
create
Whether to create the variable if it is not already defined.
Returns
The variable "%name", or null if it is not defined and create is false.
Remarks
The actual variable is returned. Modifications to the return of this function will alter the variable itself.
GetScalar
public Scalar GetScalar (string name)

Returns the global scalar with the given name.

Parameters
name
The name of the variable. Omit the "$".
Returns
The variable "$name".
Remarks
The actual variable is returned. Modifications to the return of this function will alter the variable itself. The variable is created if it doesn't exist.
GetScalar
public Scalar GetScalar (string name, bool create)

Returns the global scalar with the given name.

Parameters
name
The name of the variable.
create
Whether to create the variable if it is not already defined.
Returns
The variable "$name", or null if it is not defined and create is false.
Remarks
The actual variable is returned. Modifications to the return of this function will alter the variable itself.
GetReference
public Value GetReference (string name)

Returns the global reference (ref, blessed object, code ref) with the given name.

Parameters
name
The name of the variable.
Returns
The variable "$name", or null if it is not defined. If $name is a scalar, a Scalar is returned. Otherwise, one of the reference types (Reference, Code, Blessed) may be returned.
Remarks
The actual variable is returned. Modifications to the return of this function will alter the variable itself.
AddExtensionObject
public void AddExtensionObject (object obj)

Defines a Perl package that interfaces into the managed world.

Parameters
obj
The extension object.
Remarks
The public methods of the extension object are added into the Perl package with the same name as the object's type's full name, but with periods replaced by double colons. (e.g. Perl::Interpreter) Calls to subs in that package invoke members of obj.
AddExtensionObject
public void AddExtensionObject (string package, object obj)

Defines a Perl package that interfaces into the managed world.

Parameters
package
The name of the Perl package to add the methods into.
obj
The extension object.
Remarks
The public methods of the extension object are added into the specified Perl package. Calls to subs in that package invoke the methods of obj.
AddSimpleExtension
public void AddSimpleExtension (object target, System.Reflection.MethodInfo method)

Defines a Perl sub in the main package that interfaces into the managed world.

Parameters
target
The instance of the object to invoke the method on, or null if method is static.
method
The instance or static method to invoke.
Remarks
The method is defind in Perl with the same name as the method. Calling this with System.Console.WriteLine as method will result in the creation of a Perl sub named "WriteLine" that when called will invoke System.Console.WriteLine.
AddSimpleExtension
public void AddSimpleExtension (object target, string method)

Defines a Perl sub in the main package that interfaces into the managed world.

Parameters
target
The instance of the object to invoke the method on.
method
The name of the instance or static method of target to invoke.
Remarks
The method is defind in Perl with the same name as the method.
AddExtension
public void AddExtension (object target, System.Reflection.MethodInfo method)

Defines a named Perl sub that interfaces into the managed world.

Parameters
target
The instance of the object to invoke the method on, or null if method is static.
method
The instance or static method to invoke.
Remarks
The method is defind in Perl with the same name as the method in the package with the same name as the declaring type of the method, but with periods replaced by double colons. Calling this with System.Console.WriteLine as method will result in the creation of a Perl sub named "System::Console::WriteLine" that when called will invoke System.Console.WriteLine.
AddExtension
public void AddExtension (string name, object target, System.Reflection.MethodInfo method)

Defines a Perl sub in the named package that interfaces into the managed world.

Parameters
name
The Perl name for the subroutine. A package can be specified.
target
The instance of the object to invoke the method on, or null if method is static.
method
The instance or static method to invoke.
AddExtension
public void AddExtension (Delegate deleg)

Defines a Perl sub that is a callback to a delegate.

Parameters
deleg
The delegate to call when the Perl sub is invoked.
Remarks
The delegate is created in the Perl package named by the declaring type of the method the delegate refers to. See AddExtension(object,System.Reflection.MethodInfo).
AddExtension
public void AddExtension (string name, Delegate deleg)

Defines a Perl sub that is a callback to a delegate.

Parameters
name
The Perl name for the sub. A package may be specified.
deleg
The delegate to call when the Perl sub is invoked.
Remarks
See AddExtension(string,object,System.Reflection.MethodInfo).
Convert
public Value Convert (object value)

Converts a managed object into one of the Value types.

Parameters
value
The object to convert.
Returns
The Value corresponding to the object.
Remarks
The following conversions are performed: Values are returned unchanged. IDictionary objects are returned as Hashes, with its keys and values similarly converted. ICollection objects are returned as Arrays, with its elements similarly converted. Everything else is converted to a Scalar. Numeric and string types are converted directly to Scalars. For other types, the return value of ToString called on them is used.
Convert
public static object Convert (Value value)

Converts a Value object to the usual managed equivalent.

Parameters
value
The Perl object to convert.
Returns
The managed object.
Remarks
The following conversions are made: Arrays are converted to ArrayLists. Hashes are converted to Hashtables. The elements of Arrays and Hashes are not converted. Scalars are converted to strings. References are dereferenced before conversion. Anything else is converted to null.
Convert
public static object Convert (Value value, Type select)

Converts a Value object to another type.

Parameters
value
The Perl object to convert.
select
The type of object to convert to.
Returns
The converted object.
Remarks
The following conversions are made: If value is assignable to select and select is not Object, value is returned unchanged. If select is ArrayList or one of its ancestors and value is an Array, an ArrayList is returned. If select is Hashtable or one of its ancestors and value is a Hash, then a Hashtable is returned. The elements of Arrays and Hashes are not converted. Scalars are converted to ints, longs, floats, doubles, and strings if one of those types is specified as select. Otherwise, Scalars are converted to strings. References are dereferenced before conversion. Anything else is converted to null.