Alt-Devel-CallParser-ButWorking

 view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME

Devel::CallParser - custom parsing attached to subroutines

DESCRIPTION

This module provides a C API, for XS modules, concerned with custom
parsing.  It is centred around the function "cv_set_call_parser", which
allows XS code to attach a magical annotation to a Perl subroutine,
resulting in resolvable calls to that subroutine having their arguments
parsed by arbitrary C code.  (This is a more conveniently structured
facility than the core's "PL_keyword_plugin" API.)  This module makes
"cv_set_call_parser" and several supporting functions available.

This module provides the implementation of the functions at runtime,
and also at compile time supplies the C header file which provides access
to the functions.

INSTALLATION

lib/Devel/CallParser.pm  view on Meta::CPAN

=head1 NAME

Devel::CallParser - custom parsing attached to subroutines

=head1 SYNOPSIS

	# to generate header prior to XS compilation

	perl -MDevel::CallParser=callparser0_h \
		-e 'print callparser0_h' > callparser0.h
	perl -MDevel::CallParser=callparser1_h \
		-e 'print callparser1_h' > callparser1.h

lib/Devel/CallParser.pm  view on Meta::CPAN

	args = parse_args_unary(&flags);
	args = parse_args_list(&flags);
	args = parse_args_block_list(&flags);
	args = parse_args_proto(namegv, protosv, &flags);
	args = parse_args_proto_or_list(namegv, protosv, &flags);

=head1 DESCRIPTION

This module provides a C API, for XS modules, concerned with custom
parsing.  It is centred around the function C<cv_set_call_parser>, which
allows XS code to attach a magical annotation to a Perl subroutine,
resulting in resolvable calls to that subroutine having their arguments
parsed by arbitrary C code.  (This is a more conveniently structured
facility than the core's C<PL_keyword_plugin> API.)  This module makes
C<cv_set_call_parser> and several supporting functions available.

This module provides the implementation of the functions at runtime.
It also, at compile time, supplies the C header file and link
library which provide access to the functions.  In normal use,
L</callparser0_h>/L</callparser1_h> and L</callparser_linkable> should
be called at build time (not authoring time) for the module that wishes

lib/Devel/CallParser.pm  view on Meta::CPAN

The way this module determines which parsing code to use for a subroutine
conflicts with the expectations of some particularly tricky modules that
use nasty hacks to perform custom parsing without proper support from the
Perl core.  In particular, this module is incompatible with versions of
L<Devel::Declare> prior to 0.006004 and versions of L<Data::Alias> prior
to 1.13.  An arrangement has been reached that allows later versions of
those modules to coexist with this module.

Custom parsing code is only invoked if the subroutine to which it is
attached is invoked using an unqualified name.  For example, the name
C<foo> works, but the name C<main::foo> will not, despite referring
to the same subroutine.  This is an unavoidable limitation imposed by
the core's interim facility for custom parser plugins.  This should
be resolved if the API provided by this module, or something similar,
migrates into the core in a future version of Perl.

=head1 SEE ALSO

L<Devel::CallChecker>