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}  op‐
91             tion.
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

EXPORTS

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

AUTHORS

228       <>
229
230
231
232                                 xmerl 1.3.28                    xmerl_scan(3)