XML::RelaxNG argument forwarding (#3342)

**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
sparklemotion · Dec 6, 2024 · 3100afb · 3100afb
2 parents f7a8a35 + 76bfa34
commit 3100afb
Show file tree

Hide file tree

Showing 3 changed files with 66 additions and 73 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -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
@@ -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 ruby-security-ann@googlegroups.com and ruby-talk@ruby-lang.org
-  - [ ] 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`
diff --git a/ext/nokogiri/xml_relax_ng.c b/ext/nokogiri/xml_relax_ng.c
@@ -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);
@@ -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,
 };
@@ -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
@@ -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
@@ -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

diff --git a/lib/nokogiri/xml/relax_ng.rb b/lib/nokogiri/xml/relax_ng.rb
@@ -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