extutils::xspp::node::function(3pm) [debian man page]
ExtUtils::XSpp::Node::Function(3pm) User Contributed Perl Documentation ExtUtils::XSpp::Node::Function(3pm)NAME
ExtUtils::XSpp::Node::Function - Node representing a function
DESCRIPTION
An ExtUtils::XSpp::Node subclass representing a single function declaration such as
int foo();
More importantly, ExtUtils::XSpp::Node::Method inherits from this class, so all in here equally applies to method nodes.
METHODS
new
Creates a new "ExtUtils::XSpp::Node::Function".
Named parameters: "cpp_name" indicating the C++ name of the function, "perl_name" indicating the Perl name of the function (defaults to the
same as "cpp_name"), "arguments" can be a reference to an array of "ExtUtils::XSpp::Node::Argument" objects and finally "ret_type"
indicates the (C++) return type of the function.
Additionally, there are several optional decorators for a function declaration (see ExtUtils::XSpp for a list). These can be passed to the
constructor as "code", "cleanup", "postcall", and "catch". "catch" is special in that it must be a reference to an array of class names.
resolve_typemaps
Fetches the ExtUtils::XSpp::Typemap object for the return type and the arguments from the typemap registry and stores a reference to those
objects.
resolve_exceptions
Fetches the ExtUtils::XSpp::Exception object for the %catch directives associated with this function.
add_exception_handlers
Adds a list of exception names to the list of exception handlers. This is mainly called by a class' "add_methods" method. If the function
is hard-wired to have no exception handlers, any extra handlers from the class are ignored.
print_declaration
Returns a string with a C++ method declaration for the node.
perl_function_name
Returns the name of the Perl function to generate.
is_method
Returns whether the object at hand is a method. Hard-wired to be false for "ExtUtils::XSpp::Node::Function" object, but overridden in the
ExtUtils::XSpp::Node::Method sub-class.
has_argument_with_length
Returns true if the function has any argument that uses the XS length feature.
ACCESSORS
cpp_name
Returns the C++ name of the function.
perl_name
Returns the Perl name of the function (defaults to same as C++).
set_perl_name
Sets the Perl name of the function.
arguments
Returns the internal array reference of ExtUtils::XSpp::Node::Argument objects that represent the function arguments.
ret_type
Returns the C++ return type.
code
Returns the %code decorator if any.
set_code
Sets the implementation for the method call (equivalent to using %code); takes the code as an array reference containing the lines.
cleanup
Returns the %cleanup decorator if any.
postcall
Returns the %postcall decorator if any.
catch
Returns the set of exception types that were associated with the function via %catch. (array reference)
set_static
Sets the "static"-ness attribute of the function. Can be either undef (i.e. not static), "package_static", or "class_static".
package_static
Returns whether the function is package static. A package static function can be invoked as:
My::Package::Function( ... );
class_static
Returns whether the function is class static. A class static function can be invoked as:
My::Package->Function( ... );
perl v5.14.2 2011-12-20 ExtUtils::XSpp::Node::Function(3pm)
Check Out this Related Man Page
ExtUtils::XSpp(3pm) User Contributed Perl Documentation ExtUtils::XSpp(3pm)NAME
ExtUtils::XSpp - XS for C++
SYNOPSIS
xspp [--typemap=typemap.xsp [--typemap=typemap2.xsp]]
[--xsubpp[=/path/to/xsubpp] [--xsubpp-args="xsubpp args"]
Foo.xsp
or
perl -MExtUtils::XSpp::Cmd -e xspp -- <xspp options and arguments>
In Foo.xs
INCLUDE_COMMAND: $^X -MExtUtils::XSpp::Cmd -e xspp -- <xspp options/arguments>
Using "ExtUtils::XSpp::Cmd" is equivalent to using the "xspp" command line script, except that there is no guarantee for "xspp" to be
installed in the system PATH.
OVERVIEW
XS++ is just a thin layer over plain XS, hence to use it you are supposed to know, at the very least, C++ and XS.
This means that you will need typemaps for both the normal XS pre-processor xsubpp and the XS++ pre-processor xspp.
COMMAND LINE
"--typemap=/path/to/typemap.xsp"
Can be specified multiple times to process additional typemap files before the main XS++ input files. Typemap files are processed the same
way as regular XS++ files, except that output code is discarded.
"--xsubpp[=/path/to/xsubpp]"
If specified, XS++ will run xsubpp after processing the XS++ input file. If the path to xsubpp is not specified, xspp expects to find it
in the system PATH.
"--xsubpp-args="extra xsubpp args""
Can be used to pass additional command line arguments to xsubpp.
TYPEMAPS
There is nothing special about typemap files (i.e. you can put typemaps directly in your .xsp file), but it is handy to have common
typemaps in a separate file, to avoid duplication.
%typemap{<C++ type>}{simple};
Just let XS++ know that this is a valid type, the type will be passed unchanged to XS code except that any "const" qualifiers will be
stripped.
%typemap{<C++ reference type>}{reference};
Handle C++ references: the XS variable will be declared as a pointer, and it will be explicitly dereferenced in the function call. If it is
used in the return value, the function will create copy of the returned value using a copy constructor.
As a shortcut for the common case of declaring both of the above for a given type, you may use
%typemap{<C++ type>};
Which has the same effect as:
%typemap{<C++ type>}{simple};
%typemap{<C++ type>&}{reference};
For more control over the type mapping, you can use the "parsed" variant as follows.
%typemap{<C++ type 1>}{parsed}{%<C++ type 2>%};
When "C++ type 1" is used, replace it with "C++ type 2" in the generated XS code.
%typemap{<C++ type>}{parsed}{
%cpp_type{%<C++ type 2>%};
%call_function_code{% $CVar = new Foo( $Call ) %};
%cleanup_code{% ... %};
%precall_code{% ... %};
# use only one of the following
%output_code{% $PerlVar = newSViv( $CVar ) %};
%output_list{% PUTBACK; XPUSHi( $CVar ); SPAGAIN %};
};
Is a more flexible form for the "parsed" typemap. All the parameters are optional.
cpp_type
Specifies the C++ type used for the variable declaration in the generated XS code.
If not specified defaults to the type specified in the typemap.
call_function_code
Used when the typemap applies to the return value of the function.
Specifies the code to use in the function call. The special variables $Call and $CVar are replaced with the actual call code and the
name of the C++ return variable.
output_code
Used when the typemap applies to the return value of the function. See also %output_list.
Specifies the code emitted right after the function call to convert the C++ return value into a Perl return value. The special
variable $CVar is replaced with the C++ return variable name.
cleanup_code
Used when the typemap applies to the return value of the function.
Specifies some code emitted after output value processing. The special variables $PerlVar and $CVar are replaced with the names of the
C++ variables containing the Perl scalar and the corresponding C++ value.
precall_code
Used when the typemap applies to a parameter.
Specifies some code emitted after argument processing and before calling the C++ method. The special variables $PerlVar and $CVar are
replaced with the names of the C++ variables containing the Perl scalar and the corresponding C++ value.
output_list
Used when the typemap applies to the return value of the function, as an alternative to %output_code.
Specifies some code that manipulates the Perl stack directly in order to return a list. The special variable $CVar is replaced with
the C++ name of the output variable.
The code must use PUTBACK/SPAGAIN if appropriate.
DESCRIPTION
Anything that does not look like a XS++ directive or a class declaration is passed verbatim to XS. If you want XS++ to ignore code that
looks like a XS++ directive or class declaration, simply surround it with a raw block delimiter like this:
%{
XS++ won't interpret this
%}
%code
See under Classes. Note that custom %code blocks are the only exception to the exception handling. By specifying a custom %code block, you
forgo the automatic exception handlers.
%file
%file{file/path.h};
...
%file{file/path2};
...
%file{-}
By default XS++ output goes to standard output; to change this, use the %file directive; use "-" for standard output.
%module
%module{Module::Name};
Will be used to generate the "MODULE=Module::Name" XS directives. It indirectly sets the name of the shared library that is generated as
well as the name of the module via which XSLoader will be able to find/load it.
%name
%name{Perl::Class} class MyClass { ... };
%name{Perl::Func} int foo();
Specifies the Perl name under which the C++ class/function will be accessible. By default, constructor names are mapped to "new" in Perl.
%typemap
See TYPEMAPS above.
%length
When you need to pass a string from Perl to an XSUB that takes the C string and its length as arguments, you may have XS++ pass the length
of the string automatically. For example, if you declare a method as follows,
void PrintLine( char* line, unsigned int %length{line} );
you can call the method from Perl like this:
$object->PrintLine( $string );
This feature is also present in plain XS. See also: perlxs.
If you use "%length(line)" in conjunction with any kind of special code block such as %code, %postcall, etc., then you can refer to the
length of the string (here: "line") efficiently as "length(line)" in the code.
Classes
%name{My::Class} class MyClass : public %name{My::Base} MyBase
{
// can be called in Perl as My::Class->new( ... );
MyClass( int arg );
// My::Class->newMyClass( ... );
%name{newMyClass} MyClass( const char* str, int arg );
// standard DESTROY method
~MyClass();
int GetInt();
void SetValue( int arg = -1 );
%name{SetString} void SetValue( const char* string = NULL );
// Supply a C<CODE:> or C<CLEANUP:> block for the XS
int MyMethod( int a, int b )
%code{% RETVAL = a + b; %}
%cleanup{% /* do something */ %};
};
Comments
XS++ recognizes both C-style comments "/* ... */" and C++-style comments "// ...". Comments are removed from the XS output.
Exceptions
C++ Exceptions are always caught and transformed to Perl "croak()" calls. If the exception that was caught inherited from "std::exception",
then the "what()" message is included in the Perl-level error message. All other exceptions will result in the "croak()" message "Caught
unhandled C++ exception of unknown type".
Note that if you supply a custom %code block for a function or method, the automatic exception handling is turned off.
EXAMPLES
The distribution contains an examples directory. The examples/XSpp-Example directory therein demonstrates a particularly simple way of
getting started with XS++.
AUTHOR
Mattia Barbon <mbarbon@cpan.org>
LICENSE
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
perl v5.14.2 2011-12-20 ExtUtils::XSpp(3pm)