Struct(3) User Contributed Perl Documentation Struct(3)NAMEInline::Struct-- Manipulate C structures directly from Perl.
SYNOPSIS
use Inline C => Config => Structs => ['Foo'];
my $obj = Inline::Struct::Foo->new;
$obj->num(10);
$obj->str("Hello");
myfunc($obj);
__END__
__C__
struct Foo {
int num;
char *str;
};
void myfunc(Foo *f) {
printf("myfunc: num=%i, str='%s'\n", f->num, f->str);
}
This complete program prints:
myfunc: num=10, str='Hello'
DESCRIPTIONInline::Struct is not a new language. It's a language extension
designed to be used by Inline::C. It parses struct definitions and
creates typemaps and XS code which bind each struct into a Perl class.
This code is passed to Inline::C, which compiles it in the normal way.
NOTE: Inline::Struct parses only C-style structs. It doesn't know about
any C++ extensions to structs like scopes, constructors or methods. If
you want such functionality you should use Inline::CPP to parse your
structs.
Using Inline::StructInline::Struct has a Parse::RecDescent grammar to parse C structs. If a
struct is recognized, it can be bound to Perl. If the struct's
definition is not recognized (usually because it has a member with no
typemap), it will not be bound to Perl, but will be available from
other functions in C or C++.
The following example shows how a simple struct might look to a Perl
programmer.
Example 1:
use Inline C => <<'END', ENABLE => 'STRUCTS';
struct Fraction {
long numer;
long denom;
};
END
my $o = Inline::Struct::Fraction->new(4, 3);
print $o->numer, $o->denom, "\n";
$o->numer(4)->denom(7);
After the code above has been compiled, Perl's namespace looks a lot
like the following:
package Inline::Struct::Fraction;
sub new { }
sub DESTROY { }
sub _KEYS { }
sub _VALUES { }
sub _HASH { }
sub numer { }
sub denom { }
Note that these are actually XS subs written in C, not Perl subs. But
that's what it looks like.
The Struct Interface
The following sections define the interface of each subroutine. Note:
this interface is likely to change in future versions of
Inline::Struct. Please don't rely on Inline::Struct in production code
quite yet.
When a struct is bound by Inline::Struct, a new namespace is created
underneath Inline::Struct. So if you have a struct named 'Foo', the
package of the Perl class will be 'Inline::Struct::Foo'.
new
If no arguments are provided, all fields are zeroed out. If you provide
values, they should be appropriate for the field type, and in the same
order as they are defined in the struct.
DESTROY
The destructor. Should never be called by the programmer -- this is
called automatically when the Perl variable holding the struct is
destroyed. Frees the memory associated with the struct. If the struct
holds pointers to malloc'd memory, they will not be freed. If you run
into such a situation, consider using C++ and Inline::CPP instead.
_KEYS
A read-only method, this returns a reference to an array containing the
names of the fields in the struct. The fields are in the order they
appear in the C source code.
_VALUES
A read-only method, this returns a reference to an array containing the
values of the fields in the struct. The values are returned in the same
order as the fields.
_HASH
A read-only method, this returns a reference to a hash, mapping field
names to field values.
Accessors
For each field in the struct, an accessor sub will be created which
lets you get or set the value in the struct. If no arguments are
provided, the sub returns the value of that field. If any arguments are
provided, the field is set to the first argument, and the modified
structure is returned. This makes setting multiple fields easy:
$o->field1(something)->field2(somethingelse);
C and C++ Configuration OptionsInline::Struct has no configuration options of its own, but it does
provide a new configuration option for C or C++.
STRUCTS
Specifies that structs are to be bound to Perl. There are several
meanings to this option, so I'll explain with an example:
use Inline C => Config => STRUCTS => 'Foo';
Adds 'Foo' to the list of structs to bind to Perl.
use Inline C => Config => STRUCTS => ['Foo', 'Bar'];
Adds 'Foo' and 'Bar' to the list of structs to bind to Perl.
use Inline C => Config => STRUCTS => undef;
Clears the list of structs to bind to Perl.
use Inline C => Config => ENABLE => 'STRUCTS';
or
use Inline C => Config => STRUCTS => 1;
Enable binding structs to Perl, without specifying any structs to
search for. As shown, this would bind all structs to Perl.
use Inline C => Config => DISABLE => 'STRUCTS';
or
use Inline C => Config => STRUCTS => 0;
Disable binding structs to Perl.
SEE ALSO
For more information about using C from Perl, see Inline::C. For more
information about using C++ from Perl, see Inline::CPP.
AUTHOR
Neil Watkiss (NEILW@cpan.org)
COPYRIGHT
Copyright (C) 2001, Neil Watkiss.
This module is free software. It may be used, redistributed and/or
modified under the same terms as Perl itself.
(see http://www.perl.com/perl/misc/Artistic.html)
perl v5.16.2 2001-05-13 Struct(3)
