From 7817ba4dfeb754838a0da8f159127895c2dcf4fc Mon Sep 17 00:00:00 2001 From: Nicholas Clark Date: Thu, 16 Nov 2000 16:48:25 +0000 Subject: [PATCH] Re: 20001101.003 PDL Message-ID: <20001116164825.B93487@plum.flirble.org> p4raw-id: //depot/perl@7717 --- lib/ExtUtils/xsubpp | 17 ++++++++++++++--- pod/perlxs.pod | 50 ++++++++++++++++++++++++++++---------------------- pod/perlxstut.pod | 3 ++- 3 files changed, 44 insertions(+), 26 deletions(-) diff --git a/lib/ExtUtils/xsubpp b/lib/ExtUtils/xsubpp index 1e9ff45..8599ddc 100755 --- a/lib/ExtUtils/xsubpp +++ b/lib/ExtUtils/xsubpp @@ -109,7 +109,7 @@ sub Q ; # Global Constants -$XSUBPP_version = "1.9507"; +$XSUBPP_version = "1.9508"; my ($Is_VMS, $SymSet); if ($^O eq 'VMS') { @@ -859,10 +859,21 @@ print("#line 1 \"$filename\"\n") firstmodule: while (<$FH>) { if (/^=/) { + my $podstartline = $.; do { - next firstmodule if /^=cut\s*$/; + if (/^=cut\s*$/) { + print("/* Skipped embedded POD. */\n"); + printf("#line %d \"$filename\"\n", $. + 1) + if $WantLineNumbers; + next firstmodule + } + } while (<$FH>); - &Exit; + # At this point $. is at end of file so die won't state the start + # of the problem, and as we haven't yet read any lines &death won't + # show the correct line in the message either. + die ("Error: Unterminated pod in $filename, line $podstartline\n") + unless $lastline; } last if ($Module, $Package, $Prefix) = /^MODULE\s*=\s*([\w:]+)(?:\s+PACKAGE\s*=\s*([\w:]+))?(?:\s+PREFIX\s*=\s*(\S+))?\s*$/; diff --git a/pod/perlxs.pod b/pod/perlxs.pod index 781afe6..bd4e99c 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -66,7 +66,9 @@ for the library being linked. A file in XS format starts with a C language section which goes until the first C> directive. Other XS directives and XSUB definitions may follow this line. The "language" used in this part of the file -is usually referred to as the XS language. +is usually referred to as the XS language. B recognizes and +skips POD (see L) in both the C and XS language sections, which +allows the XS file to contain embedded documentation. See L for a tutorial on the whole extension creation process. @@ -207,9 +209,9 @@ separate lines and should be flush left-adjusted. double x sin(x) double x -The rest of the function description may be indented or left-adjusted. The following example -shows a function with its body left-adjusted. Most examples in this -document will indent the body for better readability. +The rest of the function description may be indented or left-adjusted. The +following example shows a function with its body left-adjusted. Most +examples in this document will indent the body for better readability. CORRECT @@ -276,16 +278,14 @@ mercy of this heuristics unless you use C as return value.) =head2 The MODULE Keyword -The MODULE keyword is used to start the XS code and to -specify the package of the functions which are being -defined. All text preceding the first MODULE keyword is -considered C code and is passed through to the output -untouched. Every XS module will have a bootstrap function -which is used to hook the XSUBs into Perl. The package name -of this bootstrap function will match the value of the last -MODULE statement in the XS source files. The value of -MODULE should always remain constant within the same XS -file, though this is not required. +The MODULE keyword is used to start the XS code and to specify the package +of the functions which are being defined. All text preceding the first +MODULE keyword is considered C code and is passed through to the output with +POD stripped, but otherwise untouched. Every XS module will have a +bootstrap function which is used to hook the XSUBs into Perl. The package +name of this bootstrap function will match the value of the last MODULE +statement in the XS source files. The value of MODULE should always remain +constant within the same XS file, though this is not required. The following example will start the XS code and will place all functions in a package named RPC. @@ -776,7 +776,7 @@ is expected that the C function will write through these pointers The return list of the generated Perl function consists of the C return value from the function (unless the XSUB is of C return type or C was used) followed by all the C -and C parameters (in the order of appearence). Say, an XSUB +and C parameters (in the order of appearance). Say, an XSUB void day_month(OUTLIST day, IN unix_time, OUTLIST month) @@ -1347,13 +1347,19 @@ C<&> through, so the function call looks like C. OUTPUT: timep -=head2 Inserting Comments and C Preprocessor Directives +=head2 Inserting POD, Comments and C Preprocessor Directives -C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, -CODE:, PPCODE:, POST_CALL:, and CLEANUP: blocks, as well as outside the functions. -Comments are allowed anywhere after the MODULE keyword. The compiler -will pass the preprocessor directives through untouched and will remove -the commented lines. +C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:, +PPCODE:, POST_CALL:, and CLEANUP: blocks, as well as outside the functions. +Comments are allowed anywhere after the MODULE keyword. The compiler will +pass the preprocessor directives through untouched and will remove the +commented lines. POD documentation is allowed at any point, both in the +C and XS language sections. POD must be terminated with a C<=cut> command; +C will exit with an error if it does not. It is very unlikely that +human generated C code will be mistaken for POD, as most indenting styles +result in whitespace in front of any line starting with C<=>. Machine +generated XS files may fall into this trap unless care is taken to +ensure that a space breaks the sequence "\n=". Comments can be added to XSUBs by placing a C<#> as the first non-whitespace of a line. Care should be taken to avoid making the @@ -1613,7 +1619,7 @@ getnetconfigent() XSUB and an object created by a normal Perl subroutine. The typemap is a collection of code fragments which are used by the B compiler to map C function parameters and values to Perl values. The -typemap file may consist of three sections labeled C, C, and +typemap file may consist of three sections labelled C, C, and C. An unlabelled initial section is assumed to be a C section. The INPUT section tells the compiler how to translate Perl values diff --git a/pod/perlxstut.pod b/pod/perlxstut.pod index 347b46e..5b7ed6d 100644 --- a/pod/perlxstut.pod +++ b/pod/perlxstut.pod @@ -682,7 +682,8 @@ the meaning of these elements, pay attention to the line which reads Anything before this line is plain C code which describes which headers to include, and defines some convenience functions. No translations are -performed on this part, it goes into the generated output C file as is. +performed on this part, apart from having embedded POD documentation +skipped over (see L) it goes into the generated output C file as is. Anything after this line is the description of XSUB functions. These descriptions are translated by B into C code which -- 2.7.4