.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "XML::Smart::Tutorial 3"
.TH XML::Smart::Tutorial 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
XML::Smart::Tutorial \- Tutorial and examples for XML::Smart.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
This document is a tutorial for \fIXML::Smart\fR and shows some examples of usual things.
.SH "Working with contents:"
.IX Header "Working with contents:"
In \fIXML::Smart\fR the key \fICONTENT\fR is reserved and shouldn't be used directly,
since \fIXML::Smart\fR will deal with the convertion of arguments to node contents,
including multiple node contents autimatically.
.SS "What happens when you set a value:"
.IX Subsection "What happens when you set a value:"
.Vb 1
\&  $xml\->{root}{foo} = \*(Aqsimple value\*(Aq ;
.Ve
.PP
Here foo will be a normal argument/attribute value, and will generate this XML data:
.PP
.Vb 1
\&  <root foo="simple value"/>
.Ve
.PP
But if you insert some tag or lines in the values by default \fIXML::Smart\fR will convert it to a node content:
.PP
.Vb 1
\&  $xml\->{root}{foo} = "line0\enlien1\enline2\en" ;
.Ve
.PP
And will generate that XML data:
.PP
.Vb 6
\&  <root>
\&  <foo>line0
\&  lien1
\&  line2
\&  </foo>
\&  </root>
.Ve
.PP
But what you can do if you want to force some type, let's say, have a node content with a simple value:
.PP
.Vb 2
\&  $xml\->{root}{foo} = \*(Aqsimple value\*(Aq ;
\&  $xml\->{root}{foo}\->set_node(1) ;
.Ve
.PP
And will generate that XML data:
.PP
.Vb 3
\&  <root>
\&    <foo>simple value</foo>
\&  </root>
.Ve
.SS "Multiple contents:"
.IX Subsection "Multiple contents:"
When you have interpolated content/data you need to work in a different. Let's say that you load
this XML data:
.PP
.Vb 5
\&  <root>
\&  content0
\&  <tag1 arg="1"/>
\&  content1
\&  </root>
.Ve
.PP
If you access directly the root key as string you will get all the content parts grouped.
So, this code:
.PP
.Vb 7
\&  my $xml = new XML::Smart(q\`
\&  <root>
\&  content0
\&  <tag1 arg="1"/>
\&  content1
\&  </root>
\&  \`,\*(Aqsmart\*(Aq) ;
\&  
\&  print "#$xml\->{root}#" ;
.Ve
.PP
Will print that:
.PP
.Vb 2
\&  #
\&  content0
\&  
\&  content1
\&  #
.Ve
.PP
\&\fBTo access each part of the content independently you should use an array that receive the method \fR\f(BIcontent()\fR\fB:\fR
.PP
.Vb 1
\&  my @content = $xml\->{root}\->content ;
\&  
\&  print "#$content[0]#\en" ;
.Ve
.PP
And this will print that:
.PP
.Vb 3
\&  #
\&  content0
\&  #
.Ve
.PP
\&\fBNow to set the multiple content values you should use the method \fR\f(BIcontent()\fR\fB with 2 arguments:\fR
.PP
.Vb 1
\&  $xml\->{root}\->content(0,\*(Aqnew content\*(Aq) ;
.Ve
.PP
And now the XML data produced will be:
.PP
.Vb 3
\&  <root>new content<tag1 arg="1"/>
\&  content1
\&  </root>
.Ve
.PP
If you use the method \fR\f(BIcontent()\fR\fI\fR with only one argument it will remove all the multiple contents and will set
the new value in the place of the 1st content.
.SH "Setting the XML Parser."
.IX Header "Setting the XML Parser."
By defaul \fIXML::Smart\fR will use XML::Parser or XML::Smart::Parser (in this order of preference) to load a XML data.
.PP
To force or define by your self the parser you can use the 2nd argument option when creating a \fIXML::Smart\fR object:
.PP
.Vb 1
\&  my $xml = new XML::Smart( \*(Aqsome.xml\*(Aq , \*(AqXML::Parser\*(Aq ) ;
\&  
\&  ## and
\&  
\&  my $xml = new XML::Smart( \*(Aqsome.xml\*(Aq , \*(AqXML::Smart::Parser\*(Aq ) ;
.Ve
.PP
\&\fIXML::Smart\fR also has an extra parser, \fIXML::Smart::HTMLParser\fR, that can be used to load HTML as XML, or to load wild XML data:
.PP
.Vb 1
\&  my $xml = new XML::Smart( \*(Aqsome.xml\*(Aq , \*(AqXML::Smart::HTMLParser\*(Aq ) ;
.Ve
.PP
Aliases for the parser options:
.PP
.Vb 2
\&  SMART|REGEXP   => XML::Smart::Parser
\&  HTML           => XML::Smart::HTMLParser
.Ve
.PP
So, you can use as:
.PP
.Vb 2
\&  my $xml = new XML::Smart( \*(Aqsome.xml\*(Aq , \*(Aqsmart\*(Aq ) ;
\&  my $xml = new XML::Smart( \*(Aqsome.xml\*(Aq , \*(Aqhtml\*(Aq ) ;
.Ve
.SH "Customizing the Parser."
.IX Header "Customizing the Parser."
You can customize the way that the parser will treat the XML data:
.SS "Forcing nodes/tags and arguments/attributes to lowercase or upercase:"
.IX Subsection "Forcing nodes/tags and arguments/attributes to lowercase or upercase:"
.Vb 1
\&  ## For lower case:
\&
\&  my $xml = new XML::Smart( \*(Aqsome.xml\*(Aq ,
\&  lowtag => 1 ,
\&  lowarg => 1 ,
\&  ) ;
\&  
\&  ## For uper case:
\&  
\&  my $xml = new XML::Smart( \*(Aqsome.xml\*(Aq ,
\&  upertag => 1 ,
\&  uperarg => 1 ,
\&  ) ;
.Ve
.SS "Loading arguments without values (flags) as a TRUE boolean:"
.IX Subsection "Loading arguments without values (flags) as a TRUE boolean:"
\&\fI** Note, this option will work only when the XML is parsed by XML::Smart::HTMLParser, since only it accept arguments without values!\fR
.PP
.Vb 5
\&  my $xml = new XML::Smart(
\&  \*(Aq<root><foo arg1="" flag></root>\*(Aq ,
\&  \*(AqXML::Smart::HTMLParser\*(Aq ,
\&  arg_single => 1 ,
\&  ) ;
.Ve
.PP
Here's the tree of the example above:
.PP
.Vb 6
\&  \*(Aqroot\*(Aq => {
\&              \*(Aqfoo\*(Aq => {
\&                         \*(Aqflag\*(Aq => 1,
\&                         \*(Aqarg1\*(Aq => \*(Aq\*(Aq
\&                       },
\&            },
.Ve
.SS "Customizing the parse events:"
.IX Subsection "Customizing the parse events:"
\&\fIXML::Smart\fR can redirect the parsing process to personalized functions:
.PP
.Vb 5
\&  my $xml = XML::Smart\->new( \*(Aqsome.xml\*(Aq ,
\&  on_start => \e&on_start ,
\&  on_char  => \e&on_char ,
\&  on_end   => \e&on_end ,
\&  ) ;
\&  
\&  sub on_start {
\&    my ( $tag , $pointer , $pointer_back ) = @_ ;
\&    $pointer\->{$tag}{type_user} = 1 if $tag =~ /(?:name|age)/ ;
\&  }
\&
\&  sub on_char {
\&    my ( $tag , $pointer , $pointer_back , $content) = @_ ;
\&    $$content =~ s/\es+/ /gs ;
\&  }
\&  
\&  sub on_end {
\&    my ( $tag , $pointer , $pointer_back ) = @_ ;
\&    $pointer\->{$tag}{type_extra} = 1 if $tag =~ /(?:more|tel|address)/ ;
\&  }
.Ve
.SH AUTHOR
.IX Header "AUTHOR"
Graciliano M. P. <gm@virtuasites.com.br>
.PP
I will appreciate any type of feedback (include your opinions and/or suggestions). ;\-P
.PP
Enjoy and thanks for who are enjoying this tool and have sent e\-mails! ;\-P
.SH ePod
.IX Header "ePod"
This document was written in ePod (easy-POD), than converted to POD, and from here you know the way.