In perl.git, the branch blead has been updated
<http://perl5.git.perl.org/perl.git/commitdiff/d0dcc4028a160eba03640da1ff1d34087f930ec1?hp=20c002109cce68de85ddf6451b809a24ae6d650a>
- Log -----------------------------------------------------------------
commit d0dcc4028a160eba03640da1ff1d34087f930ec1
Author: Karl Williamson <pub...@khwilliamson.com>
Date: Sun Sep 19 12:29:02 2010 -0600
handy.h: isASCII() extend to work on > 8 bit values
Prior to this patch, if isASCII() is called with something like '256',
it would return true.
For some reason unknown to me, U64 is defined only inside the perl core.
However, the equivalent U64TYPE is known everywhere, so in the macro
that can be called outside of core, use that instead.
The commit log doesn't give a reason for not defining U64 outside of
core, and no tests in the suite fail when it is defined outside core.
But out of caution, I'm just doing this workaround instead of exposing
U64.
M handy.h
commit 89e8dfa95ef07c947545bb90a358cf884038b1eb
Author: Karl Williamson <pub...@khwilliamson.com>
Date: Sun Sep 19 11:57:04 2010 -0600
handy.h: Don't use isascii() as not in all libc's
EBCDIC platforms use isascii(), but is not in all libc's so better to
use our own.
M handy.h
commit 06dc89afdb8be14f426e43dc96c714e43c31ed64
Author: Karl Williamson <pub...@khwilliamson.com>
Date: Sun Sep 19 11:04:34 2010 -0600
handy.h: Fix-up documentation
Previous documentation was wrong for EBCDIC platforms. This fixes that
and adds some more explanation.
M handy.h
commit e7c1e6c17f14a02226d41112091dfb1849c29ff2
Author: Karl Williamson <pub...@khwilliamson.com>
Date: Sun Sep 19 10:38:14 2010 -0600
handy.h: toUPPER is not a char class fcn
toUPPER() and toLOWER() were grouped with the character class functions
(in perlapi), to which they are related, but aren't the same. Create a
new heading for these.
M handy.h
commit 151c3fe5f7dc89494468b7e5b9b616c7836b255b
Author: Karl Williamson <pub...@khwilliamson.com>
Date: Sun Sep 19 10:20:58 2010 -0600
autodoc.pl: Allow heading level documentation
This patch changes autodoc.pl to accept text that is to come immediately
after headings, so that it applies to across the whole section, and not
just to an individual function within that section.
M autodoc.pl
-----------------------------------------------------------------------
Summary of changes:
autodoc.pl | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
handy.h | 53 +++++++++++++++++++++++++++++++----------------------
2 files changed, 85 insertions(+), 24 deletions(-)
diff --git a/autodoc.pl b/autodoc.pl
index c271bf4..26eb871 100644
--- a/autodoc.pl
+++ b/autodoc.pl
@@ -15,6 +15,13 @@
#
# This script is normally invoked as part of 'make all', but is also
# called from from regen.pl.
+#
+# '=head1' are the only headings looked for. If the next line after the
+# heading begins with a word character, it is considered to be the first line
+# of documentation that applies to the heading itself. That is, it is output
+# immediately after the heading, before the first function, and not indented.
+# The next input line that is a pod directive terminates this heading-level
+# documentation.
use strict;
@@ -39,7 +46,7 @@ my $curheader = "Unknown section";
sub autodoc ($$) { # parse a file and extract documentation info
my($fh,$file) = @_;
- my($in, $doc, $line);
+ my($in, $doc, $line, $header_doc);
FUNC:
while (defined($in = <$fh>)) {
if ($in =~ /^#\s*define\s+([A-Za-z_][A-Za-z_0-9]+)\(/ &&
@@ -49,6 +56,35 @@ FUNC:
}
if ($in=~ /^=head1 (.*)/) {
$curheader = $1;
+
+ # If the next line begins with a word char, then is the start of
+ # heading-level documentation.
+ if (defined($doc = <$fh>)) {
+ if ($doc !~ /^\w/) {
+ $in = $doc;
+ redo FUNC;
+ }
+ $header_doc = $doc;
+ $line++;
+
+ # Continue getting the heading-level documentation until read
+ # in any pod directive (or as a fail-safe, find a closing
+ # comment to this pod in a C language file
+HDR_DOC:
+ while (defined($doc = <$fh>)) {
+ if ($doc =~ /^=\w/) {
+ $in = $doc;
+ redo FUNC;
+ }
+ $line++;
+
+ if ($doc =~ m:^\s*\*/$:) {
+ warn "=cut missing? $file:$line:$doc";;
+ last HDR_DOC;
+ }
+ $header_doc .= $doc;
+ }
+ }
next FUNC;
}
$line++;
@@ -111,6 +147,13 @@ DOC:
$docs{$inline_where}{$curheader}{$name}
= [$flags, $docs, $ret, $file, @args];
+ # Create a special entry with an empty-string name for the
+ # heading-level documentation.
+ if (defined $header_doc) {
+ $docs{$inline_where}{$curheader}{""} = $header_doc;
+ undef $header_doc;
+ }
+
if (defined $doc) {
if ($doc =~ /^=(?:for|head)/) {
$in = $doc;
@@ -173,7 +216,16 @@ _EOH_
# case insensitive sort, with fallback for determinacy
for $key (sort { uc($a) cmp uc($b) || $a cmp $b } keys %$dochash) {
my $section = $dochash->{$key};
- print $fh "\n=head1 $key\n\n=over 8\n\n";
+ print $fh "\n=head1 $key\n\n";
+
+ # Output any heading-level documentation and delete so won't get in
+ # the way later
+ if (exists $section->{""}) {
+ print $fh $section->{""} . "\n";
+ delete $section->{""};
+ }
+ print $fh "=over 8\n\n";
+
# Again, fallback for determinacy
for my $key (sort { uc($a) cmp uc($b) || $a cmp $b } keys %$section) {
docout($fh, $key, $section->{$key});
diff --git a/handy.h b/handy.h
index e091a9b..b41c1c8 100644
--- a/handy.h
+++ b/handy.h
@@ -438,42 +438,51 @@ C<strncmp>).
/*
=head1 Character classes
+The functions in this section operate using the character set of the platform
+Perl is running on, and are unaffected by locale. For ASCII platforms, they
+will all return false for characters outside the ASCII range. For EBCDIC
+platforms, they use the code page of the platform. The code pages that Perl
+knows about all have 8-bit characters, so most of these functions will return
+true for more characters than on ASCII platforms.
=for apidoc Am|bool|isALNUM|char ch
-Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
-alphanumeric character (including underscore) or digit.
+Returns a boolean indicating whether the C C<char> is an
+alphanumeric character (including underscore) or digit in the platform's native
+character set.
=for apidoc Am|bool|isALPHA|char ch
-Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
-alphabetic character.
+Returns a boolean indicating whether the C C<char> is an
+alphabetic character in the platform's native character set.
=for apidoc Am|bool|isSPACE|char ch
-Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
-whitespace.
+Returns a boolean indicating whether the C C<char> is a
+whitespace character in the platform's native character set.
=for apidoc Am|bool|isDIGIT|char ch
-Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
-digit.
+Returns a boolean indicating whether the C C<char> is a
+digit in the platform's native character set.
=for apidoc Am|bool|isOCTAL|char ch
-Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
-octal digit, [0-7].
+Returns a boolean indicating whether the C C<char> is an
+octal digit, [0-7] in the platform's native character set.
=for apidoc Am|bool|isUPPER|char ch
-Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
-uppercase character.
+Returns a boolean indicating whether the C C<char> is an
+uppercase character in the platform's native character set.
=for apidoc Am|bool|isLOWER|char ch
-Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
-lowercase character.
+Returns a boolean indicating whether the C C<char> is a
+lowercase character in the platform's native character set.
+
+=head1 Character case changing
=for apidoc Am|char|toUPPER|char ch
-Converts the specified character to uppercase. Characters outside the
-US-ASCII (Basic Latin) range are viewed as not having any case.
+Converts the specified character to uppercase in the platform's native
+character set, if possible; otherwise returns the input character itself.
=for apidoc Am|char|toLOWER|char ch
-Converts the specified character to lowercase. Characters outside the
-US-ASCII (Basic Latin) range are viewed as not having any case.
+Converts the specified character to lowercase in the platform's native
+character set, if possible; otherwise returns the input character itself.
=cut
@@ -493,9 +502,10 @@ patched there. The file as of this writing is
cpan/Devel-PPPort/parts/inc/misc
* machine has an 8-bit byte, so if c is stored in a byte, the sizeof()
* guarantees that this evaluates to a constant true at compile time. The use
* of the mask instead of '< 256' keeps gcc from complaining that it is alway
- * true, when c's storage class is a byte */
+ * true, when c's storage class is a byte. Use U64TYPE because U64 is known
+ * only in the perl core, and this macro can be called from outside that */
#ifdef HAS_QUAD
-# define FITS_IN_8_BITS(c) ((sizeof(c) == 1) || (((U64)(c) & 0xFF) ==
(U64)(c)))
+# define FITS_IN_8_BITS(c) ((sizeof(c) == 1) || (((U64TYPE)(c) & 0xFF) ==
(U64TYPE)(c)))
#else
# define FITS_IN_8_BITS(c) ((sizeof(c) == 1) || (((U32)(c) & 0xFF) ==
(U32)(c)))
#endif
@@ -521,12 +531,12 @@ patched there. The file as of this writing is
cpan/Devel-PPPort/parts/inc/misc
#define isBLANK(c) ((c) == ' ' || (c) == '\t')
#define isDIGIT(c) ((c) >= '0' && (c) <= '9')
#define isOCTAL(c) ((c) >= '0' && (c) <= '7')
+#define isASCII(c) (FITS_IN_8_BITS(c) ? NATIVE_TO_UNI((U8) c) <= 127 : 0)
#ifdef EBCDIC
/* In EBCDIC we do not do locales: therefore() isupper() is fine. */
# define isUPPER(c) isupper(c)
# define isLOWER(c) islower(c)
# define isALNUMC(c) isalnum(c)
-# define isASCII(c) isascii(c)
# define isCNTRL(c) iscntrl(c)
# define isGRAPH(c) isgraph(c)
# define isPRINT(c) isprint(c)
@@ -538,7 +548,6 @@ patched there. The file as of this writing is
cpan/Devel-PPPort/parts/inc/misc
# define isUPPER(c) ((c) >= 'A' && (c) <= 'Z')
# define isLOWER(c) ((c) >= 'a' && (c) <= 'z')
# define isALNUMC(c) (isALPHA(c) || isDIGIT(c))
-# define isASCII(c) ((U8) (c) <= 127)
# define isCNTRL(c) ((U8) (c) < ' ' || (c) == 127)
# define isGRAPH(c) (isALNUM(c) || isPUNCT(c))
# define isPRINT(c) (((c) >= 32 && (c) < 127))
--
Perl5 Master Repository
