#
#  $Id: //depot/isms/skulker/cbd/1.1/lib/cbd-xml.pl#2 $
#
#  file: cbd-xml.pl
#  desc: CBD XML generation support
#

# limit scope
package CBD::XML;


# CBD to XML DTD (for validation)
my $DTD = 'http://xml.resource.org/doc/cbd/cbd.dtd';
my $DOCTYPE = qq|PUBLIC "-//Blocks//DTD CBD//EN" "$DTD"|;

## for test/debug - bjb, 26-apr-1999
#my $DTD = 'cbdtest.dtd';
#my $DOCTYPE = qq|SYSTEM "$DTD"|;


#
# generate standard XML header
#
sub header {
	my($cbd) = shift;

	# header we will build and return
	my($hdr);

	# XML version
	$hdr  = "<?xml version=\"1.0\"?>" . "\n";
	# will this change?
	$hdr .= "<!DOCTYPE cbd $DOCTYPE>" . "\n\n";

	$hdr .= "<cbd>" . "\n";

	$hdr;
}


#
# XML transformer info
#
sub transformer {
	my($cbd) = shift;

	my($xml) = '';

	# transform date
	my($date) = `/bin/date +"%d-%h-%Y, %T %Z"`;
	chomp($date);

	$xml = <<EoD;
<transformer>
<organization>Invisible Worlds, Inc.</organization>
<address>
<postal>
<street>1179 N. McDowell Blvd</street>
<city>Petaluma</city>
<region>California</region>
<code>94954</code>
<country>US</country>
</postal>
<email>webmaster\@invisible.net</email>
<uri>http://invisible.net/</uri>
</address>
<date>$date</date>
</transformer>

EoD

	$xml;
}


#
# generate standard XML trailer
#
sub trailer {
	my($cbd) = shift;

	my($trlr);

	$trlr .= "\n";

	$trlr .= "</cbd>" . "\n";

	$trlr;
}


#
# encode reserved characters
#
sub encode {
	my($foo) = shift;

#	$foo = XML::Parser::Expat::xml_escape($foo);

	# special case -- CBD SGML ENTITY values
	$foo =~ s/&emsp;/ /g;
	$foo =~ s/&ensp;/ /g;
	$foo =~ s/&llmdash;/_/g;
	$foo =~ s/&mdash;/ -- /g;
	$foo =~ s/&ndash;/ - /g;
	$foo =~ s/&sim;/ /g;

	# avoid double encoding &
	$foo =~ s/&amp;/&/g;
	# order is important with & substitution -- keep it first
	$foo =~ s/&/&amp;/g;

	$foo;
}


#
# decode reserved characters
#
sub decode {
	my($foo) = shift;

	$foo =~ s/&amp;/&/g;

	$foo;
}

#
# remove trailing and leading spaces
#
sub trim
{
	my($text) = shift;
        
	$text =~ s/^\s+|\s+$//g;

	$text;
}


#
# encode attribute values properly
#
sub encode_av {
	my($foo) = shift;

#	$foo = XML::Parser::Expat::xml_escape($foo);

	# remove trailing and leading spaces
	$foo = trim($foo);
	
	# avoid double encoding &
	$foo =~ s/&amp;/&/g;
	# order is important with & substitution -- keep it first
	$foo =~ s/&/\&amp;/g;
	$foo =~ s/'/\&apos;/g;
	$foo =~ s/"/\&quot;/g;
	$foo =~ s/</\&lt;/g;
	$foo =~ s/>/\&gt;/g;


	return "\"$foo\"";
}


# keep require happy -- DO NOT REMOVE
1;



=head1 NAME

cbd-xml.pl - XML specific processing

=head1 PACKAGE

CBD::XML

=head1 SYNOPSIS

require cbd-xml.pl;

=head1 REQUIRED

Perl, version 5.001 or higher

=head1 DESCRIPTION

XML Specific processing routines.

=over 3

=head1 METHODS

=head2 header

=item *

generates standard XML header

=item *

An XML header is returned.

=item example:

my ($header) = &CBD::XML::header($cbd);

=head2 transformer

=item *

generates transformer information for CBD doc

=item *

An XML transformer string is returned.

=item example:

my ($transformer) = &CBD::XML::transformer($cbd);

item example XML:

<transformer>

<organization>Invisible Worlds, Inc.</organization>

<address>

<postal>

<street>660 York Street</street>

<city>San Francisco</city>

<region>California</region>

<code>94110</code>

<country>U/country

</postal>

<email>edgar@invisible.net</email>

<uri>http://invisible.net/</uri>

</address>

<date>01-12-1999</date>

<canonical>

<uri>ftp://ftp.sec.gov/edgar/data/888/777777.txt</uri>

</canonical>

</transformer>

=head2 trim

=item *

Removes leading and trailing spaces from a string

=item example:

$str = &CBD::XML::trim($str);

=head2 encode_av

=item *

Encodes entities such as &, >, <, " and '

=item example:

$str = &CBD::XML::encode_av($str);

=item encoding performed:

& --> &amp;

< --> &lt;

=head2 encode

=item *

Encodes entities such as &mdash, &llmdash, &sim

=item example:

$str = &CBD::XML::encode($str);

=item encoding performed:

&mdash --> --

&llmdash --> --

=back

=head1 COPYRIGHT

Copyright 1999 Invisible Worlds.

=head1 AUTHOR

CBD::XML was written by Gautam Yegnanarayan <gautam@invisible.net>.

=cut