1
2
3=head1 NAME
4
5XML::Smart::FAQ - Frequently Asked Questions about XML::Smart.
6
7=head1 SYNOPSIS
8
9This is the Frequently Asked Questions list for XML::Smart.
10
11=head1 QUESTIONS
12
13B<For new questions send an e-mail to the author, but please, read first all the F.A.Q.>
14
15=head2 Do I need to install XML::Parser to can use XML::Smart?
16
17No! XML::Smart already comes with 2 independent parsers, XML::Smart::Parser and XML::Smart::HTMLParser.
18
19If L<XML::Parser> is found XML::Smart will use it by default, and the 2nd options will be XML::Smart::Parser.
20
21Note that for complex parsing L<XML::Parser> is recommended, but XML::Smart::Parser will work fine too.
22
23=head2 What is the best version of XML::Smart to install?
24
25Is always the last! Always take a look for new versions before aks for help on XML::Smart.
26
27Note that internally XML::Smart is complex, since the main idea of it is to remove the complexity from the hand of the programmer.
28Actually the idea is to enable the Perl programmer to use and create XML data without really know the XML format.
29
30=head2 Where can I learn about XML?
31
32http://www.xml.com
33
34=head2 How to apply a DTD to a XML::Smart object tree?
35
36Take a look in the method I<apply_dtd()>. Example of use:
37
38  $xml->apply_dtd(q`
39  <!DOCTYPE cds [
40  <!ELEMENT cds (album+)>
41  <!ATTLIST cds
42            creator  CDATA
43            date     CDATA #REQUIRED
44  >
45  <!ELEMENT album (artist , tracks+)>
46  <!ELEMENT artist (#PCDATA)>
47  <!ELEMENT tracks (#PCDATA)>
48  ]>
49  `);
50
51This will format automatically elements, attributes, etc...
52
53=head2 How XML::Smart works?
54
55To create I<XML::Smart>, first I have created the module L<Object::MultiType>.
56With it you can have an object that works at the same time as a HASH, ARRAY, SCALAR,
57CODE & GLOB. So you can do things like this with the same object:
58
59  $obj = Object::MultiType->new() ;
60
61  $obj->{key} ;
62  $obj->[0] ;
63  $obj->method ;
64
65  @l = @{$obj} ;
66  %h = %{$obj} ;
67
68  &$obj(args) ;
69
70  print $obj "send data\n" ;
71
72Seems to be crazy, and can be more if you use tie() inside it, and this is what I<XML::Smart> does.
73
74For I<XML::Smart>, the access in the Hash and Array way paste through tie(). In other words, you have a tied HASH
75and tied ARRAY inside it. This tied Hash and Array work together, soo B<you can access a Hash key
76as the index 0 of an Array, or access an index 0 as the Hash key>:
77
78  %hash = (
79  key => ['a','b','c']
80  ) ;
81
82  $hash->{key}    ## return $hash{key}[0]
83  $hash->{key}[0] ## return $hash{key}[0]
84  $hash->{key}[1] ## return $hash{key}[1]
85
86  ## Inverse:
87
88  %hash = ( key => 'a' ) ;
89
90  $hash->{key}    ## return $hash{key}
91  $hash->{key}[0] ## return $hash{key}
92  $hash->{key}[1] ## return undef
93
94The best thing of this new resource is to avoid wrong access to the data and warnings when you try to
95access a Hash having an Array (and the inverse). Thing that generally make the script die().
96
97Once having an easy access to the data, you can use the same resource to B<create> data!
98For example:
99
100  ## Previous data:
101  <hosts>
102    <server address="192.168.2.100" os="linux" type="conectiva" version="9.0"/>
103  </hosts>
104
105  ## Now you have {address} as a normal key with a string inside:
106  $XML->{hosts}{server}{address}
107
108  ## And to add a new address, the key {address} need to be an ARRAY ref!
109  ## So, XML::Smart make the convertion: ;-P
110  $XML->{hosts}{server}{address}[1] = '192.168.2.101' ;
111
112  ## Adding to a list that you don't know the size:
113  push(@{$XML->{hosts}{server}{address}} , '192.168.2.102') ;
114
115  ## The data now:
116  <hosts>
117    <server os="linux" type="conectiva" version="9.0"/>
118      <address>192.168.2.100</address>
119      <address>192.168.2.101</address>
120      <address>192.168.2.102</address>
121    </server>
122  </hosts>
123
124Than after changing your XML tree using the Hash and Array resources you just
125get the data remade (through the Hash tree inside the object):
126
127  my $xmldata = $XML->data ;
128
129B<But note that I<XML::Smart> always return an object>! Even when you get a final
130key. So this actually returns another object, pointhing (inside it) to the key:
131
132  $addr = $XML->{hosts}{server}{address}[0] ;
133
134  ## Since $addr is an object you can TRY to access more data:
135  $addr->{foo}{bar} ; ## This doens't make warnings! just return UNDEF.
136
137  ## But you can use it like a normal SCALAR too:
138
139  print "$addr\n" ;
140
141  $addr .= ':80' ; ## After this $addr isn't an object any more, just a SCALAR!
142
143=head2 When I generate the XML data new lines (\n) are added to the content!
144
145You should use the options for the method data() and save() to not add identation to the generated data:
146
147  $XML->data( noident => 1 ) ;
148
149  ## or better:
150
151  $XML->data( nospace => 1 ) ;
152
153=head2 Your question is not here?
154
155Just send me an e-mail. ;-P
156
157=head1 AUTHOR
158
159Graciliano M. P. <gm@virtuasites.com.br>
160
161I will appreciate any type of feedback (include your opinions and/or suggestions). ;-P
162
163Enjoy and thanks for who are enjoying this tool and have sent e-mails! ;-P
164
165=head1 ePod
166
167This document was written in L<ePod> (easy-POD), than converted to POD, and from here you know the way.
168
169=cut
170
171