# xmerl_scan

### MODULE

xmerl_scan

### MODULE SUMMARY

This module is the interface to the XML parser, it handles XML 1.0.

### DESCRIPTION

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

### DATA TYPES

`global_state()`
  The global state of the scanner, represented by the #xmerl_scanner{} record.
`option_list()`
  Options allow to customize the behaviour of the scanner. See also tutorial on customization functions.
  Possible options are:
  `{acc_fun, Fun}`
    Call back function to accumulate contents of entity.
  `{continuation_fun, Fun} | {continuation_fun, Fun, ContinuationState}`
    Call back function to decide what to do if the scanner runs into EOF before the document is complete.
  `{event_fun, Fun} | {event_fun, Fun, EventState}`
    Call back function to handle scanner events.
  `{fetch_fun, Fun} | {fetch_fun, Fun, FetchState}`
    Call back function to fetch an external resource.
  `{hook_fun, Fun} | {hook_fun, Fun, HookState}`
    Call back function to process the document entities once identified.
  `{close_fun, Fun}`
    Called when document has been completely parsed.
  `{rules, ReadFun, WriteFun, RulesState} | {rules, Rules}`
    Handles storing of scanner information when parsing.
  `{user_state, UserState}`
    Global state variable accessible from all customization functions
  `{fetch_path, PathList}`
    PathList is a list of directories to search when fetching files. If the file in question is not in the fetch_path, the URI will be used as a file name.
  `{space, Flag}`
    'preserve' (default) to preserve spaces, 'normalize' to accumulate consecutive whitespace and replace it with one space.
  `{line, Line}`
    To specify starting line for scanning in document which contains fragments of XML.
  `{namespace_conformant, Flag}`
    Controls whether to behave as a namespace conformant XML parser, 'false' (default) to not otherwise 'true'.
  `{validation, Flag}`
    Controls whether to process as a validating XML parser: 'off' (default) no validation, or validation 'dtd' by DTD or 'schema' by XML Schema. 'false' and 'true' options are obsolete (i.e. they may be removed in a future release), if used 'false' equals 'off' and 'true' equals 'dtd'.
  `{schemaLocation, [{Namespace,Link}|...]}`
    Tells explicitly which XML Schema documents to use to validate the XML document. Used together with the `{validation,schema}` option.
  `{quiet, Flag}`
    Set to 'true' if xmerl should behave quietly and not output any information to standard output (default 'false').
  `{doctype_DTD, DTD}`
    Allows to specify DTD name when it isn't available in the XML document. This option has effect only together with `{validation,'dtd'` option.
  `{xmlbase, Dir}`
    XML Base directory. If using string/1 default is current directory. If using file/1 default is directory of given file.
  `{encoding, Enc}`
    Set default character set used (default UTF-8). This character set is used only if not explicitly given by the XML declaration.

### EXPORTS

`accumulate_whitespace(T::string(), S::global_state(), X3::atom(), Acc::string()) -> {Acc, T1, S1}`

Function to accumulate and normalize whitespace.

`cont_state(S::global_state()) -> global_state()`

Equivalent to cont_state(ContinuationState, S).

`cont_state(X::ContinuationState, S::global_state()) -> global_state()`

For controlling the ContinuationState, to be used in a continuation function, and called when the parser encounters the end of the byte stream. See tutorial on customization functions.

`event_state(S::global_state()) -> global_state()`

Equivalent to event_state(EventState, S).

`event_state(X::EventState, S::global_state()) -> global_state()`

For controlling the EventState, to be used in an event function, and called at the beginning and at the end of a parsed entity. See tutorial on customization functions.

`fetch_state(S::global_state()) -> global_state()`

Equivalent to fetch_state(FetchState, S).

`fetch_state(X::FetchState, S::global_state()) -> global_state()`

For controlling the FetchState, to be used in a fetch function, and called when the parser fetch an external resource (eg. a DTD). See tutorial on customization functions.

`file(Filename::string()) -> {xmlElement(), Rest}`

Types:

`Rest = list()`

Equivalent to file(Filename, []).

`file(Filename::string(), Options::option_list()) -> {xmlElement(), Rest}`

Types:

`Rest = list()`

Parse file containing an XML document

`hook_state(S::global_state()) -> global_state()`

Equivalent to hook_state(HookState, S).

`hook_state(X::HookState, S::global_state()) -> global_state()`

For controlling the HookState, to be used in a hook function, and called when the parser has parsed a complete entity. See tutorial on customization functions.

`rules_state(S::global_state()) -> global_state()`

Equivalent to rules_state(RulesState, S).

`rules_state(X::RulesState, S::global_state()) -> global_state()`

For controlling the RulesState, to be used in a rules function, and called when the parser store scanner information in a rules database. See tutorial on customization functions.

`string(Text::list()) -> {xmlElement(), Rest}`

Types:

`Rest = list()`

Equivalent to string(Test, []).

`string(Text::list(), Options::option_list()) -> {xmlElement(), Rest}`

Types:

`Rest = list()`

Parse string containing an XML document

`user_state(S::global_state()) -> global_state()`

Equivalent to user_state(UserState, S).

`user_state(X::UserState, S::global_state()) -> global_state()`

For controlling the UserState, to be used in a user function. See tutorial on customization functions.

### AUTHORS

- support@erlang.ericsson.se

xmerl 1.1
Copyright © 1991-2007 Ericsson AB