Search documentation of xmerl

# xmerl_eventp (xmerl v2.2)

Copy Markdown View Source

Simple event-based processors (front-ends to `xmerl_scan`).

Implements processing XML documents in streams for parsing in SAX style.

Each front-end contains more elaborate settings of `xmerl_scan` that makes usage of the customization functions.

## Summary

### Types

option_list()

Options allow to customize the behaviour of the scanner. See also the "Customization functions" tutorial.

xmlElement()

Record `#xmlElement{}`

### Functions

file_sax(Fname, CallBackModule, UserState, Options)

Parse file containing an XML document, SAX style.

stream(Fname, Options)

Parse file containing an XML document as a stream, DOM style.

stream_sax(Fname, CallBackModule, UserState, Options)

Parse file containing an XML document as a stream, SAX style.

string_sax(String, CallBackModule, UserState, Options)

Parse file containing an XML document, SAX style.

## Types

# option_list()

(not exported)

    -type option_list() :: [{atom(), term()} | {atom(), fun(), term()} | {atom(), fun(), fun(), term()}].

Options allow to customize the behaviour of the scanner. See also the "Customization functions" tutorial.

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.
- `{document, Flag}` - Set to `true` if Xmerl should return a complete XML document as an xmlDocument record (default `false`).
- `{comments, Flag}` - Set to `false` if Xmerl should skip comments otherwise they will be returned as xmlComment records (default `true`).
- `{default_attrs, Flag}` - Set to `true` if Xmerl should add to elements missing attributes with a defined default value (default `false`).

# xmlElement()

(not exported)

    -type xmlElement() ::
              #xmlElement{name :: term(),
                          expanded_name :: term(),
                          nsinfo :: term(),
                          namespace :: term(),
                          parents :: term(),
                          pos :: term(),
                          attributes :: term(),
                          content :: term(),
                          language :: term(),
                          xmlbase :: term(),
                          elementdef :: term()}.

Record `#xmlElement{}`

## Functions

# file_sax(Fname, CallBackModule, UserState, Options)

    -spec file_sax(Fname, CallBackModule, UserState, Options) -> NewUserState
                      when
                          Fname :: string(),
                          CallBackModule :: module(),
                          UserState :: term(),
                          Options :: option_list(),
                          NewUserState :: term().

Parse file containing an XML document, SAX style.

Wrapper for a call to the XML parser `xmerl_scan` with a `hook_fun` for using Xmerl export functionality directly after an entity is parsed.

# stream(Fname, Options)

    -spec stream(Fname, Options) -> {xmlElement(), list()} | {error, Reason}
                    when Fname :: string(), Options :: option_list(), Reason :: term().

Parse file containing an XML document as a stream, DOM style.

Wrapper for a call to the XML parser `xmerl_scan` with a `continuation_fun` for handling streams of XML data. Note that the `continuation_fun`, `acc_fun`, `fetch_fun`, `rules` and `close_fun` options cannot be user defined using this parser.

# stream_sax(Fname, CallBackModule, UserState, Options)

    -spec stream_sax(Fname, CallBackModule, UserState, Options) ->
                        {xmerl_scan:document(), Rest} | {error, Reason}
                        when
                            Fname :: string(),
                            CallBackModule :: module(),
                            UserState :: term(),
                            Options :: option_list(),
                            Rest :: string(),
                            Reason :: term().

Parse file containing an XML document as a stream, SAX style.

Wrapper for a call to the XML parser `xmerl_scan` with a `continuation_fun` for handling streams of XML data. Note that the `continuation_fun`, `acc_fun`, `fetch_fun`, `rules`, `hook_fun`, `close_fun` and `user_state` options cannot be user defined using this parser.

# string_sax(String, CallBackModule, UserState, Options)

    -spec string_sax(String, CallBackModule, UserState, Options) ->
                        {xmerl_scan:document(), Rest} | {error, Reason}
                        when
                            String :: list(),
                            CallBackModule :: module(),
                            UserState :: term(),
                            Options :: option_list(),
                            Rest :: string(),
                            Reason :: term().

Parse file containing an XML document, SAX style.

Wrapper for a call to the XML parser `xmerl_scan` with a `hook_fun` for using Xmerl export functionality directly after an entity is parsed.