xmlStructuredStop            package:XML            R Documentation

_C_o_n_d_i_t_i_o_n/_e_r_r_o_r _h_a_n_d_l_e_r _f_u_n_c_t_i_o_n_s _f_o_r _X_M_L _p_a_r_s_i_n_g

_D_e_s_c_r_i_p_t_i_o_n:

     These functions provide basic error handling for the XML parser in
     R. They also illustrate the basics which will allow others to
     provide customized error handlers that make more use of the
     information provided in each error reported.

     The 'xmlStructuredStop' function provides a simple R-level handler
     for errors raised by the XML parser. It collects the information
     provided by the XML parser and raises an R error. This is only
     used if 'NULL' is specified for the 'error' argument of
     'xmlTreeParse', 'xmlTreeParse' and 'htmlTreeParse'.

     The default is to use the function returned by a call to 
     'xmlErrorCumulator' as the error handler. This, as the name
     suggests, cumulates errors. The idea is to catch each error and
     let the parser continue and then report them all. As each error is
     encountered, it is collected by the function. If 'immediate' is
     'TRUE', the error is also reported on the console. When the
     parsing is complete and has failed, this function is invoked again
     with a zero-length character vector as the  message (first
     argument) and then it raises an error. This function will then
     raise an R condition of class 'class'.

_U_s_a_g_e:

     xmlStructuredStop(msg, code, domain, line, col, level, filename, 
                         class = "XMLError") 
     xmlErrorCumulator(class = "XMLParserErrorList", immediate = TRUE)

_A_r_g_u_m_e_n_t_s:

     msg: character string, the text of the message being reported

    code: an integer code giving an identifier for the error (see
          xmlerror.h) for the moment,

  domain: an integer domain indicating in which "module" or part of the
          parsing the error occurred, e.g. name space, parser, tree,
          xinclude, etc.

    line: an integer giving the line number in the XML content being
          processed corresponding to the error,  

     col: an integer giving the column position of the error,  

   level: an integer giving the severity of the error ranging from 1 to
          3 in increasing severity (warning, error, fatal),

filename: character string,   the name of the document being processed,
          i.e. its file name or URL.

   class: character vector,  any classes to prepend to the class
          attribute to make the error/condition. These are prepended to
          those returned via 'simpleError'.

immediate: logical value,  if  'TRUE' errors are displayed on the R
          console as they are encountered. Otherwise, the errors are
          collected and displayed at the end of the XML parsing.

_V_a_l_u_e:

     This calls 'stop' and so does not return a value.

_A_u_t_h_o_r(_s):

     Duncan Temple Lang

_R_e_f_e_r_e_n_c_e_s:

     libxml2 and its error handling facilities (<URL:
     http://xmlsoft.org>

_S_e_e _A_l_s_o:

     'xmlTreeParse' 'xmlInternalTreeParse' 'htmlTreeParse'

_E_x_a_m_p_l_e_s:

       tryCatch( xmlTreeParse("<a><b></a>", asText = TRUE, error = NULL),
                      XMLError = function(e) {
                         cat("There was an error in the XML at line", 
                               e$line, "column", e$col, "\n",
                              e$message, "\n")
                     })

