class Nokogiri::XML::SAX::ParserContext - nokogiri-1.18.10 Documentation

# class Nokogiri::XML::SAX::ParserContext

Context object to invoke the `XML` `SAX` parser on the `SAX::Document` handler.

💡 This class is usually not instantiated by the user. Use `Nokogiri::XML::SAX::Parser` instead.

### Public Class Methods

file(path) click to toggle source
file(path, encoding)

Create a parser context for the file at `path`.

Parameters

- `path` (String) The path to the input file

- `encoding` (optional) (Encoding, String) The `Encoding` to use, or the name of an encoding to use (default `nil`, encoding will be autodetected)

Returns

  `Nokogiri::XML::SAX::ParserContext`

💡 Calling this method directly is discouraged. Use `Nokogiri::XML::SAX::Parser.parse_file` which is more convenient for most use cases.

    # File lib/nokogiri/xml/sax/parser_context.rb, line 97
    def file(input, encoding = nil)
      native_file(input, resolve_encoding(encoding))
    end

io(input) click to toggle source
io(input, encoding)

Create a parser context for an `input` IO which will assume `encoding`

Parameters

- `io` (IO) The readable IO object from which to read input

- `encoding` (optional) (Encoding) The `Encoding` to use, or the name of an encoding to use (default `nil`, encoding will be autodetected)

Returns

  `Nokogiri::XML::SAX::ParserContext`

💡 Calling this method directly is discouraged. Use `Nokogiri::XML::SAX::Parser` parse methods which are more convenient for most use cases.

    # File lib/nokogiri/xml/sax/parser_context.rb, line 56
    def io(input, encoding = nil)
      native_io(input, resolve_encoding(encoding))
    end

memory(input) click to toggle source
memory(input, encoding)

Create a parser context for the `input` String.

Parameters

- `input` (String) The input string to be parsed.

- `encoding` (optional) (Encoding, String) The `Encoding` to use, or the name of an encoding to use (default `nil`, encoding will be autodetected)

Returns

  `Nokogiri::XML::SAX::ParserContext`

💡 Calling this method directly is discouraged. Use `Nokogiri::XML::SAX::Parser` parse methods which are more convenient for most use cases.

    # File lib/nokogiri/xml/sax/parser_context.rb, line 77
    def memory(input, encoding = nil)
      native_memory(input, resolve_encoding(encoding))
    end

new(input) click to toggle source
new(input, encoding)

Create a parser context for an IO or a String. This is a shorthand method for `ParserContext.io` and `ParserContext.memory`.

Parameters

- `input` (IO, String) A String or a readable IO object

- `encoding` (optional) (Encoding) The `Encoding` to use, or the name of an encoding to use (default `nil`, encoding will be autodetected)

If `input` quacks like a readable IO object, this method forwards to `ParserContext.io`, otherwise it forwards to `ParserContext.memory`.

Returns

  `Nokogiri::XML::SAX::ParserContext`

    # File lib/nokogiri/xml/sax/parser_context.rb, line 31
    def new(input, encoding = nil)
      if [:read, :close].all? { |x| input.respond_to?(x) }
        io(input, encoding)
      else
        memory(input, encoding)
      end
    end

### Private Class Methods

resolve_encoding(encoding) click to toggle source

    # File lib/nokogiri/xml/sax/parser_context.rb, line 101
            def resolve_encoding(encoding)
      case encoding
      when Encoding
        encoding

      when nil
        nil # totally fine, parser will guess encoding

      when Integer
        warn("Passing an integer to Nokogiri::XML::SAX::ParserContext.io is deprecated. Use an Encoding object instead. This will become an error in a future release.", uplevel: 2, category: :deprecated)

        return nil if encoding == Parser::ENCODINGS["NONE"]

        encoding = Parser::REVERSE_ENCODINGS[encoding]
        raise ArgumentError, "Invalid libxml2 encoding id #{encoding}" if encoding.nil?
        Encoding.find(encoding)

      when String
        Encoding.find(encoding)

      else
        raise ArgumentError, "Cannot resolve #{encoding.inspect} to an Encoding"
      end
    end

### Public Instance Methods

column click to toggle source

Returns

  (Integer) the column number of the column being currently parsed.

    static VALUE
    noko_xml_sax_parser_context__column(VALUE rb_context)
    {
      xmlParserCtxtPtr ctxt = noko_xml_sax_parser_context_unwrap(rb_context);
      xmlParserInputPtr io;

      io = ctxt->input;
      if (io) {
        return INT2NUM(io->col);
      }

      return Qnil;
    }

line click to toggle source

Returns

  (Integer) the line number of the line being currently parsed.

    static VALUE
    noko_xml_sax_parser_context__line(VALUE rb_context)
    {
      xmlParserInputPtr io;
      xmlParserCtxtPtr ctxt = noko_xml_sax_parser_context_unwrap(rb_context);

      io = ctxt->input;
      if (io) {
        return INT2NUM(io->line);
      }

      return Qnil;
    }

parse_with(sax_handler) click to toggle source

Use `sax_handler` and parse the current document

