You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucy.apache.org by ma...@apache.org on 2012/02/25 00:27:00 UTC
[lucy-commits] svn commit: r1293478 - in /incubator/lucy/trunk/clownfish:
perl/lib/Clownfish/CFC/Binding/ perl/lib/Clownfish/CFC/Binding/Perl/ src/
Author: marvin
Date: Fri Feb 24 23:26:59 2012
New Revision: 1293478
URL: http://svn.apache.org/viewvc?rev=1293478&view=rev
Log:
Move docs for CFCPerl* to C header files.
Modified:
incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl.pm
incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Class.pm
incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Constructor.pm
incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Method.pm
incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Pod.pm
incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Subroutine.pm
incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/TypeMap.pm
incubator/lucy/trunk/clownfish/src/CFCPerl.h
incubator/lucy/trunk/clownfish/src/CFCPerlClass.h
incubator/lucy/trunk/clownfish/src/CFCPerlConstructor.h
incubator/lucy/trunk/clownfish/src/CFCPerlMethod.h
incubator/lucy/trunk/clownfish/src/CFCPerlSub.h
incubator/lucy/trunk/clownfish/src/CFCPerlTypeMap.h
Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl.pm?rev=1293478&r1=1293477&r2=1293478&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl.pm Fri Feb 24 23:26:59 2012
@@ -44,88 +44,3 @@ sub new {
1;
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::CFC::Binding::Perl - Perl bindings for a Clownfish::CFC::Hierarchy.
-
-=head1 DESCRIPTION
-
-Clownfish::CFC::Binding::Perl presents an interface for auto-generating XS and
-Perl code to bind C code for a Clownfish class hierarchy to Perl.
-
-In theory this module could be much more flexible and its API could be more
-elegant. There are many ways which you could walk the parsed parcels,
-classes, methods, etc. in a Clownfish::CFC::Hierarchy and generate binding code.
-However, our needs are very limited, so we are content with a "one size fits
-one" solution.
-
-In particular, this module assumes that the XS bindings for all classes in the
-hierarchy should be assembled into a single shared object which belongs to the
-primary, "boot" class. There's no reason why it could not write one .xs file
-per class, or one per parcel, instead.
-
-The files written by this class are derived from the name of the boot class.
-If it is "Crustacean", the following files will be generated.
-
- # Generated by write_bindings()
- $lib_dir/Crustacean.xs
- $lib_dir/Crustacean/Autobinding.pm
-
- # Generated by write_boot()
- $hierarchy_dest_dir/crust_boot.h
- $hierarchy_dest_dir/crust_boot.c
-
-=head1 METHODS
-
-=head2 new
-
- my $perl_binding = Clownfish::CFC::Binding::Perl->new(
- boot_class => 'Crustacean', # required
- parcel => 'Crustacean', # required
- hierarchy => $hierarchy, # required
- lib_dir => 'lib', # required
- header => "/* Autogenerated file */\n", # required
- footer => $copyfoot, # required
- );
-
-=over
-
-=item * B<boot_class> - The name of the main class, which will own the shared
-object.
-
-=item * B<parcel> - The L<Clownfish::CFC::Parcel> to which the C<boot_class>
-belongs.
-
-=item * B<hierarchy> - A Clownfish::CFC::Hierarchy.
-
-=item * B<lib_dir> - location of the Perl lib directory to which files will be
-written.
-
-=item * B<header> - Text which will be prepended to generated C/XS files --
-typically, an "autogenerated file" warning.
-
-=item * B<footer> - Text to be appended to the end of generated C/XS files --
-typically copyright information.
-
-=back
-
-=head2 write_bindings
-
- $perl_binding->write_bindings;
-
-Generate the XS bindings (including "Autobind.pm) for all classes in the
-hierarchy.
-
-=head2 write_boot
-
- $perl_binding->write_boot;
-
-Write out "boot" files to the Hierarchy's C<dest_dir> which contain code for
-bootstrapping Clownfish classes.
-
-=cut
-
Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Class.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Class.pm?rev=1293478&r1=1293477&r2=1293478&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Class.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Class.pm Fri Feb 24 23:26:59 2012
@@ -18,90 +18,3 @@ use Clownfish::CFC;
1;
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::CFC::Binding::Perl::Class - Generate Perl binding code for a
-Clownfish::CFC::Class.
-
-=head1 CLASS METHODS
-
-=head1 register
-
- Clownfish::CFC::Binding::Perl::Class->register(
- parcel => 'MyProject' , # required
- class_name => 'Foo::FooJr', # required
- bind_methods => [qw( Do_Stuff _get_foo|Get_Foo )], # default: undef
- make_pod => [qw( get_foo )], # default: undef
- xs_code => undef, # default: undef
- );
-
-Create a new class binding and lodge it in the registry. May only be called
-once for each unique class name, and must be called after all classes have
-been parsed (via Clownfish::CFC::Hierarchy's build()).
-
-=over
-
-=item * B<parcel> - A L<Clownfish::CFC::Parcel> or parcel name.
-
-=item * B<class_name> - The name of the class to be registered.
-
-=item * B<xs_code> - Raw XS code to be included in the final .xs file
-generated by Clownfish::CFC::Binding::Perl. The XS directives PACKAGE and
-MODULE should be specified.
-
-=item * B<bind_methods> - An array of names for novel methods for which XS
-bindings should be auto-generated, supplied using Clownfish's C<Macro_Name>
-method-naming convention. The Perl subroutine name will be derived by
-lowercasing C<Method_Name> to C<method_name>, but this can be overridden by
-prepending an alias and a pipe: e.g. C<_get_foo|Get_Foo>.
-
-=item * B<make_pod> - A specification for generating POD. TODO: document this
-spec, or break it up into multiple methods. (For now, just see examples from
-the source code.)
-
-=back
-
-=head2 singleton
-
- my $binding = Clownfish::CFC::Binding::Perl::Class->singleton($class_name);
-
-Given a class name, return a class binding if one exists.
-
-=head2 registered
-
- my $registered = Clownfish::CFC::Binding::Perl::Class->registered;
-
-All registered bindings.
-
-=head1 OBJECT METHODS
-
-=head2 get_class_name get_pod_spec get_xs_code get_client
-
-Accessors. C<get_client> retrieves the Clownfish::CFC::Class module to be
-bound.
-
-=head2 constructor_bindings
-
- my @ctor_bindings = $class_binding->constructor_bindings;
-
-Return a list of Clownfish::CFC::Binding::Perl::Constructor objects created as
-per the C<bind_constructors> spec.
-
-=head2 method_bindings
-
- my @method_bindings = $class_binding->method_bindings;
-
-Return a list of Clownfish::CFC::Binding::Perl::Method objects created as per
-the C<bind_methods> spec.
-
-=head2 create_pod
-
- my $pod = $class_binding->create_pod;
-
-Auto-generate POD according to the make_pod spec, if such a spec was supplied.
-
-=cut
Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Constructor.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Constructor.pm?rev=1293478&r1=1293477&r2=1293478&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Constructor.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Constructor.pm Fri Feb 24 23:26:59 2012
@@ -18,45 +18,3 @@ use Clownfish::CFC;
1;
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::CFC::Binding::Perl::Constructor - Binding for an object method.
-
-=head1 DESCRIPTION
-
-This class isa Clownfish::CFC::Binding::Perl::Subroutine -- see its
-documentation for various code-generating routines.
-
-Constructors are always bound to accept labeled params, even if there is only
-a single argument.
-
-=head1 METHODS
-
-=head2 new
-
- my $constructor_binding = Clownfish::CFC::Binding::Perl::Constructor->new(
- class => $class,
- alias => "_new|init2",
- );
-
-=over
-
-=item * B<class> - A L<Clownfish::CFC::Class>.
-
-=item * B<alias> - A specifier for the name of the constructor, and
-optionally, a specifier for the implementing function. If C<alias> has a pipe
-character in it, the text to the left of the pipe will be used as the Perl
-alias, and the text to the right will be used to determine which C function
-should be bound. The default function is "init".
-
-=back
-
-=head2 xsub_def
-
-Generate the XSUB code.
-
-=cut
Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Method.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Method.pm?rev=1293478&r1=1293477&r2=1293478&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Method.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Method.pm Fri Feb 24 23:26:59 2012
@@ -18,39 +18,3 @@ use Clownfish::CFC;
1;
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::CFC::Binding::Perl::Method - Binding for an object method.
-
-=head1 DESCRIPTION
-
-This class isa Clownfish::CFC::Binding::Perl::Subroutine -- see its
-documentation for various code-generating routines.
-
-Method bindings use labeled parameters if the C function takes more than one
-argument (other than C<self>). If there is only one argument, the binding
-will be set up to accept a single positional argument.
-
-=head1 METHODS
-
-=head2 new
-
- my $binding = Clownfish::CFC::Binding::Perl::Method->new(
- method => $method, # required
- );
-
-=over
-
-=item * B<method> - A L<Clownfish::CFC::Method>.
-
-=back
-
-=head2 xsub_def
-
-Generate the XSUB code.
-
-=cut
Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Pod.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Pod.pm?rev=1293478&r1=1293477&r2=1293478&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Pod.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Pod.pm Fri Feb 24 23:26:59 2012
@@ -18,5 +18,3 @@ use Clownfish::CFC;
1;
-__END__
-
Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Subroutine.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Subroutine.pm?rev=1293478&r1=1293477&r2=1293478&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Subroutine.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/Subroutine.pm Fri Feb 24 23:26:59 2012
@@ -18,77 +18,3 @@ use Clownfish::CFC;
1;
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::CFC::Binding::Perl::Subroutine - Abstract base binding for a
-Clownfish::CFC::Function.
-
-=head1 SYNOPSIS
-
- # Abstract base class.
-
-=head1 DESCRIPTION
-
-This class is used to generate binding code for invoking Clownfish's
-functions and methods across the Perl/C barrier.
-
-=head1 METHODS
-
-=head2 new
-
- my $binding = $subclass->SUPER::new(
- param_list => $param_list, # required
- alias => 'pinch', # required
- class_name => 'Crustacean::Claw', # required
- use_labeled_params => 1, # default: false
- );
-
-Abstract constructor.
-
-=over
-
-=item * B<param_list> - A L<Clownfish::CFC::ParamList>.
-
-=item * B<alias> - The local, unqualified name for the Perl subroutine that
-will be used to invoke the function.
-
-=item * B<class_name> - The name of the Perl class that the subroutine belongs
-to.
-
-=item * B<use_labeled_params> - True if the binding should take hash-style
-labeled parameters, false if it should take positional arguments.
-
-=back
-
-=head2 xsub_def
-
-Abstract method which must return C code (not XS code) defining the Perl XSUB.
-
-=head2 get_class_name use_labeled_params
-
-Accessors.
-
-=head2 perl_name
-
-Returns the fully-qualified perl sub name.
-
-=head2 c_name
-
-Returns the fully-qualified name of the C function that implements the XSUB.
-
-=head2 c_name_list
-
-Returns a string containing the names of arguments to feed to bound C
-function, joined by commas.
-
-=head2 params_hash_def
-
-Return Perl code initializing a package-global hash where all the keys are the
-names of labeled params. The hash's name consists of the the binding's
-perl_name() plus "_PARAMS".
-
-=cut
Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/TypeMap.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/TypeMap.pm?rev=1293478&r1=1293477&r2=1293478&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/TypeMap.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC/Binding/Perl/TypeMap.pm Fri Feb 24 23:26:59 2012
@@ -18,76 +18,3 @@ use Clownfish::CFC;
1;
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::CFC::Binding::Perl::TypeMap - Convert between Clownfish and Perl via XS.
-
-=head1 DESCRIPTION
-
-TypeMap serves up C code fragments for translating between Perl data
-structures and Clownfish data structures. The functions to_perl() and
-from_perl() achieve this for individual types; write_xs_typemap() exports all
-types using the XS "typemap" format documented in C<perlxs>.
-
-=head1 FUNCTIONS
-
-=head2 from_perl
-
- my $expression = from_perl( $type, $xs_var );
-
-Return an expression which converts from a Perl scalar to a variable of type
-$type.
-
-=over
-
-=item * B<type> - A Clownfish::CFC::Type, which will be used to select the
-mapping code.
-
-=item * B<xs_var> - The C name of the Perl scalar from which we are extracting
-a value.
-
-=back
-
-=head2 to_perl
-
- my $c_code = to_perl( $type, $cf_var );
-
-Return an expression converts from a variable of type $type to a Perl scalar.
-
-=over
-
-=item * B<type> - A Clownfish::CFC::Type, which will be used to select the
-mapping code.
-
-=item * B<cf_var> - The name of the variable from which we are extracting a
-value.
-
-=back
-
-=head1 CLASS METHODS
-
-=head2 write_xs_typemap
-
- Clownfish::CFC::Binding::Perl::Typemap->write_xs_typemap(
- hierarchy => $hierarchy,
- );
-
-=over
-
-=item * B<hierarchy> - A L<Clownfish::CFC::Hierarchy>.
-
-=back
-
-Auto-generate a "typemap" file that adheres to the conventions documented in
-L<perlxs>.
-
-We generate this file on the fly rather than maintain a static copy because we
-want an entry for each Clownfish type so that we can differentiate between
-them when checking arguments. Keeping the entries up-to-date manually as
-classes come and go would be a pain.
-
-=cut
Modified: incubator/lucy/trunk/clownfish/src/CFCPerl.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCPerl.h?rev=1293478&r1=1293477&r2=1293478&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCPerl.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCPerl.h Fri Feb 24 23:26:59 2012
@@ -25,6 +25,47 @@ typedef struct CFCPerl CFCPerl;
struct CFCParcel;
struct CFCHierarchy;
+/** Clownfish::CFC::Binding::Perl - Perl bindings for a Clownfish::CFC::Hierarchy.
+ *
+ * Clownfish::CFC::Binding::Perl presents an interface for auto-generating XS and
+ * Perl code to bind C code for a Clownfish class hierarchy to Perl.
+ *
+ * In theory this module could be much more flexible and its API could be more
+ * elegant. There are many ways which you could walk the parsed parcels,
+ * classes, methods, etc. in a Clownfish::CFC::Hierarchy and generate binding code.
+ * However, our needs are very limited, so we are content with a "one size fits
+ * one" solution.
+ *
+ * In particular, this module assumes that the XS bindings for all classes in the
+ * hierarchy should be assembled into a single shared object which belongs to the
+ * primary, "boot" class. There's no reason why it could not write one .xs file
+ * per class, or one per parcel, instead.
+ *
+ * The files written by this class are derived from the name of the boot class.
+ * If it is "Crustacean", the following files will be generated.
+ *
+ * # Generated by write_bindings()
+ * $lib_dir/Crustacean.xs
+ * $lib_dir/Crustacean/Autobinding.pm
+ *
+ * # Generated by write_boot()
+ * $hierarchy_dest_dir/crust_boot.h
+ * $hierarchy_dest_dir/crust_boot.c
+ */
+
+/**
+ * @param parcel The L<Clownfish::CFC::Parcel> to which the C<boot_class>
+ * belongs.
+ * @param hierarchy A Clownfish::CFC::Hierarchy.
+ * @param lib_dir location of the Perl lib directory to which files will be
+ * written.
+ * @param boot_class The name of the main class, which will own the shared
+ * object.
+ * @param header Text which will be prepended to generated C/XS files --
+ * typically, an "autogenerated file" warning.
+ * @param footer Text to be appended to the end of generated C/XS files --
+ * typically copyright information.
+ */
CFCPerl*
CFCPerl_new(struct CFCParcel *parcel, struct CFCHierarchy *hierarchy,
const char *lib_dir, const char *boot_class, const char *header,
@@ -46,9 +87,15 @@ CFCPerl_destroy(CFCPerl *self);
char**
CFCPerl_write_pod(CFCPerl *self);
+/** Write out "boot" files to the Hierarchy's "dest_dir" which contain code
+ * for bootstrapping Clownfish classes.
+ */
void
CFCPerl_write_boot(CFCPerl *self);
+/** Generate the XS bindings (including "Autobind.pm") for all classes in the
+ * hierarchy.
+ */
void
CFCPerl_write_bindings(CFCPerl *self);
Modified: incubator/lucy/trunk/clownfish/src/CFCPerlClass.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCPerlClass.h?rev=1293478&r1=1293477&r2=1293478&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCPerlClass.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCPerlClass.h Fri Feb 24 23:26:59 2012
@@ -29,6 +29,14 @@ struct CFCPerlPod;
struct CFCPerlMethod;
struct CFCPerlConstructor;
+/** Clownfish::CFC::Binding::Perl::Class - Generate Perl binding code for a
+ * Clownfish::CFC::Class.
+ */
+
+/**
+ * @param parcel A Clownfish::CFC::Parcel.
+ * @param class_name The name of the class to be registered.
+ */
CFCPerlClass*
CFCPerlClass_new(struct CFCParcel *parcel, const char *class_name);
@@ -39,12 +47,19 @@ CFCPerlClass_init(CFCPerlClass *self, st
void
CFCPerlClass_destroy(CFCPerlClass *self);
+/** Add a new class binding to the registry. Each unique parcel/class-name
+ * combination may only be registered once.
+ */
void
CFCPerlClass_add_to_registry(CFCPerlClass *self);
+/** Given a class name, return a class binding if one exists.
+ */
CFCPerlClass*
CFCPerlClass_singleton(const char *class_name);
+/** All registered bindings.
+ */
CFCPerlClass**
CFCPerlClass_registry();
@@ -69,18 +84,29 @@ CFCPerlClass_exclude_method(CFCPerlClass
void
CFCPerlClass_exclude_constructor(CFCPerlClass *self);
+/** Return an array of Clownfish::CFC::Binding::Perl::Method objects.
+ */
struct CFCPerlMethod**
CFCPerlClass_method_bindings(CFCPerlClass *self);
+/** Return an array of Clownfish::CFC::Binding::Perl::Constructor objects.
+ */
struct CFCPerlConstructor**
CFCPerlClass_constructor_bindings(CFCPerlClass *self);
+/** Auto-generate POD according to the make_pod spec, if such a spec was
+ * supplied.
+ */
char*
CFCPerlClass_create_pod(CFCPerlClass *self);
+/** Accessor for the Clownfish::CFC::Class module to be bound.
+ */
struct CFCClass*
CFCPerlClass_get_client(CFCPerlClass *self);
+/** Accessor.
+ */
const char*
CFCPerlClass_get_class_name(CFCPerlClass *self);
@@ -89,6 +115,8 @@ CFCPerlClass_get_class_name(CFCPerlClass
void
CFCPerlClass_append_xs(CFCPerlClass *self, const char *xs);
+/** Accessor for verbatim XS code.
+ */
const char*
CFCPerlClass_get_xs_code(CFCPerlClass *self);
Modified: incubator/lucy/trunk/clownfish/src/CFCPerlConstructor.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCPerlConstructor.h?rev=1293478&r1=1293477&r2=1293478&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCPerlConstructor.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCPerlConstructor.h Fri Feb 24 23:26:59 2012
@@ -24,6 +24,23 @@ extern "C" {
typedef struct CFCPerlConstructor CFCPerlConstructor;
struct CFCClass;
+/** Clownfish::CFC::Binding::Perl::Constructor - Binding for an object method.
+ *
+ * This class isa Clownfish::CFC::Binding::Perl::Subroutine -- see its
+ * documentation for various code-generating routines.
+ *
+ * Constructors are always bound to accept labeled params, even if there is only
+ * a single argument.
+ */
+
+/**
+ * @param class A L<Clownfish::CFC::Class>.
+ * @param alias A specifier for the name of the constructor, and
+ * optionally, a specifier for the implementing function. If C<alias> has a pipe
+ * character in it, the text to the left of the pipe will be used as the Perl
+ * alias, and the text to the right will be used to determine which C function
+ * should be bound. The default function is "init".
+ */
CFCPerlConstructor*
CFCPerlConstructor_new(struct CFCClass *klass, const char *alias,
const char *initializer);
@@ -35,6 +52,8 @@ CFCPerlConstructor_init(CFCPerlConstruct
void
CFCPerlConstructor_destroy(CFCPerlConstructor *self);
+/** Generate C code for the XSUB.
+ */
char*
CFCPerlConstructor_xsub_def(CFCPerlConstructor *self);
Modified: incubator/lucy/trunk/clownfish/src/CFCPerlMethod.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCPerlMethod.h?rev=1293478&r1=1293477&r2=1293478&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCPerlMethod.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCPerlMethod.h Fri Feb 24 23:26:59 2012
@@ -21,12 +21,27 @@
extern "C" {
#endif
+/** Clownfish::CFC::Binding::Perl::Method - Binding for an object method.
+ *
+ *
+ * This class isa Clownfish::CFC::Binding::Perl::Subroutine -- see its
+ * documentation for various code-generating routines.
+ *
+ * Method bindings use labeled parameters if the C function takes more than one
+ * argument (other than "self"). If there is only one argument, the binding
+ * will be set up to accept a single positional argument.
+ */
typedef struct CFCPerlMethod CFCPerlMethod;
struct CFCMethod;
CFCPerlMethod*
CFCPerlMethod_new(struct CFCMethod *method, const char *alias);
+/**
+ * @param method A Clownfish::CFC::Method.
+ * @param alias The perl name for the method. Defaults to the lowercased name
+ * of the supplied Clownfish Method.
+ */
CFCPerlMethod*
CFCPerlMethod_init(CFCPerlMethod *self, struct CFCMethod *method,
const char *alias);
@@ -34,6 +49,8 @@ CFCPerlMethod_init(CFCPerlMethod *self,
void
CFCPerlMethod_destroy(CFCPerlMethod *self);
+/** Generate C code for the XSUB.
+ */
char*
CFCPerlMethod_xsub_def(CFCPerlMethod *self);
Modified: incubator/lucy/trunk/clownfish/src/CFCPerlSub.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCPerlSub.h?rev=1293478&r1=1293477&r2=1293478&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCPerlSub.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCPerlSub.h Fri Feb 24 23:26:59 2012
@@ -39,6 +39,23 @@ struct CFCPerlSub {
};
#endif
+/** Clownfish::CFC::Binding::Perl::Subroutine - Abstract base binding for a
+ * Clownfish::CFC::Function.
+ *
+ * This class is used to generate binding code for invoking Clownfish's
+ * functions and methods across the Perl/C barrier.
+ */
+
+/** Abstract constructor.
+ *
+ * @param param_list A Clownfish::CFC::ParamList.
+ * @param class_name The name of the Perl class that the subroutine belongs
+ * to.
+ * @param alias The local, unqualified name for the Perl subroutine that
+ * will be used to invoke the function.
+ * @param use_labeled_params True if the binding should take hash-style
+ * labeled parameters, false if it should take positional arguments.
+ */
CFCPerlSub*
CFCPerlSub_init(CFCPerlSub *self, struct CFCParamList *param_list,
const char *class_name, const char *alias,
@@ -47,6 +64,10 @@ CFCPerlSub_init(CFCPerlSub *self, struct
void
CFCPerlSub_destroy(CFCPerlSub *self);
+/** Return Perl code initializing a package-global hash where all the keys are
+ * the names of labeled params. The hash's name consists of the the binding's
+ * perl_name() plus "_PARAMS".
+ */
char*
CFCPerlSub_params_hash_def(CFCPerlSub *self);
@@ -56,18 +77,33 @@ CFCPerlSub_build_allot_params(CFCPerlSub
struct CFCParamList*
CFCPerlSub_get_param_list(CFCPerlSub *self);
+/** Accessor.
+ */
const char*
CFCPerlSub_get_class_name(CFCPerlSub *self);
+/** Accessor.
+ */
int
CFCPerlSub_use_labeled_params(CFCPerlSub *self);
+/**
+ * @return the fully-qualified perl sub name.
+ */
const char*
CFCPerlSub_perl_name(CFCPerlSub *self);
+/**
+ * @return the fully-qualified name of the C function that implements the
+ * XSUB.
+ */
const char*
CFCPerlSub_c_name(CFCPerlSub *self);
+/**
+ * @return a string containing the names of arguments to feed to bound C
+ * function, joined by commas.
+ */
const char*
CFCPerlSub_c_name_list(CFCPerlSub *self);
Modified: incubator/lucy/trunk/clownfish/src/CFCPerlTypeMap.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCPerlTypeMap.h?rev=1293478&r1=1293477&r2=1293478&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCPerlTypeMap.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCPerlTypeMap.h Fri Feb 24 23:26:59 2012
@@ -21,15 +21,50 @@
extern "C" {
#endif
+/** Clownfish::CFC::Binding::Perl::TypeMap - Convert between Clownfish and
+ * Perl via XS.
+ *
+ * TypeMap serves up C code fragments for translating between Perl data
+ * structures and Clownfish data structures. The functions to_perl() and
+ * from_perl() achieve this for individual types; write_xs_typemap() exports
+ * all types using the XS "typemap" format documented in "perlxs".
+ */
+
struct CFCHierarchy;
struct CFCType;
+/** Return an expression which converts from a Perl scalar to a variable of
+ * the specified type.
+ *
+ * @param type A Clownfish::CFC::Type, which will be used to select the
+ * mapping code.
+ * @param xs_var The C name of the Perl scalar from which we are extracting
+ * a value.
+ */
char*
CFCPerlTypeMap_from_perl(struct CFCType *type, const char *xs_var);
+/** Return an expression converts from a variable of type $type to a Perl
+ * scalar.
+ *
+ * @param type A Clownfish::CFC::Type, which will be used to select the
+ * mapping code.
+ * @param cf_var The name of the variable from which we are extracting a
+ * value.
+ */
char*
CFCPerlTypeMap_to_perl(struct CFCType *type, const char *cf_var);
+/** Auto-generate a "typemap" file that adheres to the conventions documented
+ * in "perlxs".
+ *
+ * We generate this file on the fly rather than maintain a static copy because
+ * we want an entry for each Clownfish type so that we can differentiate
+ * between them when checking arguments. Keeping the entries up-to-date
+ * manually as classes come and go would be a pain.
+ *
+ * @param hierarchy A Clownfish::CFC::Hierarchy.
+ */
void
CFCPerlTypeMap_write_xs_typemap(struct CFCHierarchy *hierarchy);