sf.spec.bccheck.enable - Added comment into common_props.ant.xml to explain how the value is used.
# $Id: SAX.pm,v 1.27 2007/02/07 09:33:50 grant Exp $package XML::SAX;use strict;use vars qw($VERSION @ISA @EXPORT_OK);$VERSION = '0.15';use Exporter ();@ISA = ('Exporter');@EXPORT_OK = qw(Namespaces Validation);use File::Basename qw(dirname);use File::Spec ();use Symbol qw(gensym);use XML::SAX::ParserFactory (); # loaded for simplicityuse constant PARSER_DETAILS => "ParserDetails.ini";use constant Namespaces => "http://xml.org/sax/features/namespaces";use constant Validation => "http://xml.org/sax/features/validation";my $known_parsers = undef;# load_parsers takes the ParserDetails.ini file out of the same directory# that XML::SAX is in, and looks at it. Format in POD below=begin EXAMPLE[XML::SAX::PurePerl]http://xml.org/sax/features/namespaces = 1http://xml.org/sax/features/validation = 0# a comment# blank lines ignored[XML::SAX::AnotherParser]http://xml.org/sax/features/namespaces = 0http://xml.org/sax/features/validation = 1=end EXAMPLE=cutsub load_parsers { my $class = shift; my $dir = shift; # reset parsers $known_parsers = []; # get directory from wherever XML::SAX is installed if (!$dir) { $dir = $INC{'XML/SAX.pm'}; $dir = dirname($dir); } my $fh = gensym(); if (!open($fh, File::Spec->catfile($dir, "SAX", PARSER_DETAILS))) { XML::SAX->do_warn("could not find " . PARSER_DETAILS . " in $dir/SAX\n"); return $class; } $known_parsers = $class->_parse_ini_file($fh); return $class;}sub _parse_ini_file { my $class = shift; my ($fh) = @_; my @config; my $lineno = 0; while (defined(my $line = <$fh>)) { $lineno++; my $original = $line; # strip whitespace $line =~ s/\s*$//m; $line =~ s/^\s*//m; # strip comments $line =~ s/[#;].*$//m; # ignore blanks next if $line =~ /^$/m; # heading if ($line =~ /^\[\s*(.*)\s*\]$/m) { push @config, { Name => $1 }; next; } # instruction elsif ($line =~ /^(.*?)\s*?=\s*(.*)$/) { unless(@config) { push @config, { Name => '' }; } $config[-1]{Features}{$1} = $2; } # not whitespace, comment, or instruction else { die "Invalid line in ini: $lineno\n>>> $original\n"; } } return \@config;}sub parsers { my $class = shift; if (!$known_parsers) { $class->load_parsers(); } return $known_parsers;}sub remove_parser { my $class = shift; my ($parser_module) = @_; if (!$known_parsers) { $class->load_parsers(); } @$known_parsers = grep { $_->{Name} ne $parser_module } @$known_parsers; return $class;}sub add_parser { my $class = shift; my ($parser_module) = @_; if (!$known_parsers) { $class->load_parsers(); } # first load module, then query features, then push onto known_parsers, my $parser_file = $parser_module; $parser_file =~ s/::/\//g; $parser_file .= ".pm"; require $parser_file; my @features = $parser_module->supported_features(); my $new = { Name => $parser_module }; foreach my $feature (@features) { $new->{Features}{$feature} = 1; } # If exists in list already, move to end. my $done = 0; my $pos = undef; for (my $i = 0; $i < @$known_parsers; $i++) { my $p = $known_parsers->[$i]; if ($p->{Name} eq $parser_module) { $pos = $i; } } if (defined $pos) { splice(@$known_parsers, $pos, 1); push @$known_parsers, $new; $done++; } # Otherwise (not in list), add at end of list. if (!$done) { push @$known_parsers, $new; } return $class;}sub save_parsers { my $class = shift; # get directory from wherever XML::SAX is installed my $dir = $INC{'XML/SAX.pm'}; $dir = dirname($dir); my $file = File::Spec->catfile($dir, "SAX", PARSER_DETAILS); chmod 0644, $file; unlink($file); my $fh = gensym(); open($fh, ">$file") || die "Cannot write to $file: $!"; foreach my $p (@$known_parsers) { print $fh "[$p->{Name}]\n"; foreach my $key (keys %{$p->{Features}}) { print $fh "$key = $p->{Features}{$key}\n"; } print $fh "\n"; } print $fh "\n"; close $fh; return $class;}sub do_warn { my $class = shift; # Don't output warnings if running under Test::Harness warn(@_) unless $ENV{HARNESS_ACTIVE};}1;__END__=head1 NAMEXML::SAX - Simple API for XML=head1 SYNOPSIS use XML::SAX; # get a list of known parsers my $parsers = XML::SAX->parsers(); # add/update a parser XML::SAX->add_parser(q(XML::SAX::PurePerl)); # remove parser XML::SAX->remove_parser(q(XML::SAX::Foodelberry)); # save parsers XML::SAX->save_parsers();=head1 DESCRIPTIONXML::SAX is a SAX parser access API for Perl. It includes classesand APIs required for implementing SAX drivers, along with a factoryclass for returning any SAX parser installed on the user's system.=head1 USING A SAX2 PARSERThe factory class is XML::SAX::ParserFactory. Please see thedocumentation of that module for how to instantiate a SAX parser:L<XML::SAX::ParserFactory>. However if you don't want to load upanother manual page, here's a short synopsis: use XML::SAX::ParserFactory; use XML::SAX::XYZHandler; my $handler = XML::SAX::XYZHandler->new(); my $p = XML::SAX::ParserFactory->parser(Handler => $handler); $p->parse_uri("foo.xml"); # or $p->parse_string("<foo/>") or $p->parse_file($fh);This will automatically load a SAX2 parser (defaulting toXML::SAX::PurePerl if no others are found) and return it to you.In order to learn how to use SAX to parse XML, you will need to readL<XML::SAX::Intro> and for reference, L<XML::SAX::Specification>.=head1 WRITING A SAX2 PARSERThe first thing to remember in writing a SAX2 parser is to subclassXML::SAX::Base. This will make your life infinitely easier, by providinga number of methods automagically for you. See L<XML::SAX::Base> for moredetails.When writing a SAX2 parser that is compatible with XML::SAX, you needto inform XML::SAX of the presence of that driver when you install it.In order to do that, XML::SAX contains methods for saving the fact thatthe parser exists on your system to a "INI" file, which is then loadedto determine which parsers are installed.The best way to do this is to follow these rules:=over 4=item * Add XML::SAX as a prerequisite in Makefile.PL: WriteMakefile( ... PREREQ_PM => { 'XML::SAX' => 0 }, ... );Alternatively you may wish to check for it in other ways that willcause more than just a warning.=item * Add the following code snippet to your Makefile.PL: sub MY::install { package MY; my $script = shift->SUPER::install(@_); if (ExtUtils::MakeMaker::prompt( "Do you want to modify ParserDetails.ini?", 'Y') =~ /^y/i) { $script =~ s/install :: (.*)$/install :: $1 install_sax_driver/m; $script .= <<"INSTALL"; install_sax_driver : \t\@\$(PERL) -MXML::SAX -e "XML::SAX->add_parser(q(\$(NAME)))->save_parsers()" INSTALL } return $script; }Note that you should check the output of this - \$(NAME) will use the name ofyour distribution, which may not be exactly what you want. For example XML::LibXMLhas a driver called XML::LibXML::SAX::Generator, which is used in place of\$(NAME) in the above.=item * Add an XML::SAX test:A test file should be added to your t/ directory containing something like thefollowing: use Test; BEGIN { plan tests => 3 } use XML::SAX; use XML::SAX::PurePerl::DebugHandler; XML::SAX->add_parser(q(XML::SAX::MyDriver)); local $XML::SAX::ParserPackage = 'XML::SAX::MyDriver'; eval { my $handler = XML::SAX::PurePerl::DebugHandler->new(); ok($handler); my $parser = XML::SAX::ParserFactory->parser(Handler => $handler); ok($parser); ok($parser->isa('XML::SAX::MyDriver'); $parser->parse_string("<tag/>"); ok($handler->{seen}{start_element}); };=back=head1 EXPORTSBy default, XML::SAX exports nothing into the caller's namespace. However youcan request the symbols C<Namespaces> and C<Validation> which are theURIs for those features, allowing an easier way to request those featuresvia ParserFactory: use XML::SAX qw(Namespaces Validation); my $factory = XML::SAX::ParserFactory->new(); $factory->require_feature(Namespaces); $factory->require_feature(Validation); my $parser = $factory->parser();=head1 AUTHORCurrent maintainer: Grant McLean, grantm@cpan.orgOriginally written by:Matt Sergeant, matt@sergeant.orgKip Hampton, khampton@totalcinema.comRobin Berjon, robin@knowscape.com=head1 LICENSEThis is free software, you may use it and distribute it underthe same terms as Perl itself.=head1 SEE ALSOL<XML::SAX::Base> for writing SAX Filters and ParsersL<XML::SAX::PurePerl> for an XML parser written in 100%pure perl.L<XML::SAX::Exception> for details on exception handling=cut