NAME

       xmerl_scan - 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

         document() = xmlElement() | xmlDocument():

           The  document  returned by xmerl_scan:string/[1,2] and xmerl_scan:file/[1,2]. The type
           of the returned record depends on the value of  the  document  option  passed  to  the
           function.

         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.

           {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').

         xmlDocument() = #xmlDocument{}:

           The record definition is found in xmerl.hrl.

         xmlElement() = #xmlElement{}:

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()) -> {document(), 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(Text, []).

       string(Text::list(), Options::option_list()) -> {document(), 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

       <>

                                           xmerl 1.3.30                          xmerl_scan(3erl)