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

           {allow_entities, Flag}:
             Set  to 'false' if xmerl_scan should fail when there is an ENTITY declaration in the
             XML document (default 'true').

         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.31.1                         xmerl_scan(3erl)