Skip to content

Commit

Permalink
XML::RelaxNG argument forwarding (#3342)
Browse files Browse the repository at this point in the history
**What problem is this PR intended to solve?**
#3323

**Have you included adequate test coverage?**
No test changes

**Does this change affect the behavior of either the C or the Java
implementations?**
No
  • Loading branch information
flavorjones authored Dec 6, 2024
2 parents f7a8a35 + 76bfa34 commit 3100afb
Show file tree
Hide file tree
Showing 3 changed files with 66 additions and 73 deletions.
51 changes: 31 additions & 20 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -344,14 +344,22 @@ Some guidelines (see [lib/nokogiri/xml/node.rb](lib/nokogiri/xml/node.rb) and [e
- name all the aliases of a method
- indicate block/yield usage of a method
- Briefly explain the purpose of the method, what it returns, and what side effects it has
- Use a `[Parameters]` definition to note the expected types of all the parameters as a bulleted list
- Use a `[Returns]` definition to note the return type
- Use a `[Yields]` definition to note the block parameters
- Use a `` character to warn the user about tricky usage
- Use a `💡` character to call attention to important notes
- `See also:` should be used to call out related methods
- `Since` should be used to indicate the version in which the code was introduced
- Prefer to **show** nuanced behavior in code examples, rather than try to explain it in prose.
- Method signatures
- Use a `[Parameters]` definition to note the expected types of all the parameters as a bulleted list
- Use a `[Returns]` definition to note the return type
- Use a `[Yields]` definition to note the block parameters
- use RBS syntax whenever possible to declare variable types
- Callouts
- Use a `🛡` character for security-related notes
- Use a `` character to warn the user about tricky usage
- Use a `💡` character to call attention to other important notes
- Examples
- Prefer to **show** nuanced behavior in code examples, rather than try to explain it in prose.
- Use the line `*Example:* <Brief explanation>` to name examples and visually separate them
- Indent two extra columns to get code-block formatting
- Metadata
- `See also:` should be used to call out related methods
- `Since` should be used to indicate the version in which the code was introduced


### Code
Expand Down Expand Up @@ -502,17 +510,20 @@ The `Rakefile` used to be a big fat mess. It's now decomposed into a small set o

## Making a release

A quick checklist:

- [ ] make sure CI is green!
- [ ] update `CHANGELOG.md` and `lib/nokogiri/version/constant.rb`
- [ ] create a git tag
- [ ] run `scripts/build-gems` and make sure it completes and all the tests pass
- [ ] `for g in gems/*.gem ; do gem push $g ; done`
- [ ] create a release at https://github.com/sparklemotion/nokogiri/releases and provide sha2 checksums
- if security-related,
A quick checklist for releasing Nokogiri:

- Prechecks
- [ ] make sure CI is green!
- [ ] update `CHANGELOG.md` and `lib/nokogiri/version/constant.rb`
- [ ] commit and create a git tag
- [ ] run `scripts/build-gems` and make sure it completes and all the tests pass
- Release
- [ ] `git push && git push --tags`
- [ ] `for g in gems/*.gem ; do gem push $g ; done`
- [ ] create a release at https://github.com/sparklemotion/nokogiri/releases and provide sha2 checksums
- If the release has security fixes ...
- [ ] publish a GHSA
- [ ] email [email protected] and [email protected]
- [ ] submit a PR to https://github.com/rubysec/ruby-advisory-db
- [ ] update nokogiri.org
- [ ] bump `lib/nokogiri/version/constant.rb` to a prerelease version like `v1.14.0.dev`
- Post-release
- [ ] update nokogiri.org
- [ ] bump `lib/nokogiri/version/constant.rb` to a prerelease version like `v1.14.0.dev`
12 changes: 6 additions & 6 deletions ext/nokogiri/xml_relax_ng.c
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
VALUE cNokogiriXmlRelaxNG;

static void
xml_relax_ng_deallocate(void *data)
_noko_xml_relax_ng_deallocate(void *data)
{
xmlRelaxNGPtr schema = data;
xmlRelaxNGFree(schema);
Expand All @@ -12,7 +12,7 @@ xml_relax_ng_deallocate(void *data)
static const rb_data_type_t xml_relax_ng_type = {
.wrap_struct_name = "xmlRelaxNG",
.function = {
.dfree = xml_relax_ng_deallocate,
.dfree = _noko_xml_relax_ng_deallocate,
},
.flags = RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED,
};
Expand Down Expand Up @@ -51,7 +51,7 @@ noko_xml_relax_ng__validate_document(VALUE self, VALUE document)
}

static VALUE
xml_relax_ng_parse_schema(
_noko_xml_relax_ng_parse_schema(
VALUE rb_class,
xmlRelaxNGParserCtxtPtr c_parser_context,
VALUE rb_parse_options
Expand Down Expand Up @@ -105,10 +105,10 @@ xml_relax_ng_parse_schema(
* from_document(document) → Nokogiri::XML::RelaxNG
* from_document(document, parse_options) → Nokogiri::XML::RelaxNG
*
* Create a Schema from an already-parsed RELAX NG schema definition document.
* Parse a RELAX NG schema definition from a Document to create a new Schema.
*
* [Parameters]
* - +document+ (XML::Document) A XML::Document object representing the parsed RELAX NG
* - +document+ (XML::Document) RELAX NG schema definition
* - +parse_options+ (Nokogiri::XML::ParseOptions) ⚠ Unused
*
* [Returns] Nokogiri::XML::RelaxNG
Expand All @@ -131,7 +131,7 @@ noko_xml_relax_ng_s_from_document(int argc, VALUE *argv, VALUE rb_class)

c_parser_context = xmlRelaxNGNewDocParserCtxt(c_document);

return xml_relax_ng_parse_schema(rb_class, c_parser_context, rb_parse_options);
return _noko_xml_relax_ng_parse_schema(rb_class, c_parser_context, rb_parse_options);
}

void
Expand Down
76 changes: 29 additions & 47 deletions lib/nokogiri/xml/relax_ng.rb
Original file line number Diff line number Diff line change
Expand Up @@ -4,81 +4,63 @@ module Nokogiri
module XML
class << self
# :call-seq:
# RelaxNg(input) → Nokogiri::XML::RelaxNG
# RelaxNg(input, parse_options) → Nokogiri::XML::RelaxNG
# RelaxNG(input) → Nokogiri::XML::RelaxNG
# RelaxNG(input, options:) → Nokogiri::XML::RelaxNG
#
# Parse a RELAX NG schema definition and create a new Schema object. This is a convenience
# method for Nokogiri::XML::RelaxNG.new
#
# See related: Nokogiri::XML::RelaxNG.new
#
# [Parameters]
# - +input+ (String, IO) RELAX NG schema definition
# - +parse_options+ (Nokogiri::XML::ParseOptions)
# Defaults to ParseOptions::DEFAULT_SCHEMA
#
# [Returns] Nokogiri::XML::RelaxNG
#
def RelaxNG(input, parse_options = ParseOptions::DEFAULT_SCHEMA)
RelaxNG.new(input, parse_options)
# Convenience method for calling Nokogiri::XML::RelaxNG.read_memory
def RelaxNG(...)
RelaxNG.new(...)
end
end

# Nokogiri::XML::RelaxNG is used for validating XML against a RELAX NG schema definition.
# Nokogiri::XML::RelaxNG is used for validating \XML against a RELAX NG schema definition.
#
# *Example:* Determine whether an XML document is valid.
# 🛡 <b>Do not use this class for untrusted schema documents.</b> RELAX NG input is always
# treated as *trusted*, meaning that the underlying parsing libraries <b>will access network
# resources</b>. This is counter to Nokogiri's "untrusted by default" security policy, but is an
# unfortunate limitation of the underlying libraries.
#
# schema = Nokogiri::XML::RelaxNG(File.read(RELAX_NG_FILE))
# doc = Nokogiri::XML(File.read(XML_FILE))
# *Example:* Determine whether an \XML document is valid.
#
# schema = Nokogiri::XML::RelaxNG.read_memory(File.read(RELAX_NG_FILE))
# doc = Nokogiri::XML::Document.parse(File.read(XML_FILE))
# schema.valid?(doc) # Boolean
#
# *Example:* Validate an XML document against a RelaxNG schema, and capture any errors that are found.
# *Example:* Validate an \XML document against a \RelaxNG schema, and capture any errors that are found.
#
# schema = Nokogiri::XML::RelaxNG(File.open(RELAX_NG_FILE))
# doc = Nokogiri::XML(File.open(XML_FILE))
# schema = Nokogiri::XML::RelaxNG.read_memory(File.open(RELAX_NG_FILE))
# doc = Nokogiri::XML::Document.parse(File.open(XML_FILE))
# errors = schema.validate(doc) # Array<SyntaxError>
#
# ⚠ RELAX NG input is always treated as *trusted*, meaning that the underlying parsing libraries
# *will access network resources*. This is counter to Nokogiri's "untrusted by default" security
# policy, but is an unfortunate limitation of the underlying libraries. Please do not use this
# class for untrusted schema documents.
class RelaxNG < Nokogiri::XML::Schema
# :call-seq:
# new(input) → Nokogiri::XML::RelaxNG
# new(input, parse_options) → Nokogiri::XML::RelaxNG
#
# Parse a RELAX NG schema definition and create a new Schema object.
# new(input, options:) → Nokogiri::XML::RelaxNG
#
# [Parameters]
# - +input+ (String, IO) RELAX NG schema definition
# - +parse_options+ (Nokogiri::XML::ParseOptions)
# Defaults to ParseOptions::DEFAULT_SCHEMA ⚠ Unused
#
# [Returns] Nokogiri::XML::RelaxNG
#
# ⚠ +parse_options+ is currently unused by this method and is present only as a placeholder for
# future functionality.
def self.new(input, parse_options = ParseOptions::DEFAULT_SCHEMA)
read_memory(input, parse_options)
# Convenience method for calling Nokogiri::XML::RelaxNG.read_memory
def self.new(...)
read_memory(...)
end

# :call-seq:
# read_memory(input) → Nokogiri::XML::RelaxNG
# read_memory(input, parse_options) → Nokogiri::XML::RelaxNG
# read_memory(input, options:) → Nokogiri::XML::RelaxNG
#
# Parse a RELAX NG schema definition and create a new Schema object.
# Parse a RELAX NG schema definition from a String to create a new Schema.
#
# [Parameters]
# - +input+ (String) RELAX NG schema definition
# - +parse_options+ (Nokogiri::XML::ParseOptions)
# Defaults to ParseOptions::DEFAULT_SCHEMA ⚠ Unused
# - +options:+ (Nokogiri::XML::ParseOptions)
# Defaults to ParseOptions::DEFAULT_SCHEMA ⚠ Unused
#
# [Returns] Nokogiri::XML::RelaxNG
#
# ⚠ +parse_options+ is currently unused by this method and is present only as a placeholder for
# future functionality.
def self.read_memory(input, parse_options = ParseOptions::DEFAULT_SCHEMA)
from_document(Nokogiri::XML::Document.parse(input), parse_options)
#
# Also see convenience method Nokogiri::XML::RelaxNG()
def self.read_memory(input, parse_options_ = ParseOptions::DEFAULT_SCHEMA, options: parse_options_)
from_document(Nokogiri::XML::Document.parse(input), options)
end
end
end
Expand Down

0 comments on commit 3100afb

Please sign in to comment.