.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "XML::Smart::FAQ 3pm"
.TH XML::Smart::FAQ 3pm "2004-12-08" "perl v5.20.1" "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::FAQ \- Frequently Asked Questions about XML::Smart.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
This is the Frequently Asked Questions list for XML::Smart.
.SH "QUESTIONS"
.IX Header "QUESTIONS"
\&\fBFor new questions send an e\-mail to the author, but please, read first all the F.A.Q.\fR
.SS "Do I need to install XML::Parser to can use XML::Smart?"
.IX Subsection "Do I need to install XML::Parser to can use XML::Smart?"
No! XML::Smart already comes with 2 independent parsers, XML::Smart::Parser and XML::Smart::HTMLParser.
.PP
If XML::Parser is found XML::Smart will use it by default, and the 2nd options will be XML::Smart::Parser.
.PP
Note that for complex parsing XML::Parser is recommended, but XML::Smart::Parser will work fine too.
.SS "What is the best version of XML::Smart to install?"
.IX Subsection "What is the best version of XML::Smart to install?"
Is always the last! Always take a look for new versions before aks for help on XML::Smart.
.PP
Note that internally XML::Smart is complex, since the main idea of it is to remove the complexity from the hand of the programmer.
Actually the idea is to enable the Perl programmer to use and create \s-1XML\s0 data without really know the \s-1XML\s0 format.
.SS "Where can I learn about \s-1XML\s0?"
.IX Subsection "Where can I learn about XML?"
http://www.xml.com
.SS "How to apply a \s-1DTD\s0 to a XML::Smart object tree?"
.IX Subsection "How to apply a DTD to a XML::Smart object tree?"
Take a look in the method \fI\fIapply_dtd()\fI\fR. Example of use:
.PP
.Vb 12
\&  $xml\->apply_dtd(q\`
\&  <!DOCTYPE cds [
\&  <!ELEMENT cds (album+)>
\&  <!ATTLIST cds
\&            creator  CDATA
\&            date     CDATA #REQUIRED
\&  >
\&  <!ELEMENT album (artist , tracks+)>
\&  <!ELEMENT artist (#PCDATA)>
\&  <!ELEMENT tracks (#PCDATA)>
\&  ]>
\&  \`);
.Ve
.PP
This will format automatically elements, attributes, etc...
.SS "How XML::Smart works?"
.IX Subsection "How XML::Smart works?"
To create \fIXML::Smart\fR, first I have created the module Object::MultiType.
With it you can have an object that works at the same time as a \s-1HASH, ARRAY, SCALAR,
CODE & GLOB.\s0 So you can do things like this with the same object:
.PP
.Vb 1
\&  $obj = Object::MultiType\->new() ;
\&  
\&  $obj\->{key} ;
\&  $obj\->[0] ;
\&  $obj\->method ;
\&  
\&  @l = @{$obj} ;
\&  %h = %{$obj} ;
\&  
\&  &$obj(args) ;
\&  
\&  print $obj "send data\en" ;
.Ve
.PP
Seems to be crazy, and can be more if you use \fItie()\fR inside it, and this is what \fIXML::Smart\fR does.
.PP
For \fIXML::Smart\fR, the access in the Hash and Array way paste through \fItie()\fR. In other words, you have a tied \s-1HASH\s0
and tied \s-1ARRAY\s0 inside it. This tied Hash and Array work together, soo \fByou can access a Hash key
as the index 0 of an Array, or access an index 0 as the Hash key\fR:
.PP
.Vb 3
\&  %hash = (
\&  key => [\*(Aqa\*(Aq,\*(Aqb\*(Aq,\*(Aqc\*(Aq]
\&  ) ;
\&  
\&  $hash\->{key}    ## return $hash{key}[0]
\&  $hash\->{key}[0] ## return $hash{key}[0]
\&  $hash\->{key}[1] ## return $hash{key}[1]
\&  
\&  ## Inverse:
\&  
\&  %hash = ( key => \*(Aqa\*(Aq ) ;
\&  
\&  $hash\->{key}    ## return $hash{key}
\&  $hash\->{key}[0] ## return $hash{key}
\&  $hash\->{key}[1] ## return undef
.Ve
.PP
The best thing of this new resource is to avoid wrong access to the data and warnings when you try to
access a Hash having an Array (and the inverse). Thing that generally make the script \fIdie()\fR.
.PP
Once having an easy access to the data, you can use the same resource to \fBcreate\fR data!
For example:
.PP
.Vb 4
\&  ## Previous data:
\&  <hosts>
\&    <server address="192.168.2.100" os="linux" type="conectiva" version="9.0"/>
\&  </hosts>
\&  
\&  ## Now you have {address} as a normal key with a string inside:
\&  $XML\->{hosts}{server}{address}
\&  
\&  ## And to add a new address, the key {address} need to be an ARRAY ref!
\&  ## So, XML::Smart make the convertion: ;\-P
\&  $XML\->{hosts}{server}{address}[1] = \*(Aq192.168.2.101\*(Aq ;
\&  
\&  ## Adding to a list that you don\*(Aqt know the size:
\&  push(@{$XML\->{hosts}{server}{address}} , \*(Aq192.168.2.102\*(Aq) ;
\&  
\&  ## The data now:
\&  <hosts>
\&    <server os="linux" type="conectiva" version="9.0"/>
\&      <address>192.168.2.100</address>
\&      <address>192.168.2.101</address>
\&      <address>192.168.2.102</address>
\&    </server>
\&  </hosts>
.Ve
.PP
Than after changing your \s-1XML\s0 tree using the Hash and Array resources you just
get the data remade (through the Hash tree inside the object):
.PP
.Vb 1
\&  my $xmldata = $XML\->data ;
.Ve
.PP
\&\fBBut note that \f(BIXML::Smart\fB always return an object\fR! Even when you get a final
key. So this actually returns another object, pointhing (inside it) to the key:
.PP
.Vb 1
\&  $addr = $XML\->{hosts}{server}{address}[0] ;
\&  
\&  ## Since $addr is an object you can TRY to access more data:
\&  $addr\->{foo}{bar} ; ## This doens\*(Aqt make warnings! just return UNDEF.
\&
\&  ## But you can use it like a normal SCALAR too:
\&
\&  print "$addr\en" ;
\&
\&  $addr .= \*(Aq:80\*(Aq ; ## After this $addr isn\*(Aqt an object any more, just a SCALAR!
.Ve
.SS "When I generate the \s-1XML\s0 data new lines (\en) are added to the content!"
.IX Subsection "When I generate the XML data new lines (n) are added to the content!"
You should use the options for the method \fIdata()\fR and \fIsave()\fR to not add identation to the generated data:
.PP
.Vb 1
\&  $XML\->data( noident => 1 ) ;
\&
\&  ## or better:
\&
\&  $XML\->data( nospace => 1 ) ;
.Ve
.SS "Your question is not here?"
.IX Subsection "Your question is not here?"
Just send me an e\-mail. ;\-P
.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 \s-1POD,\s0 and from here you know the way.