1xmerl_scan(3)              Erlang Module Definition              xmerl_scan(3)
2
3
4

NAME

6       xmerl_scan - This module is the interface to the XML parser, it handles
7       XML 1.0.
8

DESCRIPTION

10       This module is the interface to the XML parser, it handles XML 1.0. The
11       XML    parser   is   activated   through   xmerl_scan:string/[1,2]   or
12       xmerl_scan:file/[1,2]. It  returns  records  of  the  type  defined  in
13       xmerl.hrl. See also tutorial on customization functions.
14

DATA TYPES

16         document() = xmlElement() | xmlDocument():
17
18
19           The    document    returned    by    xmerl_scan:string/[1,2]    and
20           xmerl_scan:file/[1,2]. The type of the returned record  depends  on
21           the value of the document option passed to the function.
22
23         global_state():
24
25
26           The  global  state  of the scanner, represented by the #xmerl_scan‐
27           ner{} record.
28
29         option_list():
30
31
32           Options allow to customize the behaviour of the scanner.  See  also
33           tutorial on customization functions.
34
35           Possible options are:
36
37           {acc_fun, Fun}:
38             Call back function to accumulate contents of entity.
39
40           {continuation_fun,  Fun}  |  {continuation_fun,  Fun, Continuation‐
41           State}:
42             Call back function to decide what to do if the scanner runs  into
43             EOF before the document is complete.
44
45           {event_fun, Fun} | {event_fun, Fun, EventState}:
46             Call back function to handle scanner events.
47
48           {fetch_fun, Fun} | {fetch_fun, Fun, FetchState}:
49             Call back function to fetch an external resource.
50
51           {hook_fun, Fun} | {hook_fun, Fun, HookState}:
52             Call  back function to process the document entities once identi‐
53             fied.
54
55           {close_fun, Fun}:
56             Called when document has been completely parsed.
57
58           {rules, ReadFun, WriteFun, RulesState} | {rules, Rules}:
59             Handles storing of scanner information when parsing.
60
61           {user_state, UserState}:
62             Global state variable accessible from all customization functions
63
64           {fetch_path, PathList}:
65             PathList is a list of directories to search when fetching  files.
66             If the file in question is not in the fetch_path, the URI will be
67             used as a file name.
68
69           {space, Flag}:
70             'preserve' (default) to preserve spaces, 'normalize'  to  accumu‐
71             late consecutive whitespace and replace it with one space.
72
73           {line, Line}:
74             To  specify starting line for scanning in document which contains
75             fragments of XML.
76
77           {namespace_conformant, Flag}:
78             Controls whether to behave as a namespace conformant XML  parser,
79             'false' (default) to not otherwise 'true'.
80
81           {validation, Flag}:
82             Controls  whether  to  process  as a validating XML parser: 'off'
83             (default) no validation, or validation 'dtd' by DTD  or  'schema'
84             by XML Schema. 'false' and 'true' options are obsolete (i.e. they
85             may be removed in a future release), if used 'false' equals 'off'
86             and 'true' equals 'dtd'.
87
88           {schemaLocation, [{Namespace,Link}|...]}:
89             Tells  explicitly  which  XML Schema documents to use to validate
90             the XML document.  Used  together  with  the  {validation,schema}
91             option.
92
93           {quiet, Flag}:
94             Set  to  'true' if xmerl should behave quietly and not output any
95             information to standard output (default 'false').
96
97           {doctype_DTD, DTD}:
98             Allows to specify DTD name when it isn't  available  in  the  XML
99             document.  This  option  has  effect  only together with {valida‐
100             tion,'dtd' option.
101
102           {xmlbase, Dir}:
103             XML Base directory. If using string/1 default is  current  direc‐
104             tory. If using file/1 default is directory of given file.
105
106           {encoding, Enc}:
107             Set  default  character  set used (default UTF-8). This character
108             set is used only if not explicitly given by the XML declaration.
109
110           {document, Flag}:
111             Set to 'true' if xmerl should return a complete XML  document  as
112             an xmlDocument record (default 'false').
113
114           {comments, Flag}:
115             Set  to 'false' if xmerl should skip comments otherwise they will
116             be returned as xmlComment records (default 'true').
117
118           {default_attrs, Flag}:
119             Set to 'true' if xmerl should add to elements missing  attributes
120             with a defined default value (default 'false').
121
122         xmlDocument() = #xmlDocument{}:
123
124
125           The record definition is found in xmerl.hrl.
126
127         xmlElement() = #xmlElement{}:
128
129
130           The record definition is found in xmerl.hrl.
131

EXPORTS

133       accumulate_whitespace(T::string(),    S::global_state(),    X3::atom(),
134       Acc::string()) -> {Acc, T1, S1}
135
136              Function to accumulate and normalize whitespace.
137
138       cont_state(S::global_state()) -> global_state()
139
140              Equivalent to cont_state(ContinuationState, S).
141
142       cont_state(X::ContinuationState, S::global_state()) -> global_state()
143
144              For controlling the ContinuationState, to be used in a continua‐
145              tion  function, and called when the parser encounters the end of
146              the byte stream. See tutorial on customization functions.
147
148       event_state(S::global_state()) -> global_state()
149
150              Equivalent to event_state(EventState, S).
151
152       event_state(X::EventState, S::global_state()) -> global_state()
153
154              For controlling the EventState, to be used in an event function,
155              and  called  at the beginning and at the end of a parsed entity.
156              See tutorial on customization functions.
157
158       fetch_state(S::global_state()) -> global_state()
159
160              Equivalent to fetch_state(FetchState, S).
161
162       fetch_state(X::FetchState, S::global_state()) -> global_state()
163
164              For controlling the FetchState, to be used in a fetch  function,
165              and  called  when  the  parser fetch an external resource (eg. a
166              DTD). See tutorial on customization functions.
167
168       file(Filename::string()) -> {xmlElement(), Rest}
169
170              Types:
171
172                 Rest = list()
173
174              Equivalent to file(Filename, []).
175
176       file(Filename::string(), Options::option_list()) -> {document(), Rest}
177
178              Types:
179
180                 Rest = list()
181
182              Parse file containing an XML document
183
184       hook_state(S::global_state()) -> global_state()
185
186              Equivalent to hook_state(HookState, S).
187
188       hook_state(X::HookState, S::global_state()) -> global_state()
189
190              For controlling the HookState, to be used in  a  hook  function,
191              and  called  when  the  parser has parsed a complete entity. See
192              tutorial on customization functions.
193
194       rules_state(S::global_state()) -> global_state()
195
196              Equivalent to rules_state(RulesState, S).
197
198       rules_state(X::RulesState, S::global_state()) -> global_state()
199
200              For controlling the RulesState, to be used in a rules  function,
201              and  called when the parser store scanner information in a rules
202              database. See tutorial on customization functions.
203
204       string(Text::list()) -> {xmlElement(), Rest}
205
206              Types:
207
208                 Rest = list()
209
210              Equivalent to string(Text, []).
211
212       string(Text::list(), Options::option_list()) -> {document(), Rest}
213
214              Types:
215
216                 Rest = list()
217
218              Parse string containing an XML document
219
220       user_state(S::global_state()) -> global_state()
221
222              Equivalent to user_state(UserState, S).
223
224       user_state(X::UserState, S::global_state()) -> global_state()
225
226              For controlling the UserState, to be used in  a  user  function.
227              See tutorial on customization functions.
228

AUTHORS

230       <>
231
232
233
234                                 xmerl 1.3.24                    xmerl_scan(3)