💡 Calling this method directly is discouraged. Use `Nokogiri::XML::SAX::Parser` methods which are more convenient for most use cases.

    static VALUE
    noko_xml_sax_parser_context__parse_with(VALUE rb_context, VALUE rb_sax_parser)
    {
      xmlParserCtxtPtr c_context;
      xmlSAXHandlerPtr sax;

      if (!rb_obj_is_kind_of(rb_sax_parser, cNokogiriXmlSaxParser)) {
        rb_raise(rb_eArgError, "argument must be a Nokogiri::XML::SAX::Parser");
      }

      c_context = noko_xml_sax_parser_context_unwrap(rb_context);
      sax = noko_xml_sax_parser_unwrap(rb_sax_parser);

      c_context->sax = sax;
      c_context->userData = c_context; /* so we can use libxml2/SAX2.c handlers if we want to */
      c_context->_private = (void *)rb_sax_parser;

      xmlSetStructuredErrorFunc(NULL, NULL);

      /* although we're calling back into Ruby here, we don't need to worry about exceptions, because we
       * don't have any cleanup to do. The only memory we need to free is handled by
       * xml_sax_parser_context_type_free */
      xmlParseDocument(c_context);

      return Qnil;
    }

recovery click to toggle source

Inspect whether this parser will recover from parsing errors. If set to `true`, the parser will invoke the `SAX::Document#error` callback and continue processing the file. If set to `false`, the parser will stop processing the file on the first parsing error.

Returns

  (Boolean) Whether this parser will recover from parsing errors.

Default is `false` for `XML` and `true` for `HTML`.

    static VALUE
    noko_xml_sax_parser_context__recovery_get(VALUE rb_context)
    {
      xmlParserCtxtPtr ctxt = noko_xml_sax_parser_context_unwrap(rb_context);

      if (xmlCtxtGetOptions(ctxt) & XML_PARSE_RECOVER) {
        return Qtrue;
      } else {
        return Qfalse;
      }
    }

recovery=(value) click to toggle source

Controls whether this parser will recover from parsing errors. If set to `true`, the parser will invoke the `SAX::Document#error` callback and continue processing the file. If set to `false`, the parser will stop processing the file on the first parsing error.

Parameters

- `value` (Boolean) Recover from parsing errors. (Default is `false` for `XML` and `true` for `HTML`.)

Returns

  (Boolean) The passed `value`.

Example

  Because this class is generally not instantiated directly, you would typically set this option via the block argument to `Nokogiri::XML::SAX::Parser.parse` et al:

      parser = Nokogiri::XML::SAX::Parser.new(document_handler)
      parser.parse(xml) do |ctx|
        ctx.recovery = true
      end

    static VALUE
    noko_xml_sax_parser_context__recovery_set(VALUE rb_context, VALUE rb_value)
    {
      int error;
      xmlParserCtxtPtr ctxt = noko_xml_sax_parser_context_unwrap(rb_context);

      if (RB_TEST(rb_value)) {
        error = xmlCtxtSetOptions(ctxt, xmlCtxtGetOptions(ctxt) | XML_PARSE_RECOVER);
      } else {
        error = xmlCtxtSetOptions(ctxt, xmlCtxtGetOptions(ctxt) & ~XML_PARSE_RECOVER);
      }

      if (error) {
        rb_raise(rb_eRuntimeError, "failed to set parser context options (%x)", error);
      }

      return rb_value;
    }

replace_entities click to toggle source

See Entity Handling at `Document` for an explanation of the behavior controlled by this flag.

Returns

  (Boolean) Value of the parse option. (Default `false`)

This option is perhaps misnamed by the libxml2 author, since it controls resolution and not replacement.

    static VALUE
    noko_xml_sax_parser_context__replace_entities_get(VALUE rb_context)
    {
      xmlParserCtxtPtr ctxt = noko_xml_sax_parser_context_unwrap(rb_context);

      if (xmlCtxtGetOptions(ctxt) & XML_PARSE_NOENT) {
        return Qtrue;
      } else {
        return Qfalse;
      }
    }

replace_entities=(value) click to toggle source

See Entity Handling at `Document` for an explanation of the behavior controlled by this flag.

Parameters

- `value` (Boolean) Whether external parsed entities will be resolved.

⚠ It is UNSAFE to set this option to `true` when parsing untrusted documents. The option defaults to `false` for this reason.

This option is perhaps misnamed by the libxml2 author, since it controls resolution and not replacement.

Example

  Because this class is generally not instantiated directly, you would typically set this option via the block argument to `Nokogiri::XML::SAX::Parser.parse` et al:

      parser = Nokogiri::XML::SAX::Parser.new(document_handler)
      parser.parse(xml) do |ctx|
        ctx.replace_entities = true # this is UNSAFE for untrusted documents!
      end

    static VALUE
    noko_xml_sax_parser_context__replace_entities_set(VALUE rb_context, VALUE rb_value)
    {
      int error;
      xmlParserCtxtPtr ctxt = noko_xml_sax_parser_context_unwrap(rb_context);

      if (RB_TEST(rb_value)) {
        error = xmlCtxtSetOptions(ctxt, xmlCtxtGetOptions(ctxt) | XML_PARSE_NOENT);
      } else {
        error = xmlCtxtSetOptions(ctxt, xmlCtxtGetOptions(ctxt) & ~XML_PARSE_NOENT);
      }

      if (error) {
        rb_raise(rb_eRuntimeError, "failed to set parser context options (%x)", error);
      }

      return rb_value;
    }