Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

Struct(3)                            User Contributed Perl Documentation                           Struct(3)



NAME
       Inline::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'

DESCRIPTION
       Inline::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::Struct
       Inline::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 Options
       Inline::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)