From 0ddb7ee01a4684d2ffa375f87b1326167e659eea Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Fri, 31 Jan 2020 14:15:41 +0900 Subject: [PATCH 01/56] Bump version --- lib/rexml/rexml.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/rexml/rexml.rb b/lib/rexml/rexml.rb index f0651154..fcefbae1 100644 --- a/lib/rexml/rexml.rb +++ b/lib/rexml/rexml.rb @@ -24,7 +24,7 @@ module REXML COPYRIGHT = "Copyright © 2001-2008 Sean Russell " DATE = "2008/019" - VERSION = "3.2.4" + VERSION = "3.2.5" REVISION = "" Copyright = COPYRIGHT From be62163ba12a6657679a34e472b1d29d75e0e881 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Fri, 31 Jan 2020 14:16:03 +0900 Subject: [PATCH 02/56] travis: update Ruby versions --- .travis.yml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.travis.yml b/.travis.yml index b2e241a5..aadba040 100644 --- a/.travis.yml +++ b/.travis.yml @@ -3,18 +3,18 @@ notifications: - https://webhook.commit-email.info/ matrix: include: - - name: "2.3" - rvm: 2.3 - name: "2.4" - rvm: 2.4.5 + rvm: 2.4 - name: "2.5" - rvm: 2.5.2 + rvm: 2.5 - name: "2.6" - rvm: 2.6.0-rc2 + rvm: 2.6 + - name: "2.7" + rvm: 2.7 - name: "trunk" rvm: ruby-head - name: "gem" - rvm: 2.6 + rvm: 2.7 install: - rake install script: From af10ea538e3be1622f7dfb69b2eca44b63c1f9f2 Mon Sep 17 00:00:00 2001 From: Nobuyoshi Nakada Date: Sun, 5 Jul 2020 18:32:43 +0900 Subject: [PATCH 03/56] Already `$SAFE` has been removed in master --- test/lib/leakchecker.rb | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/test/lib/leakchecker.rb b/test/lib/leakchecker.rb index af9200bf..325ca8d0 100644 --- a/test/lib/leakchecker.rb +++ b/test/lib/leakchecker.rb @@ -23,7 +23,11 @@ def check(test_name) end def check_safe test_name + verbose, $VERBOSE = $VERBOSE, nil + return unless defined?($SAFE) puts "#{test_name}: $SAFE == #{$SAFE}" unless $SAFE == 0 + ensure + $VERBOSE = verbose end def check_verbose test_name From ad5de4e78e7c10803952fd898ed742c2fbf7e865 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Fri, 24 Jul 2020 06:45:12 +0900 Subject: [PATCH 04/56] xpath: add an error check for unprocessed rest data --- lib/rexml/parsers/xpathparser.rb | 12 ++++++++++-- test/rexml/xpath/test_axis_self.rb | 22 ++++++++++++++++++++++ 2 files changed, 32 insertions(+), 2 deletions(-) create mode 100644 test/rexml/xpath/test_axis_self.rb diff --git a/lib/rexml/parsers/xpathparser.rb b/lib/rexml/parsers/xpathparser.rb index d01d325e..1ebe1a3b 100644 --- a/lib/rexml/parsers/xpathparser.rb +++ b/lib/rexml/parsers/xpathparser.rb @@ -22,7 +22,13 @@ def parse path path.gsub!(/([\(\[])\s+/, '\1') # Strip ignorable spaces path.gsub!( /\s+([\]\)])/, '\1') parsed = [] - OrExpr(path, parsed) + rest = OrExpr(path, parsed) + if rest + unless rest.strip.empty? + raise ParseException.new("Garbage component exists at the end: " + + "<#{rest}>: <#{path}>") + end + end parsed end @@ -301,7 +307,9 @@ def NodeTest path, parsed when PI path = $' literal = nil - if path !~ /^\s*\)/ + if path =~ /^\s*\)/ + path = $' + else path =~ LITERAL literal = $1 path = $' diff --git a/test/rexml/xpath/test_axis_self.rb b/test/rexml/xpath/test_axis_self.rb new file mode 100644 index 00000000..c0a53736 --- /dev/null +++ b/test/rexml/xpath/test_axis_self.rb @@ -0,0 +1,22 @@ +# frozen_string_literal: false +require "test/unit/testcase" +require "rexml/document" + +module REXMLTests + class TestXPathAxisSelf < Test::Unit::TestCase + def test_only + doc = REXML::Document.new("") + assert_equal([doc.root], + REXML::XPath.match(doc.root, ".")) + end + + def test_have_predicate + doc = REXML::Document.new("") + error = assert_raise(REXML::ParseException) do + REXML::XPath.match(doc.root, ".[child]") + end + assert_equal("Garbage component exists at the end: <[child]>: <.[child]>", + error.message) + end + end +end From 119e38840c6ef6014f5f069d1102c7b2be74ad00 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Fri, 24 Jul 2020 07:03:05 +0900 Subject: [PATCH 05/56] xpath: add more invalid cases * FilterExpr without PrimaryExpr. * RelativeLocationPath without NodeTest. --- lib/rexml/parsers/xpathparser.rb | 24 +++++++++++++++--------- test/rexml/xpath/test_predicate.rb | 9 +++++++++ 2 files changed, 24 insertions(+), 9 deletions(-) diff --git a/lib/rexml/parsers/xpathparser.rb b/lib/rexml/parsers/xpathparser.rb index 1ebe1a3b..d92678fe 100644 --- a/lib/rexml/parsers/xpathparser.rb +++ b/lib/rexml/parsers/xpathparser.rb @@ -235,24 +235,28 @@ def RelativeLocationPath path, parsed path = path[1..-1] end else + path_before_axis_specifier = path + parsed_not_abberviated = [] if path[0] == ?@ - parsed << :attribute + parsed_not_abberviated << :attribute path = path[1..-1] # Goto Nodetest elsif path =~ AXIS - parsed << $1.tr('-','_').intern + parsed_not_abberviated << $1.tr('-','_').intern path = $' # Goto Nodetest else - parsed << :child + parsed_not_abberviated << :child end - n = [] - path = NodeTest( path, n) - - path = Predicate( path, n ) + path_before_node_test = path + path = NodeTest(path, parsed_not_abberviated) + if path == path_before_node_test + return path_before_axis_specifier + end + path = Predicate(path, parsed_not_abberviated) - parsed.concat(n) + parsed.concat(parsed_not_abberviated) end original_path = path @@ -553,7 +557,9 @@ def PathExpr path, parsed #| PrimaryExpr def FilterExpr path, parsed n = [] - path = PrimaryExpr( path, n ) + path_before_primary_expr = path + path = PrimaryExpr(path, n) + return path_before_primary_expr if path == path_before_primary_expr path = Predicate(path, n) parsed.concat(n) path diff --git a/test/rexml/xpath/test_predicate.rb b/test/rexml/xpath/test_predicate.rb index ce1aaa32..8878a2b9 100644 --- a/test/rexml/xpath/test_predicate.rb +++ b/test/rexml/xpath/test_predicate.rb @@ -29,6 +29,15 @@ def setup end + def test_predicate_only + error = assert_raise(REXML::ParseException) do + do_path("[article]") + end + assert_equal("Garbage component exists at the end: " + + "<[article]>: <[article]>", + error.message) + end + def test_predicates_parent path = '//section[../self::section[@role="division"]]' m = do_path( path ) From c1db4d5ce9e06381d63e1fbf44f6f5a65bcc248e Mon Sep 17 00:00:00 2001 From: Koichi ITO Date: Wed, 16 Sep 2020 20:22:11 +0900 Subject: [PATCH 06/56] `require "rexml/document"` by default (#36) It would be convenient if users can use `REXML::Document` without explicitly `require "rexml/document"`. https://guides.rubygems.org/name-your-gem/ I heard the following Gemfile setting in a real world application development: ```ruby # Gemfile gem "rexml", require: "rexml/document" ``` So, I think this could be unnecessary if "rexml/document" will be required by default as a endpoint. --- lib/rexml.rb | 3 +++ rexml.gemspec | 1 + 2 files changed, 4 insertions(+) create mode 100644 lib/rexml.rb diff --git a/lib/rexml.rb b/lib/rexml.rb new file mode 100644 index 00000000..eee246e4 --- /dev/null +++ b/lib/rexml.rb @@ -0,0 +1,3 @@ +# frozen_string_literal: true + +require_relative "rexml/document" diff --git a/rexml.gemspec b/rexml.gemspec index 263f013a..429863d8 100644 --- a/rexml.gemspec +++ b/rexml.gemspec @@ -24,6 +24,7 @@ Gem::Specification.new do |spec| "NEWS.md", "README.md", "Rakefile", + "lib/rexml.rb", "lib/rexml/attlistdecl.rb", "lib/rexml/attribute.rb", "lib/rexml/cdata.rb", From d97b318acb2658a48d94f666d49dd6218aa1f256 Mon Sep 17 00:00:00 2001 From: Akira Matsuda Date: Wed, 9 Dec 2020 14:38:26 +0900 Subject: [PATCH 07/56] Use Refinements to define dclone methods that are used only in xpath_parser.rb (#37) --- lib/rexml/xpath_parser.rb | 66 +++++++++++++++++++++------------------ 1 file changed, 36 insertions(+), 30 deletions(-) diff --git a/lib/rexml/xpath_parser.rb b/lib/rexml/xpath_parser.rb index b9897254..d8b88e7a 100644 --- a/lib/rexml/xpath_parser.rb +++ b/lib/rexml/xpath_parser.rb @@ -7,39 +7,45 @@ require_relative 'attribute' require_relative 'parsers/xpathparser' -class Object - # provides a unified +clone+ operation, for REXML::XPathParser - # to use across multiple Object types - def dclone - clone - end -end -class Symbol - # provides a unified +clone+ operation, for REXML::XPathParser - # to use across multiple Object types - def dclone ; self ; end -end -class Integer - # provides a unified +clone+ operation, for REXML::XPathParser - # to use across multiple Object types - def dclone ; self ; end -end -class Float - # provides a unified +clone+ operation, for REXML::XPathParser - # to use across multiple Object types - def dclone ; self ; end -end -class Array - # provides a unified +clone+ operation, for REXML::XPathParser - # to use across multiple Object+ types - def dclone - klone = self.clone - klone.clear - self.each{|v| klone << v.dclone} - klone +module REXML + module DClonable + refine Object do + # provides a unified +clone+ operation, for REXML::XPathParser + # to use across multiple Object types + def dclone + clone + end + end + refine Symbol do + # provides a unified +clone+ operation, for REXML::XPathParser + # to use across multiple Object types + def dclone ; self ; end + end + refine Integer do + # provides a unified +clone+ operation, for REXML::XPathParser + # to use across multiple Object types + def dclone ; self ; end + end + refine Float do + # provides a unified +clone+ operation, for REXML::XPathParser + # to use across multiple Object types + def dclone ; self ; end + end + refine Array do + # provides a unified +clone+ operation, for REXML::XPathParser + # to use across multiple Object+ types + def dclone + klone = self.clone + klone.clear + self.each{|v| klone << v.dclone} + klone + end + end end end +using REXML::DClonable + module REXML # You don't want to use this class. Really. Use XPath, which is a wrapper # for this class. Believe me. You don't want to poke around in here. From 8c5d5cd75c9f15a77e1a2a0162a141f8ee85a8b1 Mon Sep 17 00:00:00 2001 From: Nobuyoshi Nakada Date: Wed, 6 Jan 2021 18:22:47 +0900 Subject: [PATCH 08/56] Exclude useless files after installation (#39) These files are meaningless outside the working directory. --- rexml.gemspec | 5 ----- 1 file changed, 5 deletions(-) diff --git a/rexml.gemspec b/rexml.gemspec index 429863d8..9259a9a5 100644 --- a/rexml.gemspec +++ b/rexml.gemspec @@ -17,13 +17,9 @@ Gem::Specification.new do |spec| spec.license = "BSD-2-Clause" spec.files = [ - ".gitignore", - ".travis.yml", - "Gemfile", "LICENSE.txt", "NEWS.md", "README.md", - "Rakefile", "lib/rexml.rb", "lib/rexml/attlistdecl.rb", "lib/rexml/attribute.rb", @@ -74,7 +70,6 @@ Gem::Specification.new do |spec| "lib/rexml/xmltokens.rb", "lib/rexml/xpath.rb", "lib/rexml/xpath_parser.rb", - "rexml.gemspec", ] spec.bindir = "exe" spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) } From c306201e55b75eb0c8f8ccca33b154b3cb50140c Mon Sep 17 00:00:00 2001 From: timcraft Date: Wed, 6 Jan 2021 21:17:26 +0000 Subject: [PATCH 09/56] Test on ruby 3.0 (#40) --- .travis.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.travis.yml b/.travis.yml index aadba040..f2c0491b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -11,6 +11,8 @@ matrix: rvm: 2.6 - name: "2.7" rvm: 2.7 + - name: "3.0" + rvm: 3.0 - name: "trunk" rvm: ruby-head - name: "gem" From 1e59077896912a7a35be45f14ce95770f4d6b158 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Thu, 7 Jan 2021 06:24:10 +0900 Subject: [PATCH 10/56] ci: migrate to GitHub Actions from Travis CI --- .github/workflows/test.yml | 37 +++++++++++++++++++++++++++++++++++++ .travis.yml | 26 -------------------------- 2 files changed, 37 insertions(+), 26 deletions(-) create mode 100644 .github/workflows/test.yml delete mode 100644 .travis.yml diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 00000000..fe5611a6 --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,37 @@ +name: Test +on: + - push + - pull_request +jobs: + test: + name: ${{ matrix.ruby-version }} on ${{ matrix.runs-on }} + runs-on: ${{ matrix.runs-on }} + strategy: + fail-fast: false + matrix: + runs-on: + - ubuntu-latest + - macos-latest + - windows-latest + ruby-version: + - "2.5" + - "2.6" + - "2.7" + - "3.0" + - head + - jruby + -truffleruby + steps: + - uses: actions/checkout@v2 + - uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby-version }} + - name: Install as gem + run: | + rake install + - name: Test + run: | + ruby -run -e mkdir -- tmp + ruby -run -e cp -- -p -r test tmp + cd tmp + ruby ../run-test.rb diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index f2c0491b..00000000 --- a/.travis.yml +++ /dev/null @@ -1,26 +0,0 @@ -notifications: - webhooks: - - https://webhook.commit-email.info/ -matrix: - include: - - name: "2.4" - rvm: 2.4 - - name: "2.5" - rvm: 2.5 - - name: "2.6" - rvm: 2.6 - - name: "2.7" - rvm: 2.7 - - name: "3.0" - rvm: 3.0 - - name: "trunk" - rvm: ruby-head - - name: "gem" - rvm: 2.7 - install: - - rake install - script: - - mkdir -p tmp - - cd tmp - - cp -a ../test/ ./ - - ../run-test.rb From 8adeb16efd8a3cf3779eb0c4f93d02164a774c9c Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Thu, 7 Jan 2021 06:25:11 +0900 Subject: [PATCH 11/56] ci: fix a typo --- .github/workflows/test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index fe5611a6..f004a79c 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -20,7 +20,7 @@ jobs: - "3.0" - head - jruby - -truffleruby + - truffleruby steps: - uses: actions/checkout@v2 - uses: ruby/setup-ruby@v1 From f9d186376ec40b4dd63c7a7093af193272e50dfe Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Thu, 7 Jan 2021 06:39:02 +0900 Subject: [PATCH 12/56] ci: use gem only with Ruby 3.0 or later --- .github/workflows/test.yml | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index f004a79c..269dc5b3 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -3,7 +3,7 @@ on: - push - pull_request jobs: - test: + inplace: name: ${{ matrix.ruby-version }} on ${{ matrix.runs-on }} runs-on: ${{ matrix.runs-on }} strategy: @@ -17,10 +17,30 @@ jobs: - "2.5" - "2.6" - "2.7" - - "3.0" - - head - jruby - truffleruby + steps: + - uses: actions/checkout@v2 + - uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby-version }} + bundler-cache: true + - name: Test + run: bundle exec rake + + gem: + name: ${{ matrix.ruby-version }} on ${{ matrix.runs-on }} + runs-on: ${{ matrix.runs-on }} + strategy: + fail-fast: false + matrix: + runs-on: + - ubuntu-latest + - macos-latest + - windows-latest + ruby-version: + - "3.0" + - head steps: - uses: actions/checkout@v2 - uses: ruby/setup-ruby@v1 From 3ac43963d34c37ee10b00e024950b8ae11583e80 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Thu, 7 Jan 2021 06:40:02 +0900 Subject: [PATCH 13/56] test: ensure using rexml_test_utils --- test/rexml/test_attributes.rb | 4 ++-- test/rexml/test_attributes_mixin.rb | 4 ++-- test/rexml/test_changing_encoding.rb | 1 + test/rexml/test_comment.rb | 3 +-- test/rexml/test_document.rb | 3 +-- test/rexml/test_element.rb | 3 +-- test/rexml/test_elements.rb | 4 ++-- test/rexml/test_entity.rb | 4 ++-- test/rexml/test_martin_fowler.rb | 4 ++-- test/rexml/test_preceding_sibling.rb | 4 ++-- test/rexml/test_pullparser.rb | 3 ++- test/rexml/test_stream.rb | 5 +++-- test/rexml/test_ticket_80.rb | 3 +-- test/rexml/test_validation_rng.rb | 4 ++-- test/rexml/test_xml_declaration.rb | 3 +-- test/rexml/xpath/test_attribute.rb | 4 ++-- test/rexml/xpath/test_axis_preceding_sibling.rb | 4 ++-- test/rexml/xpath/test_axis_self.rb | 4 ++-- test/rexml/xpath/test_base.rb | 3 +-- test/rexml/xpath/test_compare.rb | 2 -- test/rexml/xpath/test_node.rb | 2 -- test/rexml/xpath/test_predicate.rb | 5 +++-- test/rexml/xpath/test_text.rb | 5 +++-- 23 files changed, 38 insertions(+), 43 deletions(-) diff --git a/test/rexml/test_attributes.rb b/test/rexml/test_attributes.rb index d6f566bd..b0d87221 100644 --- a/test/rexml/test_attributes.rb +++ b/test/rexml/test_attributes.rb @@ -1,6 +1,6 @@ # frozen_string_literal: false -require 'test/unit/testcase' -require 'rexml/document' + +require_relative "rexml_test_utils" module REXMLTests class AttributesTester < Test::Unit::TestCase diff --git a/test/rexml/test_attributes_mixin.rb b/test/rexml/test_attributes_mixin.rb index 3a9f54ee..3de34f8c 100644 --- a/test/rexml/test_attributes_mixin.rb +++ b/test/rexml/test_attributes_mixin.rb @@ -1,6 +1,6 @@ # frozen_string_literal: false -require 'test/unit' -require 'rexml/document' + +require_relative "rexml_test_utils" module REXMLTests class TestAttributes < Test::Unit::TestCase diff --git a/test/rexml/test_changing_encoding.rb b/test/rexml/test_changing_encoding.rb index a2dc0725..73a61ef7 100644 --- a/test/rexml/test_changing_encoding.rb +++ b/test/rexml/test_changing_encoding.rb @@ -1,6 +1,7 @@ # -*- coding: utf-8 -*- # frozen_string_literal: false +require_relative "rexml_test_utils" require 'rexml/encoding' module REXMLTests diff --git a/test/rexml/test_comment.rb b/test/rexml/test_comment.rb index 0af2f5ca..aa026bc9 100644 --- a/test/rexml/test_comment.rb +++ b/test/rexml/test_comment.rb @@ -1,7 +1,6 @@ # frozen_string_literal: false -require "test/unit/testcase" -require 'rexml/document' +require_relative "rexml_test_utils" module REXMLTests class CommentTester < Test::Unit::TestCase diff --git a/test/rexml/test_document.rb b/test/rexml/test_document.rb index c0faae4a..95e8194d 100644 --- a/test/rexml/test_document.rb +++ b/test/rexml/test_document.rb @@ -1,8 +1,7 @@ # -*- coding: utf-8 -*- # frozen_string_literal: false -require "rexml/document" -require "test/unit" +require_relative "rexml_test_utils" module REXMLTests class TestDocument < Test::Unit::TestCase diff --git a/test/rexml/test_element.rb b/test/rexml/test_element.rb index 82830b44..b25d32ba 100644 --- a/test/rexml/test_element.rb +++ b/test/rexml/test_element.rb @@ -1,7 +1,6 @@ # frozen_string_literal: false -require "test/unit/testcase" -require "rexml/document" +require_relative "rexml_test_utils" module REXMLTests class ElementTester < Test::Unit::TestCase diff --git a/test/rexml/test_elements.rb b/test/rexml/test_elements.rb index a850e622..e5453b63 100644 --- a/test/rexml/test_elements.rb +++ b/test/rexml/test_elements.rb @@ -1,6 +1,6 @@ # frozen_string_literal: false -require 'test/unit/testcase' -require 'rexml/document' + +require_relative "rexml_test_utils" module REXMLTests class ElementsTester < Test::Unit::TestCase diff --git a/test/rexml/test_entity.rb b/test/rexml/test_entity.rb index 6dc66370..9bb26db6 100644 --- a/test/rexml/test_entity.rb +++ b/test/rexml/test_entity.rb @@ -1,7 +1,7 @@ # frozen_string_literal: false -require "test/unit/testcase" -require 'rexml/document' +require_relative "rexml_test_utils" + require 'rexml/entity' require 'rexml/source' diff --git a/test/rexml/test_martin_fowler.rb b/test/rexml/test_martin_fowler.rb index add3c827..216df846 100644 --- a/test/rexml/test_martin_fowler.rb +++ b/test/rexml/test_martin_fowler.rb @@ -1,6 +1,6 @@ # frozen_string_literal: false -require 'test/unit' -require 'rexml/document' + +require_relative "rexml_test_utils" module REXMLTests class OrderTesterMF < Test::Unit::TestCase diff --git a/test/rexml/test_preceding_sibling.rb b/test/rexml/test_preceding_sibling.rb index d89a1e1c..c92e4549 100644 --- a/test/rexml/test_preceding_sibling.rb +++ b/test/rexml/test_preceding_sibling.rb @@ -1,7 +1,7 @@ # frozen_string_literal: false # ISSUE 32 -require 'test/unit' -require 'rexml/document' + +require_relative "rexml_test_utils" module REXMLTests # daz - for report by Dan Kohn in: diff --git a/test/rexml/test_pullparser.rb b/test/rexml/test_pullparser.rb index 31b5b74b..6af53aeb 100644 --- a/test/rexml/test_pullparser.rb +++ b/test/rexml/test_pullparser.rb @@ -1,5 +1,6 @@ # frozen_string_literal: false -require "test/unit/testcase" + +require_relative "rexml_test_utils" require 'rexml/parsers/pullparser' diff --git a/test/rexml/test_stream.rb b/test/rexml/test_stream.rb index 08d4462e..fd9d0c62 100644 --- a/test/rexml/test_stream.rb +++ b/test/rexml/test_stream.rb @@ -1,6 +1,7 @@ # frozen_string_literal: false -require "test/unit/testcase" -require "rexml/document" + +require_relative "rexml_test_utils" + require 'rexml/streamlistener' require 'stringio' diff --git a/test/rexml/test_ticket_80.rb b/test/rexml/test_ticket_80.rb index ab6a57ef..70557e4d 100644 --- a/test/rexml/test_ticket_80.rb +++ b/test/rexml/test_ticket_80.rb @@ -7,8 +7,7 @@ # copy: (C) CopyLoose 2006 Bib Development Team atdot #------------------------------------------------------------------------------ -require 'test/unit' -require 'rexml/document' +require_relative "rexml_test_utils" module REXMLTests class Ticket80 < Test::Unit::TestCase diff --git a/test/rexml/test_validation_rng.rb b/test/rexml/test_validation_rng.rb index b5b50450..c6821131 100644 --- a/test/rexml/test_validation_rng.rb +++ b/test/rexml/test_validation_rng.rb @@ -1,7 +1,7 @@ # frozen_string_literal: false -require "test/unit/testcase" -require "rexml/document" +require_relative "rexml_test_utils" + require "rexml/validation/relaxng" module REXMLTests diff --git a/test/rexml/test_xml_declaration.rb b/test/rexml/test_xml_declaration.rb index da707612..e9bd538b 100644 --- a/test/rexml/test_xml_declaration.rb +++ b/test/rexml/test_xml_declaration.rb @@ -3,8 +3,7 @@ # Created by Henrik Mårtensson on 2007-02-18. # Copyright (c) 2007. All rights reserved. -require "rexml/document" -require "test/unit" +require_relative "rexml_test_utils" module REXMLTests class TestXmlDeclaration < Test::Unit::TestCase diff --git a/test/rexml/xpath/test_attribute.rb b/test/rexml/xpath/test_attribute.rb index 713d77b2..d1e088f9 100644 --- a/test/rexml/xpath/test_attribute.rb +++ b/test/rexml/xpath/test_attribute.rb @@ -1,6 +1,6 @@ # frozen_string_literal: false -require 'test/unit' -require 'rexml/document' + +require_relative "../rexml_test_utils" module REXMLTests class TestXPathAttribute < Test::Unit::TestCase diff --git a/test/rexml/xpath/test_axis_preceding_sibling.rb b/test/rexml/xpath/test_axis_preceding_sibling.rb index 5842c6bc..0e208505 100644 --- a/test/rexml/xpath/test_axis_preceding_sibling.rb +++ b/test/rexml/xpath/test_axis_preceding_sibling.rb @@ -1,6 +1,6 @@ # frozen_string_literal: false -require "test/unit/testcase" -require "rexml/document" + +require_relative "../rexml_test_utils" module REXMLTests class TestXPathAxisPredcedingSibling < Test::Unit::TestCase diff --git a/test/rexml/xpath/test_axis_self.rb b/test/rexml/xpath/test_axis_self.rb index c0a53736..da934349 100644 --- a/test/rexml/xpath/test_axis_self.rb +++ b/test/rexml/xpath/test_axis_self.rb @@ -1,6 +1,6 @@ # frozen_string_literal: false -require "test/unit/testcase" -require "rexml/document" + +require_relative "../rexml_test_utils" module REXMLTests class TestXPathAxisSelf < Test::Unit::TestCase diff --git a/test/rexml/xpath/test_base.rb b/test/rexml/xpath/test_base.rb index 210d6c7c..9eac3716 100644 --- a/test/rexml/xpath/test_base.rb +++ b/test/rexml/xpath/test_base.rb @@ -1,7 +1,6 @@ # frozen_string_literal: false -require_relative "../rexml_test_utils" -require "rexml/document" +require_relative "../rexml_test_utils" module REXMLTests class TestXPathBase < Test::Unit::TestCase diff --git a/test/rexml/xpath/test_compare.rb b/test/rexml/xpath/test_compare.rb index bb666c9b..c2d25fc3 100644 --- a/test/rexml/xpath/test_compare.rb +++ b/test/rexml/xpath/test_compare.rb @@ -2,8 +2,6 @@ require_relative "../rexml_test_utils" -require "rexml/document" - module REXMLTests class TestXPathCompare < Test::Unit::TestCase def match(xml, xpath) diff --git a/test/rexml/xpath/test_node.rb b/test/rexml/xpath/test_node.rb index e0e958e7..185dbd59 100644 --- a/test/rexml/xpath/test_node.rb +++ b/test/rexml/xpath/test_node.rb @@ -3,8 +3,6 @@ require_relative "../rexml_test_utils" -require "rexml/document" - module REXMLTests class TestXPathNode < Test::Unit::TestCase def matches(xml, xpath) diff --git a/test/rexml/xpath/test_predicate.rb b/test/rexml/xpath/test_predicate.rb index 8878a2b9..32bd9b80 100644 --- a/test/rexml/xpath/test_predicate.rb +++ b/test/rexml/xpath/test_predicate.rb @@ -1,6 +1,7 @@ # frozen_string_literal: false -require "test/unit/testcase" -require "rexml/document" + +require_relative "../rexml_test_utils" + require "rexml/xpath" require "rexml/parsers/xpathparser" diff --git a/test/rexml/xpath/test_text.rb b/test/rexml/xpath/test_text.rb index 7222388e..854f554d 100644 --- a/test/rexml/xpath/test_text.rb +++ b/test/rexml/xpath/test_text.rb @@ -1,6 +1,7 @@ # frozen_string_literal: false -require 'test/unit' -require 'rexml/document' + +require_relative "../rexml_test_utils" + require 'rexml/element' require 'rexml/xpath' From 795e4fe299d976bec312374b90312f343b90922c Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Thu, 7 Jan 2021 07:03:31 +0900 Subject: [PATCH 14/56] test: use test-unit to work with JRuby --- .github/workflows/test.yml | 2 +- Rakefile | 2 +- rexml.gemspec | 1 + run-test.rb | 9 - test/{rexml => }/data/LostineRiver.kml.gz | Bin test/{rexml => }/data/ProductionSupport.xml | 0 test/{rexml => }/data/axis.xml | 0 test/{rexml => }/data/bad.xml | 0 test/{rexml => }/data/basic.xml | 0 test/{rexml => }/data/basicupdate.xml | 0 test/{rexml => }/data/broken.rss | 0 test/{rexml => }/data/contents.xml | 0 test/{rexml => }/data/dash.xml | 0 test/{rexml => }/data/defaultNamespace.xml | 0 test/{rexml => }/data/doctype_test.xml | 0 test/{rexml => }/data/documentation.xml | 0 test/{rexml => }/data/euc.xml | 0 test/{rexml => }/data/evaluate.xml | 0 test/{rexml => }/data/fibo.xml | 0 test/{rexml => }/data/foo.xml | 0 test/{rexml => }/data/google.2.xml | 0 test/{rexml => }/data/id.xml | 0 test/{rexml => }/data/iso8859-1.xml | 0 test/{rexml => }/data/jaxen24.xml | 0 test/{rexml => }/data/jaxen3.xml | 0 test/{rexml => }/data/lang.xml | 0 test/{rexml => }/data/lang0.xml | 0 test/{rexml => }/data/message.xml | 0 test/{rexml => }/data/moreover.xml | 0 test/{rexml => }/data/much_ado.xml | 0 test/{rexml => }/data/namespaces.xml | 0 test/{rexml => }/data/nitf.xml | 0 test/{rexml => }/data/numbers.xml | 0 .../data/ofbiz-issues-full-177.xml | 0 test/{rexml => }/data/pi.xml | 0 test/{rexml => }/data/pi2.xml | 0 test/{rexml => }/data/project.xml | 0 test/{rexml => }/data/simple.xml | 0 test/{rexml => }/data/stream_accents.xml | 0 test/{rexml => }/data/t63-1.xml | Bin test/{rexml => }/data/t63-2.svg | 0 test/{rexml => }/data/t75.xml | 0 test/{rexml => }/data/test/tests.xml | 0 test/{rexml => }/data/test/tests.xsl | 0 test/{rexml => }/data/testNamespaces.xml | 0 test/{rexml => }/data/testsrc.xml | 0 test/{rexml => }/data/text.xml | 0 test/{rexml => }/data/ticket_61.xml | 0 test/{rexml => }/data/ticket_68.xml | 0 test/{rexml => }/data/tutorial.xml | 0 test/{rexml => }/data/underscore.xml | 0 test/{rexml => }/data/utf16.xml | Bin test/{rexml => }/data/web.xml | 0 test/{rexml => }/data/web2.xml | 0 test/{rexml => }/data/working.rss | 0 test/{rexml => }/data/xmlfile-bug.xml | 0 test/{rexml => }/data/xp.tst | 0 test/{rexml => }/data/yahoo.xml | 0 test/{rexml => }/formatter/test_default.rb | 2 - test/{rexml => }/functions/test_base.rb | 0 test/{rexml => }/functions/test_boolean.rb | 0 test/{rexml => }/functions/test_local_name.rb | 0 test/{rexml => }/functions/test_number.rb | 0 test/helper.rb | 35 + test/lib/envutil.rb | 298 ---- test/lib/find_executable.rb | 22 - test/lib/iseq_loader_checker.rb | 75 - test/lib/jit_support.rb | 57 - test/lib/leakchecker.rb | 244 --- test/lib/memory_status.rb | 149 -- test/lib/minitest/README.txt | 457 ------ test/lib/minitest/autorun.rb | 14 - test/lib/minitest/benchmark.rb | 418 ----- test/lib/minitest/mock.rb | 196 --- test/lib/minitest/unit.rb | 1416 ----------------- test/lib/profile_test_all.rb | 91 -- test/lib/test/unit.rb | 1175 -------------- test/lib/test/unit/assertions.rb | 943 ----------- test/lib/test/unit/parallel.rb | 208 --- test/lib/test/unit/testcase.rb | 36 - test/lib/tracepointchecker.rb | 126 -- test/lib/with_different_ofs.rb | 18 - test/lib/zombie_hunter.rb | 13 - test/{rexml => }/listener.rb | 0 .../parse/test_document_type_declaration.rb | 0 test/{rexml => }/parse/test_element.rb | 0 .../parse/test_notation_declaration.rb | 0 .../parse/test_processing_instruction.rb | 0 test/{rexml => }/parser/test_sax2.rb | 0 test/{rexml => }/parser/test_stream.rb | 0 test/{rexml => }/parser/test_tree.rb | 0 test/{rexml => }/parser/test_ultra_light.rb | 0 test/rexml/rexml_test_utils.rb | 10 - test/run.rb | 13 + test/{rexml => }/test_attribute.rb | 2 - test/{rexml => }/test_attributes.rb | 2 - test/{rexml => }/test_attributes_mixin.rb | 2 - test/{rexml => }/test_changing_encoding.rb | 1 - test/{rexml => }/test_comment.rb | 2 - test/{rexml => }/test_contrib.rb | 5 +- test/{rexml => }/test_core.rb | 6 +- test/{rexml => }/test_doctype.rb | 2 - test/{rexml => }/test_document.rb | 2 - test/{rexml => }/test_element.rb | 2 - test/{rexml => }/test_elements.rb | 2 - test/{rexml => }/test_encoding.rb | 21 +- test/{rexml => }/test_entity.rb | 2 - test/{rexml => }/test_instruction.rb | 2 - test/{rexml => }/test_jaxen.rb | 3 +- test/{rexml => }/test_light.rb | 4 +- test/{rexml => }/test_lightparser.rb | 4 +- test/{rexml => }/test_listener.rb | 5 +- test/{rexml => }/test_martin_fowler.rb | 2 - test/{rexml => }/test_namespace.rb | 5 +- test/{rexml => }/test_order.rb | 5 +- test/{rexml => }/test_preceding_sibling.rb | 2 - test/{rexml => }/test_pullparser.rb | 2 - test/{rexml => }/test_rexml_issuezilla.rb | 4 +- test/{rexml => }/test_sax.rb | 5 +- test/{rexml => }/test_stream.rb | 2 - test/{rexml => }/test_text.rb | 2 - test/{rexml => }/test_ticket_80.rb | 2 - test/{rexml => }/test_validation_rng.rb | 2 - test/{rexml => }/test_xml_declaration.rb | 2 - test/{rexml => }/xpath/test_attribute.rb | 2 - .../xpath/test_axis_preceding_sibling.rb | 2 - test/{rexml => }/xpath/test_axis_self.rb | 2 - test/{rexml => }/xpath/test_base.rb | 4 +- test/{rexml => }/xpath/test_compare.rb | 2 - test/{rexml => }/xpath/test_node.rb | 2 - test/{rexml => }/xpath/test_predicate.rb | 2 - test/{rexml => }/xpath/test_text.rb | 2 - 132 files changed, 77 insertions(+), 6075 deletions(-) delete mode 100755 run-test.rb rename test/{rexml => }/data/LostineRiver.kml.gz (100%) rename test/{rexml => }/data/ProductionSupport.xml (100%) rename test/{rexml => }/data/axis.xml (100%) rename test/{rexml => }/data/bad.xml (100%) rename test/{rexml => }/data/basic.xml (100%) rename test/{rexml => }/data/basicupdate.xml (100%) rename test/{rexml => }/data/broken.rss (100%) rename test/{rexml => }/data/contents.xml (100%) rename test/{rexml => }/data/dash.xml (100%) rename test/{rexml => }/data/defaultNamespace.xml (100%) rename test/{rexml => }/data/doctype_test.xml (100%) rename test/{rexml => }/data/documentation.xml (100%) rename test/{rexml => }/data/euc.xml (100%) rename test/{rexml => }/data/evaluate.xml (100%) rename test/{rexml => }/data/fibo.xml (100%) rename test/{rexml => }/data/foo.xml (100%) rename test/{rexml => }/data/google.2.xml (100%) rename test/{rexml => }/data/id.xml (100%) rename test/{rexml => }/data/iso8859-1.xml (100%) rename test/{rexml => }/data/jaxen24.xml (100%) rename test/{rexml => }/data/jaxen3.xml (100%) rename test/{rexml => }/data/lang.xml (100%) rename test/{rexml => }/data/lang0.xml (100%) rename test/{rexml => }/data/message.xml (100%) rename test/{rexml => }/data/moreover.xml (100%) rename test/{rexml => }/data/much_ado.xml (100%) rename test/{rexml => }/data/namespaces.xml (100%) rename test/{rexml => }/data/nitf.xml (100%) rename test/{rexml => }/data/numbers.xml (100%) rename test/{rexml => }/data/ofbiz-issues-full-177.xml (100%) rename test/{rexml => }/data/pi.xml (100%) rename test/{rexml => }/data/pi2.xml (100%) rename test/{rexml => }/data/project.xml (100%) rename test/{rexml => }/data/simple.xml (100%) rename test/{rexml => }/data/stream_accents.xml (100%) rename test/{rexml => }/data/t63-1.xml (100%) rename test/{rexml => }/data/t63-2.svg (100%) rename test/{rexml => }/data/t75.xml (100%) rename test/{rexml => }/data/test/tests.xml (100%) rename test/{rexml => }/data/test/tests.xsl (100%) rename test/{rexml => }/data/testNamespaces.xml (100%) rename test/{rexml => }/data/testsrc.xml (100%) rename test/{rexml => }/data/text.xml (100%) rename test/{rexml => }/data/ticket_61.xml (100%) rename test/{rexml => }/data/ticket_68.xml (100%) rename test/{rexml => }/data/tutorial.xml (100%) rename test/{rexml => }/data/underscore.xml (100%) rename test/{rexml => }/data/utf16.xml (100%) rename test/{rexml => }/data/web.xml (100%) rename test/{rexml => }/data/web2.xml (100%) rename test/{rexml => }/data/working.rss (100%) rename test/{rexml => }/data/xmlfile-bug.xml (100%) rename test/{rexml => }/data/xp.tst (100%) rename test/{rexml => }/data/yahoo.xml (100%) rename test/{rexml => }/formatter/test_default.rb (91%) rename test/{rexml => }/functions/test_base.rb (100%) rename test/{rexml => }/functions/test_boolean.rb (100%) rename test/{rexml => }/functions/test_local_name.rb (100%) rename test/{rexml => }/functions/test_number.rb (100%) create mode 100644 test/helper.rb delete mode 100644 test/lib/envutil.rb delete mode 100644 test/lib/find_executable.rb delete mode 100644 test/lib/iseq_loader_checker.rb delete mode 100644 test/lib/jit_support.rb delete mode 100644 test/lib/leakchecker.rb delete mode 100644 test/lib/memory_status.rb delete mode 100644 test/lib/minitest/README.txt delete mode 100644 test/lib/minitest/autorun.rb delete mode 100644 test/lib/minitest/benchmark.rb delete mode 100644 test/lib/minitest/mock.rb delete mode 100644 test/lib/minitest/unit.rb delete mode 100644 test/lib/profile_test_all.rb delete mode 100644 test/lib/test/unit.rb delete mode 100644 test/lib/test/unit/assertions.rb delete mode 100644 test/lib/test/unit/parallel.rb delete mode 100644 test/lib/test/unit/testcase.rb delete mode 100644 test/lib/tracepointchecker.rb delete mode 100644 test/lib/with_different_ofs.rb delete mode 100644 test/lib/zombie_hunter.rb rename test/{rexml => }/listener.rb (100%) rename test/{rexml => }/parse/test_document_type_declaration.rb (100%) rename test/{rexml => }/parse/test_element.rb (100%) rename test/{rexml => }/parse/test_notation_declaration.rb (100%) rename test/{rexml => }/parse/test_processing_instruction.rb (100%) rename test/{rexml => }/parser/test_sax2.rb (100%) rename test/{rexml => }/parser/test_stream.rb (100%) rename test/{rexml => }/parser/test_tree.rb (100%) rename test/{rexml => }/parser/test_ultra_light.rb (100%) delete mode 100644 test/rexml/rexml_test_utils.rb create mode 100755 test/run.rb rename test/{rexml => }/test_attribute.rb (90%) rename test/{rexml => }/test_attributes.rb (99%) rename test/{rexml => }/test_attributes_mixin.rb (96%) rename test/{rexml => }/test_changing_encoding.rb (96%) rename test/{rexml => }/test_comment.rb (93%) rename test/{rexml => }/test_contrib.rb (99%) rename test/{rexml => }/test_core.rb (99%) rename test/{rexml => }/test_doctype.rb (99%) rename test/{rexml => }/test_document.rb (99%) rename test/{rexml => }/test_element.rb (91%) rename test/{rexml => }/test_elements.rb (98%) rename test/{rexml => }/test_encoding.rb (88%) rename test/{rexml => }/test_entity.rb (99%) rename test/{rexml => }/test_instruction.rb (90%) rename test/{rexml => }/test_jaxen.rb (98%) rename test/{rexml => }/test_light.rb (97%) rename test/{rexml => }/test_lightparser.rb (84%) rename test/{rexml => }/test_listener.rb (97%) rename test/{rexml => }/test_martin_fowler.rb (95%) rename test/{rexml => }/test_namespace.rb (92%) rename test/{rexml => }/test_order.rb (97%) rename test/{rexml => }/test_preceding_sibling.rb (96%) rename test/{rexml => }/test_pullparser.rb (98%) rename test/{rexml => }/test_rexml_issuezilla.rb (82%) rename test/{rexml => }/test_sax.rb (99%) rename test/{rexml => }/test_stream.rb (98%) rename test/{rexml => }/test_text.rb (98%) rename test/{rexml => }/test_ticket_80.rb (98%) rename test/{rexml => }/test_validation_rng.rb (99%) rename test/{rexml => }/test_xml_declaration.rb (97%) rename test/{rexml => }/xpath/test_attribute.rb (96%) rename test/{rexml => }/xpath/test_axis_preceding_sibling.rb (96%) rename test/{rexml => }/xpath/test_axis_self.rb (93%) rename test/{rexml => }/xpath/test_base.rb (99%) rename test/{rexml => }/xpath/test_compare.rb (99%) rename test/{rexml => }/xpath/test_node.rb (95%) rename test/{rexml => }/xpath/test_predicate.rb (98%) rename test/{rexml => }/xpath/test_text.rb (98%) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 269dc5b3..b40a82b5 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -54,4 +54,4 @@ jobs: ruby -run -e mkdir -- tmp ruby -run -e cp -- -p -r test tmp cd tmp - ruby ../run-test.rb + ruby test/run.rb diff --git a/Rakefile b/Rakefile index 9da51d61..7d9c3cce 100644 --- a/Rakefile +++ b/Rakefile @@ -2,7 +2,7 @@ require "bundler/gem_tasks" desc "Run test" task :test do - ruby("run-test.rb") + ruby("test/run.rb") end task :default => :test diff --git a/rexml.gemspec b/rexml.gemspec index 9259a9a5..b3db38b4 100644 --- a/rexml.gemspec +++ b/rexml.gemspec @@ -77,4 +77,5 @@ Gem::Specification.new do |spec| spec.add_development_dependency "bundler" spec.add_development_dependency "rake" + spec.add_development_dependency "test-unit" end diff --git a/run-test.rb b/run-test.rb deleted file mode 100755 index d06225d0..00000000 --- a/run-test.rb +++ /dev/null @@ -1,9 +0,0 @@ -#!/usr/bin/env ruby - -$LOAD_PATH.unshift("test") -$LOAD_PATH.unshift("test/lib") -$LOAD_PATH.unshift("lib") - -Dir.glob("test/rexml/**/*test_*.rb") do |test_rb| - require File.expand_path(test_rb) -end diff --git a/test/rexml/data/LostineRiver.kml.gz b/test/data/LostineRiver.kml.gz similarity index 100% rename from test/rexml/data/LostineRiver.kml.gz rename to test/data/LostineRiver.kml.gz diff --git a/test/rexml/data/ProductionSupport.xml b/test/data/ProductionSupport.xml similarity index 100% rename from test/rexml/data/ProductionSupport.xml rename to test/data/ProductionSupport.xml diff --git a/test/rexml/data/axis.xml b/test/data/axis.xml similarity index 100% rename from test/rexml/data/axis.xml rename to test/data/axis.xml diff --git a/test/rexml/data/bad.xml b/test/data/bad.xml similarity index 100% rename from test/rexml/data/bad.xml rename to test/data/bad.xml diff --git a/test/rexml/data/basic.xml b/test/data/basic.xml similarity index 100% rename from test/rexml/data/basic.xml rename to test/data/basic.xml diff --git a/test/rexml/data/basicupdate.xml b/test/data/basicupdate.xml similarity index 100% rename from test/rexml/data/basicupdate.xml rename to test/data/basicupdate.xml diff --git a/test/rexml/data/broken.rss b/test/data/broken.rss similarity index 100% rename from test/rexml/data/broken.rss rename to test/data/broken.rss diff --git a/test/rexml/data/contents.xml b/test/data/contents.xml similarity index 100% rename from test/rexml/data/contents.xml rename to test/data/contents.xml diff --git a/test/rexml/data/dash.xml b/test/data/dash.xml similarity index 100% rename from test/rexml/data/dash.xml rename to test/data/dash.xml diff --git a/test/rexml/data/defaultNamespace.xml b/test/data/defaultNamespace.xml similarity index 100% rename from test/rexml/data/defaultNamespace.xml rename to test/data/defaultNamespace.xml diff --git a/test/rexml/data/doctype_test.xml b/test/data/doctype_test.xml similarity index 100% rename from test/rexml/data/doctype_test.xml rename to test/data/doctype_test.xml diff --git a/test/rexml/data/documentation.xml b/test/data/documentation.xml similarity index 100% rename from test/rexml/data/documentation.xml rename to test/data/documentation.xml diff --git a/test/rexml/data/euc.xml b/test/data/euc.xml similarity index 100% rename from test/rexml/data/euc.xml rename to test/data/euc.xml diff --git a/test/rexml/data/evaluate.xml b/test/data/evaluate.xml similarity index 100% rename from test/rexml/data/evaluate.xml rename to test/data/evaluate.xml diff --git a/test/rexml/data/fibo.xml b/test/data/fibo.xml similarity index 100% rename from test/rexml/data/fibo.xml rename to test/data/fibo.xml diff --git a/test/rexml/data/foo.xml b/test/data/foo.xml similarity index 100% rename from test/rexml/data/foo.xml rename to test/data/foo.xml diff --git a/test/rexml/data/google.2.xml b/test/data/google.2.xml similarity index 100% rename from test/rexml/data/google.2.xml rename to test/data/google.2.xml diff --git a/test/rexml/data/id.xml b/test/data/id.xml similarity index 100% rename from test/rexml/data/id.xml rename to test/data/id.xml diff --git a/test/rexml/data/iso8859-1.xml b/test/data/iso8859-1.xml similarity index 100% rename from test/rexml/data/iso8859-1.xml rename to test/data/iso8859-1.xml diff --git a/test/rexml/data/jaxen24.xml b/test/data/jaxen24.xml similarity index 100% rename from test/rexml/data/jaxen24.xml rename to test/data/jaxen24.xml diff --git a/test/rexml/data/jaxen3.xml b/test/data/jaxen3.xml similarity index 100% rename from test/rexml/data/jaxen3.xml rename to test/data/jaxen3.xml diff --git a/test/rexml/data/lang.xml b/test/data/lang.xml similarity index 100% rename from test/rexml/data/lang.xml rename to test/data/lang.xml diff --git a/test/rexml/data/lang0.xml b/test/data/lang0.xml similarity index 100% rename from test/rexml/data/lang0.xml rename to test/data/lang0.xml diff --git a/test/rexml/data/message.xml b/test/data/message.xml similarity index 100% rename from test/rexml/data/message.xml rename to test/data/message.xml diff --git a/test/rexml/data/moreover.xml b/test/data/moreover.xml similarity index 100% rename from test/rexml/data/moreover.xml rename to test/data/moreover.xml diff --git a/test/rexml/data/much_ado.xml b/test/data/much_ado.xml similarity index 100% rename from test/rexml/data/much_ado.xml rename to test/data/much_ado.xml diff --git a/test/rexml/data/namespaces.xml b/test/data/namespaces.xml similarity index 100% rename from test/rexml/data/namespaces.xml rename to test/data/namespaces.xml diff --git a/test/rexml/data/nitf.xml b/test/data/nitf.xml similarity index 100% rename from test/rexml/data/nitf.xml rename to test/data/nitf.xml diff --git a/test/rexml/data/numbers.xml b/test/data/numbers.xml similarity index 100% rename from test/rexml/data/numbers.xml rename to test/data/numbers.xml diff --git a/test/rexml/data/ofbiz-issues-full-177.xml b/test/data/ofbiz-issues-full-177.xml similarity index 100% rename from test/rexml/data/ofbiz-issues-full-177.xml rename to test/data/ofbiz-issues-full-177.xml diff --git a/test/rexml/data/pi.xml b/test/data/pi.xml similarity index 100% rename from test/rexml/data/pi.xml rename to test/data/pi.xml diff --git a/test/rexml/data/pi2.xml b/test/data/pi2.xml similarity index 100% rename from test/rexml/data/pi2.xml rename to test/data/pi2.xml diff --git a/test/rexml/data/project.xml b/test/data/project.xml similarity index 100% rename from test/rexml/data/project.xml rename to test/data/project.xml diff --git a/test/rexml/data/simple.xml b/test/data/simple.xml similarity index 100% rename from test/rexml/data/simple.xml rename to test/data/simple.xml diff --git a/test/rexml/data/stream_accents.xml b/test/data/stream_accents.xml similarity index 100% rename from test/rexml/data/stream_accents.xml rename to test/data/stream_accents.xml diff --git a/test/rexml/data/t63-1.xml b/test/data/t63-1.xml similarity index 100% rename from test/rexml/data/t63-1.xml rename to test/data/t63-1.xml diff --git a/test/rexml/data/t63-2.svg b/test/data/t63-2.svg similarity index 100% rename from test/rexml/data/t63-2.svg rename to test/data/t63-2.svg diff --git a/test/rexml/data/t75.xml b/test/data/t75.xml similarity index 100% rename from test/rexml/data/t75.xml rename to test/data/t75.xml diff --git a/test/rexml/data/test/tests.xml b/test/data/test/tests.xml similarity index 100% rename from test/rexml/data/test/tests.xml rename to test/data/test/tests.xml diff --git a/test/rexml/data/test/tests.xsl b/test/data/test/tests.xsl similarity index 100% rename from test/rexml/data/test/tests.xsl rename to test/data/test/tests.xsl diff --git a/test/rexml/data/testNamespaces.xml b/test/data/testNamespaces.xml similarity index 100% rename from test/rexml/data/testNamespaces.xml rename to test/data/testNamespaces.xml diff --git a/test/rexml/data/testsrc.xml b/test/data/testsrc.xml similarity index 100% rename from test/rexml/data/testsrc.xml rename to test/data/testsrc.xml diff --git a/test/rexml/data/text.xml b/test/data/text.xml similarity index 100% rename from test/rexml/data/text.xml rename to test/data/text.xml diff --git a/test/rexml/data/ticket_61.xml b/test/data/ticket_61.xml similarity index 100% rename from test/rexml/data/ticket_61.xml rename to test/data/ticket_61.xml diff --git a/test/rexml/data/ticket_68.xml b/test/data/ticket_68.xml similarity index 100% rename from test/rexml/data/ticket_68.xml rename to test/data/ticket_68.xml diff --git a/test/rexml/data/tutorial.xml b/test/data/tutorial.xml similarity index 100% rename from test/rexml/data/tutorial.xml rename to test/data/tutorial.xml diff --git a/test/rexml/data/underscore.xml b/test/data/underscore.xml similarity index 100% rename from test/rexml/data/underscore.xml rename to test/data/underscore.xml diff --git a/test/rexml/data/utf16.xml b/test/data/utf16.xml similarity index 100% rename from test/rexml/data/utf16.xml rename to test/data/utf16.xml diff --git a/test/rexml/data/web.xml b/test/data/web.xml similarity index 100% rename from test/rexml/data/web.xml rename to test/data/web.xml diff --git a/test/rexml/data/web2.xml b/test/data/web2.xml similarity index 100% rename from test/rexml/data/web2.xml rename to test/data/web2.xml diff --git a/test/rexml/data/working.rss b/test/data/working.rss similarity index 100% rename from test/rexml/data/working.rss rename to test/data/working.rss diff --git a/test/rexml/data/xmlfile-bug.xml b/test/data/xmlfile-bug.xml similarity index 100% rename from test/rexml/data/xmlfile-bug.xml rename to test/data/xmlfile-bug.xml diff --git a/test/rexml/data/xp.tst b/test/data/xp.tst similarity index 100% rename from test/rexml/data/xp.tst rename to test/data/xp.tst diff --git a/test/rexml/data/yahoo.xml b/test/data/yahoo.xml similarity index 100% rename from test/rexml/data/yahoo.xml rename to test/data/yahoo.xml diff --git a/test/rexml/formatter/test_default.rb b/test/formatter/test_default.rb similarity index 91% rename from test/rexml/formatter/test_default.rb rename to test/formatter/test_default.rb index b5b13172..321d8180 100644 --- a/test/rexml/formatter/test_default.rb +++ b/test/formatter/test_default.rb @@ -1,5 +1,3 @@ -require_relative "../rexml_test_utils" - module REXMLTests class DefaultFormatterTest < Test::Unit::TestCase def format(node) diff --git a/test/rexml/functions/test_base.rb b/test/functions/test_base.rb similarity index 100% rename from test/rexml/functions/test_base.rb rename to test/functions/test_base.rb diff --git a/test/rexml/functions/test_boolean.rb b/test/functions/test_boolean.rb similarity index 100% rename from test/rexml/functions/test_boolean.rb rename to test/functions/test_boolean.rb diff --git a/test/rexml/functions/test_local_name.rb b/test/functions/test_local_name.rb similarity index 100% rename from test/rexml/functions/test_local_name.rb rename to test/functions/test_local_name.rb diff --git a/test/rexml/functions/test_number.rb b/test/functions/test_number.rb similarity index 100% rename from test/rexml/functions/test_number.rb rename to test/functions/test_number.rb diff --git a/test/helper.rb b/test/helper.rb new file mode 100644 index 00000000..3de13276 --- /dev/null +++ b/test/helper.rb @@ -0,0 +1,35 @@ +# frozen_string_literal: false + +require "test-unit" + +require "rexml/document" + +module Helper + module Fixture + def fixture_path(*components) + File.join(__dir__, "data", *components) + end + end + + module Global + def suppress_warning + verbose = $VERBOSE + begin + $VERBOSE = nil + yield + ensure + $VERBOSE = verbose + end + end + + def with_default_internal(encoding) + default_internal = Encoding.default_internal + begin + suppress_warning {Encoding.default_internal = encoding} + yield + ensure + suppress_warning {Encoding.default_internal = default_internal} + end + end + end +end diff --git a/test/lib/envutil.rb b/test/lib/envutil.rb deleted file mode 100644 index 5d3bce99..00000000 --- a/test/lib/envutil.rb +++ /dev/null @@ -1,298 +0,0 @@ -# -*- coding: us-ascii -*- -# frozen_string_literal: true -require "open3" -require "timeout" -require_relative "find_executable" -begin - require 'rbconfig' -rescue LoadError -end -begin - require "rbconfig/sizeof" -rescue LoadError -end - -module EnvUtil - def rubybin - if ruby = ENV["RUBY"] - return ruby - end - ruby = "ruby" - exeext = RbConfig::CONFIG["EXEEXT"] - rubyexe = (ruby + exeext if exeext and !exeext.empty?) - 3.times do - if File.exist? ruby and File.executable? ruby and !File.directory? ruby - return File.expand_path(ruby) - end - if rubyexe and File.exist? rubyexe and File.executable? rubyexe - return File.expand_path(rubyexe) - end - ruby = File.join("..", ruby) - end - if defined?(RbConfig.ruby) - RbConfig.ruby - else - "ruby" - end - end - module_function :rubybin - - LANG_ENVS = %w"LANG LC_ALL LC_CTYPE" - - DEFAULT_SIGNALS = Signal.list - DEFAULT_SIGNALS.delete("TERM") if /mswin|mingw/ =~ RUBY_PLATFORM - - RUBYLIB = ENV["RUBYLIB"] - - class << self - attr_accessor :subprocess_timeout_scale - attr_reader :original_internal_encoding, :original_external_encoding, - :original_verbose - - def capture_global_values - @original_internal_encoding = Encoding.default_internal - @original_external_encoding = Encoding.default_external - @original_verbose = $VERBOSE - end - end - - def apply_timeout_scale(t) - if scale = EnvUtil.subprocess_timeout_scale - t * scale - else - t - end - end - module_function :apply_timeout_scale - - def invoke_ruby(args, stdin_data = "", capture_stdout = false, capture_stderr = false, - encoding: nil, timeout: 10, reprieve: 1, timeout_error: Timeout::Error, - stdout_filter: nil, stderr_filter: nil, - signal: :TERM, - rubybin: EnvUtil.rubybin, precommand: nil, - **opt) - timeout = apply_timeout_scale(timeout) - reprieve = apply_timeout_scale(reprieve) if reprieve - - in_c, in_p = IO.pipe - out_p, out_c = IO.pipe if capture_stdout - err_p, err_c = IO.pipe if capture_stderr && capture_stderr != :merge_to_stdout - opt[:in] = in_c - opt[:out] = out_c if capture_stdout - opt[:err] = capture_stderr == :merge_to_stdout ? out_c : err_c if capture_stderr - if encoding - out_p.set_encoding(encoding) if out_p - err_p.set_encoding(encoding) if err_p - end - c = "C" - child_env = {} - LANG_ENVS.each {|lc| child_env[lc] = c} - if Array === args and Hash === args.first - child_env.update(args.shift) - end - if RUBYLIB and lib = child_env["RUBYLIB"] - child_env["RUBYLIB"] = [lib, RUBYLIB].join(File::PATH_SEPARATOR) - end - args = [args] if args.kind_of?(String) - pid = spawn(child_env, *precommand, rubybin, *args, **opt) - in_c.close - out_c.close if capture_stdout - err_c.close if capture_stderr && capture_stderr != :merge_to_stdout - if block_given? - return yield in_p, out_p, err_p, pid - else - th_stdout = Thread.new { out_p.read } if capture_stdout - th_stderr = Thread.new { err_p.read } if capture_stderr && capture_stderr != :merge_to_stdout - in_p.write stdin_data.to_str unless stdin_data.empty? - in_p.close - if (!th_stdout || th_stdout.join(timeout)) && (!th_stderr || th_stderr.join(timeout)) - timeout_error = nil - else - signals = Array(signal).select do |sig| - DEFAULT_SIGNALS[sig.to_s] or - DEFAULT_SIGNALS[Signal.signame(sig)] rescue false - end - signals |= [:ABRT, :KILL] - case pgroup = opt[:pgroup] - when 0, true - pgroup = -pid - when nil, false - pgroup = pid - end - while signal = signals.shift - begin - Process.kill signal, pgroup - rescue Errno::EINVAL - next - rescue Errno::ESRCH - break - end - if signals.empty? or !reprieve - Process.wait(pid) - else - begin - Timeout.timeout(reprieve) {Process.wait(pid)} - rescue Timeout::Error - end - end - end - status = $? - end - stdout = th_stdout.value if capture_stdout - stderr = th_stderr.value if capture_stderr && capture_stderr != :merge_to_stdout - out_p.close if capture_stdout - err_p.close if capture_stderr && capture_stderr != :merge_to_stdout - status ||= Process.wait2(pid)[1] - stdout = stdout_filter.call(stdout) if stdout_filter - stderr = stderr_filter.call(stderr) if stderr_filter - if timeout_error - bt = caller_locations - msg = "execution of #{bt.shift.label} expired timeout (#{timeout} sec)" - msg = Test::Unit::Assertions::FailDesc[status, msg, [stdout, stderr].join("\n")].() - raise timeout_error, msg, bt.map(&:to_s) - end - return stdout, stderr, status - end - ensure - [th_stdout, th_stderr].each do |th| - th.kill if th - end - [in_c, in_p, out_c, out_p, err_c, err_p].each do |io| - io&.close - end - [th_stdout, th_stderr].each do |th| - th.join if th - end - end - module_function :invoke_ruby - - alias rubyexec invoke_ruby - class << self - alias rubyexec invoke_ruby - end - - def verbose_warning - class << (stderr = "".dup) - alias write concat - def flush; end - end - stderr, $stderr = $stderr, stderr - $VERBOSE = true - yield stderr - return $stderr - ensure - stderr, $stderr = $stderr, stderr - $VERBOSE = EnvUtil.original_verbose - end - module_function :verbose_warning - - def default_warning - $VERBOSE = false - yield - ensure - $VERBOSE = EnvUtil.original_verbose - end - module_function :default_warning - - def suppress_warning - $VERBOSE = nil - yield - ensure - $VERBOSE = EnvUtil.original_verbose - end - module_function :suppress_warning - - def under_gc_stress(stress = true) - stress, GC.stress = GC.stress, stress - yield - ensure - GC.stress = stress - end - module_function :under_gc_stress - - def with_default_external(enc) - suppress_warning { Encoding.default_external = enc } - yield - ensure - suppress_warning { Encoding.default_external = EnvUtil.original_external_encoding } - end - module_function :with_default_external - - def with_default_internal(enc) - suppress_warning { Encoding.default_internal = enc } - yield - ensure - suppress_warning { Encoding.default_internal = EnvUtil.original_internal_encoding } - end - module_function :with_default_internal - - def labeled_module(name, &block) - Module.new do - singleton_class.class_eval {define_method(:to_s) {name}; alias inspect to_s} - class_eval(&block) if block - end - end - module_function :labeled_module - - def labeled_class(name, superclass = Object, &block) - Class.new(superclass) do - singleton_class.class_eval {define_method(:to_s) {name}; alias inspect to_s} - class_eval(&block) if block - end - end - module_function :labeled_class - - if /darwin/ =~ RUBY_PLATFORM - DIAGNOSTIC_REPORTS_PATH = File.expand_path("~/Library/Logs/DiagnosticReports") - DIAGNOSTIC_REPORTS_TIMEFORMAT = '%Y-%m-%d-%H%M%S' - @ruby_install_name = RbConfig::CONFIG['RUBY_INSTALL_NAME'] - - def self.diagnostic_reports(signame, pid, now) - return unless %w[ABRT QUIT SEGV ILL TRAP].include?(signame) - cmd = File.basename(rubybin) - cmd = @ruby_install_name if "ruby-runner#{RbConfig::CONFIG["EXEEXT"]}" == cmd - path = DIAGNOSTIC_REPORTS_PATH - timeformat = DIAGNOSTIC_REPORTS_TIMEFORMAT - pat = "#{path}/#{cmd}_#{now.strftime(timeformat)}[-_]*.crash" - first = true - 30.times do - first ? (first = false) : sleep(0.1) - Dir.glob(pat) do |name| - log = File.read(name) rescue next - if /\AProcess:\s+#{cmd} \[#{pid}\]$/ =~ log - File.unlink(name) - File.unlink("#{path}/.#{File.basename(name)}.plist") rescue nil - return log - end - end - end - nil - end - else - def self.diagnostic_reports(signame, pid, now) - end - end - - def self.gc_stress_to_class? - unless defined?(@gc_stress_to_class) - _, _, status = invoke_ruby(["-e""exit GC.respond_to?(:add_stress_to_class)"]) - @gc_stress_to_class = status.success? - end - @gc_stress_to_class - end -end - -if defined?(RbConfig) - module RbConfig - @ruby = EnvUtil.rubybin - class << self - undef ruby if method_defined?(:ruby) - attr_reader :ruby - end - dir = File.dirname(ruby) - CONFIG['bindir'] = dir - Gem::ConfigMap[:bindir] = dir if defined?(Gem::ConfigMap) - end -end - -EnvUtil.capture_global_values diff --git a/test/lib/find_executable.rb b/test/lib/find_executable.rb deleted file mode 100644 index 89c6fb8f..00000000 --- a/test/lib/find_executable.rb +++ /dev/null @@ -1,22 +0,0 @@ -# frozen_string_literal: true -require "rbconfig" - -module EnvUtil - def find_executable(cmd, *args) - exts = RbConfig::CONFIG["EXECUTABLE_EXTS"].split | [RbConfig::CONFIG["EXEEXT"]] - ENV["PATH"].split(File::PATH_SEPARATOR).each do |path| - next if path.empty? - path = File.join(path, cmd) - exts.each do |ext| - cmdline = [path + ext, *args] - begin - return cmdline if yield(IO.popen(cmdline, "r", err: [:child, :out], &:read)) - rescue - next - end - end - end - nil - end - module_function :find_executable -end diff --git a/test/lib/iseq_loader_checker.rb b/test/lib/iseq_loader_checker.rb deleted file mode 100644 index 1a1a6948..00000000 --- a/test/lib/iseq_loader_checker.rb +++ /dev/null @@ -1,75 +0,0 @@ -# frozen_string_literal: true - -begin - require '-test-/iseq_load/iseq_load' -rescue LoadError -end -require 'tempfile' - -class RubyVM::InstructionSequence - def disasm_if_possible - begin - self.disasm - rescue Encoding::CompatibilityError, EncodingError, SecurityError - nil - end - end - - def self.compare_dump_and_load i1, dumper, loader - dump = dumper.call(i1) - return i1 unless dump - i2 = loader.call(dump) - - # compare disassembled result - d1 = i1.disasm_if_possible - d2 = i2.disasm_if_possible - - if d1 != d2 - STDERR.puts "expected:" - STDERR.puts d1 - STDERR.puts "actual:" - STDERR.puts d2 - - t1 = Tempfile.new("expected"); t1.puts d1; t1.close - t2 = Tempfile.new("actual"); t2.puts d2; t2.close - system("diff -u #{t1.path} #{t2.path}") # use diff if available - exit(1) - end - i2 - end - - CHECK_TO_A = ENV['RUBY_ISEQ_DUMP_DEBUG'] == 'to_a' - CHECK_TO_BINARY = ENV['RUBY_ISEQ_DUMP_DEBUG'] == 'to_binary' - - def self.translate i1 - # check to_a/load_iseq - compare_dump_and_load(i1, - proc{|iseq| - ary = iseq.to_a - ary[9] == :top ? ary : nil - }, - proc{|ary| - RubyVM::InstructionSequence.iseq_load(ary) - }) if CHECK_TO_A && defined?(RubyVM::InstructionSequence.iseq_load) - - # check to_binary - i2_bin = compare_dump_and_load(i1, - proc{|iseq| - begin - iseq.to_binary - rescue RuntimeError # not a toplevel - # STDERR.puts [:failed, $!, iseq].inspect - nil - end - }, - proc{|bin| - iseq = RubyVM::InstructionSequence.load_from_binary(bin) - # STDERR.puts iseq.inspect - iseq - }) if CHECK_TO_BINARY - # return value - i2_bin if CHECK_TO_BINARY - end if CHECK_TO_A || CHECK_TO_BINARY -end - -#require_relative 'x'; exit(1) diff --git a/test/lib/jit_support.rb b/test/lib/jit_support.rb deleted file mode 100644 index 0759a664..00000000 --- a/test/lib/jit_support.rb +++ /dev/null @@ -1,57 +0,0 @@ -module JITSupport - JIT_TIMEOUT = 600 # 10min for each... - JIT_SUCCESS_PREFIX = 'JIT success \(\d+\.\dms\)' - SUPPORTED_COMPILERS = [ - 'gcc', - 'clang', - ] - - def self.check_support - # Experimental. If you want to ensure JIT is working with this test, please set this for now. - if ENV.key?('RUBY_FORCE_TEST_JIT') - return true - end - - # Very pessimistic check. With this check, we can't ensure JIT is working. - begin - _, err = JITSupport.eval_with_jit('proc {}.call', verbose: 1, min_calls: 1, timeout: 10) - rescue Timeout::Error - $stderr.puts "TestJIT: #jit_supported? check timed out" - false - else - err.match?(JIT_SUCCESS_PREFIX).tap do |success| - unless success - $stderr.puts "TestJIT.check_support stderr:\n```\n#{err}\n```\n" - end - end - end - end - - module_function - def eval_with_jit(env = nil, script, verbose: 0, min_calls: 5, save_temps: false, timeout: JIT_TIMEOUT) - args = ['--disable-gems', '--jit-wait', "--jit-verbose=#{verbose}", "--jit-min-calls=#{min_calls}"] - args << '--jit-save-temps' if save_temps - args << '-e' << script - args.unshift(env) if env - EnvUtil.invoke_ruby(args, - '', true, true, timeout: timeout, - ) - end - - def supported? - return @supported if defined?(@supported) - @supported = JITSupport.check_support.tap do |supported| - unless supported - warn "JIT tests are skiped since JIT seems not working. Set RUBY_FORCE_TEST_JIT=1 to let it fail.", uplevel: 1 - end - end - end - - def remove_mjit_logs(stderr) - if RubyVM::MJIT.enabled? - stderr.gsub(/^MJIT warning: Skipped to compile unsupported instruction: \w+\n/m, '') - else - stderr - end - end -end diff --git a/test/lib/leakchecker.rb b/test/lib/leakchecker.rb deleted file mode 100644 index 325ca8d0..00000000 --- a/test/lib/leakchecker.rb +++ /dev/null @@ -1,244 +0,0 @@ -# frozen_string_literal: true -class LeakChecker - def initialize - @fd_info = find_fds - @tempfile_info = find_tempfiles - @thread_info = find_threads - @env_info = find_env - @encoding_info = find_encodings - @old_verbose = $VERBOSE - end - - def check(test_name) - leaks = [ - check_fd_leak(test_name), - check_thread_leak(test_name), - check_tempfile_leak(test_name), - check_env(test_name), - check_encodings(test_name), - check_safe(test_name), - check_verbose(test_name), - ] - GC.start if leaks.any? - end - - def check_safe test_name - verbose, $VERBOSE = $VERBOSE, nil - return unless defined?($SAFE) - puts "#{test_name}: $SAFE == #{$SAFE}" unless $SAFE == 0 - ensure - $VERBOSE = verbose - end - - def check_verbose test_name - puts "#{test_name}: $VERBOSE == #{$VERBOSE}" unless @old_verbose == $VERBOSE - end - - def find_fds - if IO.respond_to?(:console) and (m = IO.method(:console)).arity.nonzero? - m[:close] - end - fd_dir = "/proc/self/fd" - if File.directory?(fd_dir) - fds = Dir.open(fd_dir) {|d| - a = d.grep(/\A\d+\z/, &:to_i) - if d.respond_to? :fileno - a -= [d.fileno] - end - a - } - fds.sort - else - [] - end - end - - def check_fd_leak(test_name) - leaked = false - live1 = @fd_info - live2 = find_fds - fd_closed = live1 - live2 - if !fd_closed.empty? - fd_closed.each {|fd| - puts "Closed file descriptor: #{test_name}: #{fd}" - } - end - fd_leaked = live2 - live1 - if !fd_leaked.empty? - leaked = true - h = {} - ObjectSpace.each_object(IO) {|io| - inspect = io.inspect - begin - autoclose = io.autoclose? - fd = io.fileno - rescue IOError # closed IO object - next - end - (h[fd] ||= []) << [io, autoclose, inspect] - } - fd_leaked.each {|fd| - str = ''.dup - if h[fd] - str << ' :' - h[fd].map {|io, autoclose, inspect| - s = ' ' + inspect - s << "(not-autoclose)" if !autoclose - s - }.sort.each {|s| - str << s - } - end - puts "Leaked file descriptor: #{test_name}: #{fd}#{str}" - } - #system("lsof -p #$$") if !fd_leaked.empty? - h.each {|fd, list| - next if list.length <= 1 - if 1 < list.count {|io, autoclose, inspect| autoclose } - str = list.map {|io, autoclose, inspect| " #{inspect}" + (autoclose ? "(autoclose)" : "") }.sort.join - puts "Multiple autoclose IO object for a file descriptor:#{str}" - end - } - end - @fd_info = live2 - return leaked - end - - def extend_tempfile_counter - return if defined? LeakChecker::TempfileCounter - m = Module.new { - @count = 0 - class << self - attr_accessor :count - end - - def new(data) - LeakChecker::TempfileCounter.count += 1 - super(data) - end - } - LeakChecker.const_set(:TempfileCounter, m) - - class << Tempfile::Remover - prepend LeakChecker::TempfileCounter - end - end - - def find_tempfiles(prev_count=-1) - return [prev_count, []] unless defined? Tempfile - extend_tempfile_counter - count = TempfileCounter.count - if prev_count == count - [prev_count, []] - else - tempfiles = ObjectSpace.each_object(Tempfile).find_all {|t| - t.instance_variable_defined?(:@tmpfile) and t.path - } - [count, tempfiles] - end - end - - def check_tempfile_leak(test_name) - return false unless defined? Tempfile - count1, initial_tempfiles = @tempfile_info - count2, current_tempfiles = find_tempfiles(count1) - leaked = false - tempfiles_leaked = current_tempfiles - initial_tempfiles - if !tempfiles_leaked.empty? - leaked = true - list = tempfiles_leaked.map {|t| t.inspect }.sort - list.each {|str| - puts "Leaked tempfile: #{test_name}: #{str}" - } - tempfiles_leaked.each {|t| t.close! } - end - @tempfile_info = [count2, initial_tempfiles] - return leaked - end - - def find_threads - Thread.list.find_all {|t| - t != Thread.current && t.alive? - } - end - - def check_thread_leak(test_name) - live1 = @thread_info - live2 = find_threads - thread_finished = live1 - live2 - leaked = false - if !thread_finished.empty? - list = thread_finished.map {|t| t.inspect }.sort - list.each {|str| - puts "Finished thread: #{test_name}: #{str}" - } - end - thread_leaked = live2 - live1 - if !thread_leaked.empty? - leaked = true - list = thread_leaked.map {|t| t.inspect }.sort - list.each {|str| - puts "Leaked thread: #{test_name}: #{str}" - } - end - @thread_info = live2 - return leaked - end - - def find_env - ENV.to_h - end - - def check_env(test_name) - old_env = @env_info - new_env = ENV.to_h - return false if old_env == new_env - (old_env.keys | new_env.keys).sort.each {|k| - if old_env.has_key?(k) - if new_env.has_key?(k) - if old_env[k] != new_env[k] - puts "Environment variable changed: #{test_name} : #{k.inspect} changed : #{old_env[k].inspect} -> #{new_env[k].inspect}" - end - else - puts "Environment variable changed: #{test_name} : #{k.inspect} deleted" - end - else - if new_env.has_key?(k) - puts "Environment variable changed: #{test_name} : #{k.inspect} added" - else - flunk "unreachable" - end - end - } - @env_info = new_env - return true - end - - def find_encodings - [Encoding.default_internal, Encoding.default_external] - end - - def check_encodings(test_name) - old_internal, old_external = @encoding_info - new_internal, new_external = find_encodings - leaked = false - if new_internal != old_internal - leaked = true - puts "Encoding.default_internal changed: #{test_name} : #{old_internal.inspect} to #{new_internal.inspect}" - end - if new_external != old_external - leaked = true - puts "Encoding.default_external changed: #{test_name} : #{old_external.inspect} to #{new_external.inspect}" - end - @encoding_info = [new_internal, new_external] - return leaked - end - - def puts(*a) - output = MiniTest::Unit.output - if defined?(output.set_encoding) - output.set_encoding(nil, nil) - end - output.puts(*a) - end -end diff --git a/test/lib/memory_status.rb b/test/lib/memory_status.rb deleted file mode 100644 index ad002b2d..00000000 --- a/test/lib/memory_status.rb +++ /dev/null @@ -1,149 +0,0 @@ -# frozen_string_literal: true -begin - require '-test-/memory_status.so' -rescue LoadError -end - -module Memory - keys = [] - - case - when File.exist?(procfile = "/proc/self/status") && (pat = /^Vm(\w+):\s+(\d+)/) =~ (data = File.binread(procfile)) - PROC_FILE = procfile - VM_PAT = pat - def self.read_status - IO.foreach(PROC_FILE, encoding: Encoding::ASCII_8BIT) do |l| - yield($1.downcase.intern, $2.to_i * 1024) if VM_PAT =~ l - end - end - - data.scan(pat) {|k, v| keys << k.downcase.intern} - - when /mswin|mingw/ =~ RUBY_PLATFORM - require 'fiddle/import' - require 'fiddle/types' - - module Win32 - extend Fiddle::Importer - dlload "kernel32.dll", "psapi.dll" - include Fiddle::Win32Types - typealias "SIZE_T", "size_t" - - PROCESS_MEMORY_COUNTERS = struct [ - "DWORD cb", - "DWORD PageFaultCount", - "SIZE_T PeakWorkingSetSize", - "SIZE_T WorkingSetSize", - "SIZE_T QuotaPeakPagedPoolUsage", - "SIZE_T QuotaPagedPoolUsage", - "SIZE_T QuotaPeakNonPagedPoolUsage", - "SIZE_T QuotaNonPagedPoolUsage", - "SIZE_T PagefileUsage", - "SIZE_T PeakPagefileUsage", - ] - - typealias "PPROCESS_MEMORY_COUNTERS", "PROCESS_MEMORY_COUNTERS*" - - extern "HANDLE GetCurrentProcess()", :stdcall - extern "BOOL GetProcessMemoryInfo(HANDLE, PPROCESS_MEMORY_COUNTERS, DWORD)", :stdcall - - module_function - def memory_info - size = PROCESS_MEMORY_COUNTERS.size - data = PROCESS_MEMORY_COUNTERS.malloc - data.cb = size - data if GetProcessMemoryInfo(GetCurrentProcess(), data, size) - end - end - - keys << :peak << :size - def self.read_status - if info = Win32.memory_info - yield :peak, info.PeakPagefileUsage - yield :size, info.PagefileUsage - end - end - when (require_relative 'find_executable' - pat = /^\s*(\d+)\s+(\d+)$/ - pscmd = EnvUtil.find_executable("ps", "-ovsz=", "-orss=", "-p", $$.to_s) {|out| pat =~ out}) - pscmd.pop - PAT = pat - PSCMD = pscmd - - keys << :size << :rss - def self.read_status - if PAT =~ IO.popen(PSCMD + [$$.to_s], "r", err: [:child, :out], &:read) - yield :size, $1.to_i*1024 - yield :rss, $2.to_i*1024 - end - end - else - def self.read_status - raise NotImplementedError, "unsupported platform" - end - end - - if !keys.empty? - Status = Struct.new(*keys) - end -end unless defined?(Memory::Status) - -if defined?(Memory::Status) - class Memory::Status - def _update - Memory.read_status do |key, val| - self[key] = val - end - end unless method_defined?(:_update) - - Header = members.map {|k| k.to_s.upcase.rjust(6)}.join('') - Format = "%6d" - - def initialize - _update - end - - def to_s - status = each_pair.map {|n,v| - "#{n}:#{v}" - } - "{#{status.join(",")}}" - end - - def self.parse(str) - status = allocate - str.scan(/(?:\A\{|\G,)(#{members.join('|')}):(\d+)(?=,|\}\z)/) do - status[$1] = $2.to_i - end - status - end - end - - # On some platforms (e.g. Solaris), libc malloc does not return - # freed memory to OS because of efficiency, and linking with extra - # malloc library is needed to detect memory leaks. - # - case RUBY_PLATFORM - when /solaris2\.(?:9|[1-9][0-9])/i # Solaris 9, 10, 11,... - bits = [nil].pack('p').size == 8 ? 64 : 32 - if ENV['LD_PRELOAD'].to_s.empty? && - ENV["LD_PRELOAD_#{bits}"].to_s.empty? && - (ENV['UMEM_OPTIONS'].to_s.empty? || - ENV['UMEM_OPTIONS'] == 'backend=mmap') then - envs = { - 'LD_PRELOAD' => 'libumem.so', - 'UMEM_OPTIONS' => 'backend=mmap' - } - args = [ - envs, - "--disable=gems", - "-v", "-", - ] - _, err, status = EnvUtil.invoke_ruby(args, "exit(0)", true, true) - if status.exitstatus == 0 && err.to_s.empty? then - Memory::NO_MEMORY_LEAK_ENVS = envs - end - end - end #case RUBY_PLATFORM - -end diff --git a/test/lib/minitest/README.txt b/test/lib/minitest/README.txt deleted file mode 100644 index 368cc3aa..00000000 --- a/test/lib/minitest/README.txt +++ /dev/null @@ -1,457 +0,0 @@ -= minitest/{unit,spec,mock,benchmark} - -home :: https://github.com/seattlerb/minitest -rdoc :: http://docs.seattlerb.org/minitest -vim :: https://github.com/sunaku/vim-ruby-minitest - -== DESCRIPTION: - -minitest provides a complete suite of testing facilities supporting -TDD, BDD, mocking, and benchmarking. - - "I had a class with Jim Weirich on testing last week and we were - allowed to choose our testing frameworks. Kirk Haines and I were - paired up and we cracked open the code for a few test - frameworks... - - I MUST say that minitest is *very* readable / understandable - compared to the 'other two' options we looked at. Nicely done and - thank you for helping us keep our mental sanity." - - -- Wayne E. Seguin - -minitest/unit is a small and incredibly fast unit testing framework. -It provides a rich set of assertions to make your tests clean and -readable. - -minitest/spec is a functionally complete spec engine. It hooks onto -minitest/unit and seamlessly bridges test assertions over to spec -expectations. - -minitest/benchmark is an awesome way to assert the performance of your -algorithms in a repeatable manner. Now you can assert that your newb -co-worker doesn't replace your linear algorithm with an exponential -one! - -minitest/mock by Steven Baker, is a beautifully tiny mock (and stub) -object framework. - -minitest/pride shows pride in testing and adds coloring to your test -output. I guess it is an example of how to write IO pipes too. :P - -minitest/unit is meant to have a clean implementation for language -implementors that need a minimal set of methods to bootstrap a working -test suite. For example, there is no magic involved for test-case -discovery. - - "Again, I can't praise enough the idea of a testing/specing - framework that I can actually read in full in one sitting!" - - -- Piotr Szotkowski - -Comparing to rspec: - - rspec is a testing DSL. minitest is ruby. - - -- Adam Hawkins, "Bow Before MiniTest" - -minitest doesn't reinvent anything that ruby already provides, like: -classes, modules, inheritance, methods. This means you only have to -learn ruby to use minitest and all of your regular OO practices like -extract-method refactorings still apply. - -== FEATURES/PROBLEMS: - -* minitest/autorun - the easy and explicit way to run all your tests. -* minitest/unit - a very fast, simple, and clean test system. -* minitest/spec - a very fast, simple, and clean spec system. -* minitest/mock - a simple and clean mock/stub system. -* minitest/benchmark - an awesome way to assert your algorithm's performance. -* minitest/pride - show your pride in testing! -* Incredibly small and fast runner, but no bells and whistles. - -== RATIONALE: - -See design_rationale.rb to see how specs and tests work in minitest. - -== SYNOPSIS: - -Given that you'd like to test the following class: - - class Meme - def i_can_has_cheezburger? - "OHAI!" - end - - def will_it_blend? - "YES!" - end - end - -=== Unit tests - - require 'minitest/autorun' - - class TestMeme < MiniTest::Unit::TestCase - def setup - @meme = Meme.new - end - - def test_that_kitty_can_eat - assert_equal "OHAI!", @meme.i_can_has_cheezburger? - end - - def test_that_it_will_not_blend - refute_match /^no/i, @meme.will_it_blend? - end - - def test_that_will_be_skipped - skip "test this later" - end - end - -=== Specs - - require 'minitest/autorun' - - describe Meme do - before do - @meme = Meme.new - end - - describe "when asked about cheeseburgers" do - it "must respond positively" do - @meme.i_can_has_cheezburger?.must_equal "OHAI!" - end - end - - describe "when asked about blending possibilities" do - it "won't say no" do - @meme.will_it_blend?.wont_match /^no/i - end - end - end - -For matchers support check out: - -https://github.com/zenspider/minitest-matchers - -=== Benchmarks - -Add benchmarks to your regular unit tests. If the unit tests fail, the -benchmarks won't run. - - # optionally run benchmarks, good for CI-only work! - require 'minitest/benchmark' if ENV["BENCH"] - - class TestMeme < MiniTest::Unit::TestCase - # Override self.bench_range or default range is [1, 10, 100, 1_000, 10_000] - def bench_my_algorithm - assert_performance_linear 0.9999 do |n| # n is a range value - @obj.my_algorithm(n) - end - end - end - -Or add them to your specs. If you make benchmarks optional, you'll -need to wrap your benchmarks in a conditional since the methods won't -be defined. - - describe Meme do - if ENV["BENCH"] then - bench_performance_linear "my_algorithm", 0.9999 do |n| - 100.times do - @obj.my_algorithm(n) - end - end - end - end - -outputs something like: - - # Running benchmarks: - - TestBlah 100 1000 10000 - bench_my_algorithm 0.006167 0.079279 0.786993 - bench_other_algorithm 0.061679 0.792797 7.869932 - -Output is tab-delimited to make it easy to paste into a spreadsheet. - -=== Mocks - - class MemeAsker - def initialize(meme) - @meme = meme - end - - def ask(question) - method = question.tr(" ","_") + "?" - @meme.__send__(method) - end - end - - require 'minitest/autorun' - - describe MemeAsker do - before do - @meme = MiniTest::Mock.new - @meme_asker = MemeAsker.new @meme - end - - describe "#ask" do - describe "when passed an unpunctuated question" do - it "should invoke the appropriate predicate method on the meme" do - @meme.expect :will_it_blend?, :return_value - @meme_asker.ask "will it blend" - @meme.verify - end - end - end - end - -=== Stubs - - def test_stale_eh - obj_under_test = Something.new - - refute obj_under_test.stale? - - Time.stub :now, Time.at(0) do # stub goes away once the block is done - assert obj_under_test.stale? - end - end - -A note on stubbing: In order to stub a method, the method must -actually exist prior to stubbing. Use a singleton method to create a -new non-existing method: - - def obj_under_test.fake_method - ... - end - -=== Customizable Test Runner Types: - -MiniTest::Unit.runner=(runner) provides an easy way of creating custom -test runners for specialized needs. Justin Weiss provides the -following real-world example to create an alternative to regular -fixture loading: - - class MiniTestWithHooks::Unit < MiniTest::Unit - def before_suites - end - - def after_suites - end - - def _run_suites(suites, type) - begin - before_suites - super(suites, type) - ensure - after_suites - end - end - - def _run_suite(suite, type) - begin - suite.before_suite - super(suite, type) - ensure - suite.after_suite - end - end - end - - module MiniTestWithTransactions - class Unit < MiniTestWithHooks::Unit - include TestSetupHelper - - def before_suites - super - setup_nested_transactions - # load any data we want available for all tests - end - - def after_suites - teardown_nested_transactions - super - end - end - end - - MiniTest::Unit.runner = MiniTestWithTransactions::Unit.new - -== FAQ - -=== How to test SimpleDelegates? - -The following implementation and test: - - class Worker < SimpleDelegator - def work - end - end - - describe Worker do - before do - @worker = Worker.new(Object.new) - end - - it "must respond to work" do - @worker.must_respond_to :work - end - end - -outputs a failure: - - 1) Failure: - Worker#test_0001_must respond to work [bug11.rb:16]: - Expected # (Object) to respond to #work. - -Worker is a SimpleDelegate which in 1.9+ is a subclass of BasicObject. -Expectations are put on Object (one level down) so the Worker -(SimpleDelegate) hits `method_missing` and delegates down to the -`Object.new` instance. That object doesn't respond to work so the test -fails. - -You can bypass `SimpleDelegate#method_missing` by extending the worker -with `MiniTest::Expectations`. You can either do that in your setup at -the instance level, like: - - before do - @worker = Worker.new(Object.new) - @worker.extend MiniTest::Expectations - end - -or you can extend the Worker class (within the test file!), like: - - class Worker - include ::MiniTest::Expectations - end - -== Known Extensions: - -capybara_minitest_spec :: Bridge between Capybara RSpec matchers and MiniTest::Spec expectations (e.g. page.must_have_content('Title')). -minispec-metadata :: Metadata for describe/it blocks - (e.g. `it 'requires JS driver', js: true do`) -minitest-ansi :: Colorize minitest output with ANSI colors. -minitest-around :: Around block for minitest. An alternative to setup/teardown dance. -minitest-capistrano :: Assertions and expectations for testing Capistrano recipes -minitest-capybara :: Capybara matchers support for minitest unit and spec -minitest-chef-handler :: Run Minitest suites as Chef report handlers -minitest-ci :: CI reporter plugin for MiniTest. -minitest-colorize :: Colorize MiniTest output and show failing tests instantly. -minitest-context :: Defines contexts for code reuse in MiniTest - specs that share common expectations. -minitest-debugger :: Wraps assert so failed assertions drop into - the ruby debugger. -minitest-display :: Patches MiniTest to allow for an easily configurable output. -minitest-emoji :: Print out emoji for your test passes, fails, and skips. -minitest-english :: Semantically symmetric aliases for assertions and expectations. -minitest-excludes :: Clean API for excluding certain tests you - don't want to run under certain conditions. -minitest-firemock :: Makes your MiniTest mocks more resilient. -minitest-great_expectations :: Generally useful additions to minitest's assertions and expectations -minitest-growl :: Test notifier for minitest via growl. -minitest-implicit-subject :: Implicit declaration of the test subject. -minitest-instrument :: Instrument ActiveSupport::Notifications when - test method is executed -minitest-instrument-db :: Store information about speed of test - execution provided by minitest-instrument in database -minitest-libnotify :: Test notifier for minitest via libnotify. -minitest-macruby :: Provides extensions to minitest for macruby UI testing. -minitest-matchers :: Adds support for RSpec-style matchers to minitest. -minitest-metadata :: Annotate tests with metadata (key-value). -minitest-mongoid :: Mongoid assertion matchers for MiniTest -minitest-must_not :: Provides must_not as an alias for wont in MiniTest -minitest-nc :: Test notifier for minitest via Mountain Lion's Notification Center -minitest-predicates :: Adds support for .predicate? methods -minitest-rails :: MiniTest integration for Rails 3.x -minitest-rails-capybara :: Capybara integration for MiniTest::Rails -minitest-reporters :: Create customizable MiniTest output formats -minitest-should_syntax :: RSpec-style +x.should == y+ assertions for MiniTest -minitest-shouldify :: Adding all manner of shoulds to MiniTest (bad idea) -minitest-spec-context :: Provides rspec-ish context method to MiniTest::Spec -minitest-spec-magic :: Minitest::Spec extensions for Rails and beyond -minitest-spec-rails :: Drop in MiniTest::Spec superclass for ActiveSupport::TestCase. -minitest-stub-const :: Stub constants for the duration of a block -minitest-tags :: add tags for minitest -minitest-wscolor :: Yet another test colorizer. -minitest_owrapper :: Get tests results as a TestResult object. -minitest_should :: Shoulda style syntax for minitest test::unit. -minitest_tu_shim :: minitest_tu_shim bridges between test/unit and minitest. -mongoid-minitest :: MiniTest matchers for Mongoid. -pry-rescue :: A pry plugin w/ minitest support. See pry-rescue/minitest.rb. - -== Unknown Extensions: - -Authors... Please send me a pull request with a description of your minitest extension. - -* assay-minitest -* detroit-minitest -* em-minitest-spec -* flexmock-minitest -* guard-minitest -* guard-minitest-decisiv -* minitest-activemodel -* minitest-ar-assertions -* minitest-capybara-unit -* minitest-colorer -* minitest-deluxe -* minitest-extra-assertions -* minitest-rails-shoulda -* minitest-spec -* minitest-spec-should -* minitest-sugar -* minitest_should -* mongoid-minitest -* spork-minitest - -== REQUIREMENTS: - -* Ruby 1.8, maybe even 1.6 or lower. No magic is involved. - -== INSTALL: - - sudo gem install minitest - -On 1.9, you already have it. To get newer candy you can still install -the gem, but you'll need to activate the gem explicitly to use it: - - require 'rubygems' - gem 'minitest' # ensures you're using the gem, and not the built in MT - require 'minitest/autorun' - - # ... usual testing stuffs ... - -DO NOTE: There is a serious problem with the way that ruby 1.9/2.0 -packages their own gems. They install a gem specification file, but -don't install the gem contents in the gem path. This messes up -Gem.find_files and many other things (gem which, gem contents, etc). - -Just install minitest as a gem for real and you'll be happier. - -== LICENSE: - -(The MIT License) - -Copyright (c) Ryan Davis, seattle.rb - -Permission is hereby granted, free of charge, to any person obtaining -a copy of this software and associated documentation files (the -'Software'), to deal in the Software without restriction, including -without limitation the rights to use, copy, modify, merge, publish, -distribute, sublicense, and/or sell copies of the Software, and to -permit persons to whom the Software is furnished to do so, subject to -the following conditions: - -The above copyright notice and this permission notice shall be -included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY -CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, -TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE -SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/test/lib/minitest/autorun.rb b/test/lib/minitest/autorun.rb deleted file mode 100644 index 84409662..00000000 --- a/test/lib/minitest/autorun.rb +++ /dev/null @@ -1,14 +0,0 @@ -# encoding: utf-8 -# frozen_string_literal: true - -begin - require 'rubygems' - gem 'minitest' -rescue Gem::LoadError - # do nothing -end - -require 'minitest/unit' -require 'minitest/mock' - -MiniTest::Unit.autorun diff --git a/test/lib/minitest/benchmark.rb b/test/lib/minitest/benchmark.rb deleted file mode 100644 index b3f2bc28..00000000 --- a/test/lib/minitest/benchmark.rb +++ /dev/null @@ -1,418 +0,0 @@ -# encoding: utf-8 -# frozen_string_literal: true - -require 'minitest/unit' - -class MiniTest::Unit # :nodoc: - def run_benchmarks # :nodoc: - _run_anything :benchmark - end - - def benchmark_suite_header suite # :nodoc: - "\n#{suite}\t#{suite.bench_range.join("\t")}" - end - - class TestCase - ## - # Returns a set of ranges stepped exponentially from +min+ to - # +max+ by powers of +base+. Eg: - # - # bench_exp(2, 16, 2) # => [2, 4, 8, 16] - - def self.bench_exp min, max, base = 10 - min = (Math.log10(min) / Math.log10(base)).to_i - max = (Math.log10(max) / Math.log10(base)).to_i - - (min..max).map { |m| base ** m }.to_a - end - - ## - # Returns a set of ranges stepped linearly from +min+ to +max+ by - # +step+. Eg: - # - # bench_linear(20, 40, 10) # => [20, 30, 40] - - def self.bench_linear min, max, step = 10 - (min..max).step(step).to_a - rescue LocalJumpError # 1.8.6 - r = []; (min..max).step(step) { |n| r << n }; r - end - - ## - # Returns the benchmark methods (methods that start with bench_) - # for that class. - - def self.benchmark_methods # :nodoc: - public_instance_methods(true).grep(/^bench_/).map { |m| m.to_s }.sort - end - - ## - # Returns all test suites that have benchmark methods. - - def self.benchmark_suites - TestCase.test_suites.reject { |s| s.benchmark_methods.empty? } - end - - ## - # Specifies the ranges used for benchmarking for that class. - # Defaults to exponential growth from 1 to 10k by powers of 10. - # Override if you need different ranges for your benchmarks. - # - # See also: ::bench_exp and ::bench_linear. - - def self.bench_range - bench_exp 1, 10_000 - end - - ## - # Runs the given +work+, gathering the times of each run. Range - # and times are then passed to a given +validation+ proc. Outputs - # the benchmark name and times in tab-separated format, making it - # easy to paste into a spreadsheet for graphing or further - # analysis. - # - # Ranges are specified by ::bench_range. - # - # Eg: - # - # def bench_algorithm - # validation = proc { |x, y| ... } - # assert_performance validation do |n| - # @obj.algorithm(n) - # end - # end - - def assert_performance validation, &work - range = self.class.bench_range - - io.print "#{__name__}" - - times = [] - - range.each do |x| - GC.start - t0 = Time.now - instance_exec(x, &work) - t = Time.now - t0 - - io.print "\t%9.6f" % t - times << t - end - io.puts - - validation[range, times] - end - - ## - # Runs the given +work+ and asserts that the times gathered fit to - # match a constant rate (eg, linear slope == 0) within a given - # +threshold+. Note: because we're testing for a slope of 0, R^2 - # is not a good determining factor for the fit, so the threshold - # is applied against the slope itself. As such, you probably want - # to tighten it from the default. - # - # See http://www.graphpad.com/curvefit/goodness_of_fit.htm for - # more details. - # - # Fit is calculated by #fit_linear. - # - # Ranges are specified by ::bench_range. - # - # Eg: - # - # def bench_algorithm - # assert_performance_constant 0.9999 do |n| - # @obj.algorithm(n) - # end - # end - - def assert_performance_constant threshold = 0.99, &work - validation = proc do |range, times| - a, b, rr = fit_linear range, times - assert_in_delta 0, b, 1 - threshold - [a, b, rr] - end - - assert_performance validation, &work - end - - ## - # Runs the given +work+ and asserts that the times gathered fit to - # match a exponential curve within a given error +threshold+. - # - # Fit is calculated by #fit_exponential. - # - # Ranges are specified by ::bench_range. - # - # Eg: - # - # def bench_algorithm - # assert_performance_exponential 0.9999 do |n| - # @obj.algorithm(n) - # end - # end - - def assert_performance_exponential threshold = 0.99, &work - assert_performance validation_for_fit(:exponential, threshold), &work - end - - ## - # Runs the given +work+ and asserts that the times gathered fit to - # match a logarithmic curve within a given error +threshold+. - # - # Fit is calculated by #fit_logarithmic. - # - # Ranges are specified by ::bench_range. - # - # Eg: - # - # def bench_algorithm - # assert_performance_logarithmic 0.9999 do |n| - # @obj.algorithm(n) - # end - # end - - def assert_performance_logarithmic threshold = 0.99, &work - assert_performance validation_for_fit(:logarithmic, threshold), &work - end - - ## - # Runs the given +work+ and asserts that the times gathered fit to - # match a straight line within a given error +threshold+. - # - # Fit is calculated by #fit_linear. - # - # Ranges are specified by ::bench_range. - # - # Eg: - # - # def bench_algorithm - # assert_performance_linear 0.9999 do |n| - # @obj.algorithm(n) - # end - # end - - def assert_performance_linear threshold = 0.99, &work - assert_performance validation_for_fit(:linear, threshold), &work - end - - ## - # Runs the given +work+ and asserts that the times gathered curve - # fit to match a power curve within a given error +threshold+. - # - # Fit is calculated by #fit_power. - # - # Ranges are specified by ::bench_range. - # - # Eg: - # - # def bench_algorithm - # assert_performance_power 0.9999 do |x| - # @obj.algorithm - # end - # end - - def assert_performance_power threshold = 0.99, &work - assert_performance validation_for_fit(:power, threshold), &work - end - - ## - # Takes an array of x/y pairs and calculates the general R^2 value. - # - # See: http://en.wikipedia.org/wiki/Coefficient_of_determination - - def fit_error xys - y_bar = sigma(xys) { |x, y| y } / xys.size.to_f - ss_tot = sigma(xys) { |x, y| (y - y_bar) ** 2 } - ss_err = sigma(xys) { |x, y| (yield(x) - y) ** 2 } - - 1 - (ss_err / ss_tot) - end - - ## - # To fit a functional form: y = ae^(bx). - # - # Takes x and y values and returns [a, b, r^2]. - # - # See: http://mathworld.wolfram.com/LeastSquaresFittingExponential.html - - def fit_exponential xs, ys - n = xs.size - xys = xs.zip(ys) - sxlny = sigma(xys) { |x,y| x * Math.log(y) } - slny = sigma(xys) { |x,y| Math.log(y) } - sx2 = sigma(xys) { |x,y| x * x } - sx = sigma xs - - c = n * sx2 - sx ** 2 - a = (slny * sx2 - sx * sxlny) / c - b = ( n * sxlny - sx * slny ) / c - - return Math.exp(a), b, fit_error(xys) { |x| Math.exp(a + b * x) } - end - - ## - # To fit a functional form: y = a + b*ln(x). - # - # Takes x and y values and returns [a, b, r^2]. - # - # See: http://mathworld.wolfram.com/LeastSquaresFittingLogarithmic.html - - def fit_logarithmic xs, ys - n = xs.size - xys = xs.zip(ys) - slnx2 = sigma(xys) { |x,y| Math.log(x) ** 2 } - slnx = sigma(xys) { |x,y| Math.log(x) } - sylnx = sigma(xys) { |x,y| y * Math.log(x) } - sy = sigma(xys) { |x,y| y } - - c = n * slnx2 - slnx ** 2 - b = ( n * sylnx - sy * slnx ) / c - a = (sy - b * slnx) / n - - return a, b, fit_error(xys) { |x| a + b * Math.log(x) } - end - - - ## - # Fits the functional form: a + bx. - # - # Takes x and y values and returns [a, b, r^2]. - # - # See: http://mathworld.wolfram.com/LeastSquaresFitting.html - - def fit_linear xs, ys - n = xs.size - xys = xs.zip(ys) - sx = sigma xs - sy = sigma ys - sx2 = sigma(xs) { |x| x ** 2 } - sxy = sigma(xys) { |x,y| x * y } - - c = n * sx2 - sx**2 - a = (sy * sx2 - sx * sxy) / c - b = ( n * sxy - sx * sy ) / c - - return a, b, fit_error(xys) { |x| a + b * x } - end - - ## - # To fit a functional form: y = ax^b. - # - # Takes x and y values and returns [a, b, r^2]. - # - # See: http://mathworld.wolfram.com/LeastSquaresFittingPowerLaw.html - - def fit_power xs, ys - n = xs.size - xys = xs.zip(ys) - slnxlny = sigma(xys) { |x, y| Math.log(x) * Math.log(y) } - slnx = sigma(xs) { |x | Math.log(x) } - slny = sigma(ys) { | y| Math.log(y) } - slnx2 = sigma(xs) { |x | Math.log(x) ** 2 } - - b = (n * slnxlny - slnx * slny) / (n * slnx2 - slnx ** 2); - a = (slny - b * slnx) / n - - return Math.exp(a), b, fit_error(xys) { |x| (Math.exp(a) * (x ** b)) } - end - - ## - # Enumerates over +enum+ mapping +block+ if given, returning the - # sum of the result. Eg: - # - # sigma([1, 2, 3]) # => 1 + 2 + 3 => 7 - # sigma([1, 2, 3]) { |n| n ** 2 } # => 1 + 4 + 9 => 14 - - def sigma enum, &block - enum = enum.map(&block) if block - enum.inject { |sum, n| sum + n } - end - - ## - # Returns a proc that calls the specified fit method and asserts - # that the error is within a tolerable threshold. - - def validation_for_fit msg, threshold - proc do |range, times| - a, b, rr = send "fit_#{msg}", range, times - assert_operator rr, :>=, threshold - [a, b, rr] - end - end - end -end - -class MiniTest::Spec - ## - # This is used to define a new benchmark method. You usually don't - # use this directly and is intended for those needing to write new - # performance curve fits (eg: you need a specific polynomial fit). - # - # See ::bench_performance_linear for an example of how to use this. - - def self.bench name, &block - define_method "bench_#{name.gsub(/\W+/, '_')}", &block - end - - ## - # Specifies the ranges used for benchmarking for that class. - # - # bench_range do - # bench_exp(2, 16, 2) - # end - # - # See Unit::TestCase.bench_range for more details. - - def self.bench_range &block - return super unless block - - meta = (class << self; self; end) - meta.send :define_method, "bench_range", &block - end - - ## - # Create a benchmark that verifies that the performance is linear. - # - # describe "my class" do - # bench_performance_linear "fast_algorithm", 0.9999 do |n| - # @obj.fast_algorithm(n) - # end - # end - - def self.bench_performance_linear name, threshold = 0.99, &work - bench name do - assert_performance_linear threshold, &work - end - end - - ## - # Create a benchmark that verifies that the performance is constant. - # - # describe "my class" do - # bench_performance_constant "zoom_algorithm!" do |n| - # @obj.zoom_algorithm!(n) - # end - # end - - def self.bench_performance_constant name, threshold = 0.99, &work - bench name do - assert_performance_constant threshold, &work - end - end - - ## - # Create a benchmark that verifies that the performance is exponential. - # - # describe "my class" do - # bench_performance_exponential "algorithm" do |n| - # @obj.algorithm(n) - # end - # end - - def self.bench_performance_exponential name, threshold = 0.99, &work - bench name do - assert_performance_exponential threshold, &work - end - end -end diff --git a/test/lib/minitest/mock.rb b/test/lib/minitest/mock.rb deleted file mode 100644 index 224b06cb..00000000 --- a/test/lib/minitest/mock.rb +++ /dev/null @@ -1,196 +0,0 @@ -# encoding: utf-8 -# frozen_string_literal: true - -class MockExpectationError < StandardError; end # :nodoc: - -## -# A simple and clean mock object framework. - -module MiniTest # :nodoc: - - ## - # All mock objects are an instance of Mock - - class Mock - alias :__respond_to? :respond_to? - - skip_methods = %w(object_id respond_to_missing? inspect === to_s) - - instance_methods.each do |m| - undef_method m unless skip_methods.include?(m.to_s) || m =~ /^__/ - end - - def initialize # :nodoc: - @expected_calls = Hash.new { |calls, name| calls[name] = [] } - @actual_calls = Hash.new { |calls, name| calls[name] = [] } - end - - ## - # Expect that method +name+ is called, optionally with +args+ or a - # +blk+, and returns +retval+. - # - # @mock.expect(:meaning_of_life, 42) - # @mock.meaning_of_life # => 42 - # - # @mock.expect(:do_something_with, true, [some_obj, true]) - # @mock.do_something_with(some_obj, true) # => true - # - # @mock.expect(:do_something_else, true) do |a1, a2| - # a1 == "buggs" && a2 == :bunny - # end - # - # +args+ is compared to the expected args using case equality (ie, the - # '===' operator), allowing for less specific expectations. - # - # @mock.expect(:uses_any_string, true, [String]) - # @mock.uses_any_string("foo") # => true - # @mock.verify # => true - # - # @mock.expect(:uses_one_string, true, ["foo"] - # @mock.uses_one_string("bar") # => true - # @mock.verify # => raises MockExpectationError - - def expect(name, retval, args=[], &blk) - if block_given? - raise ArgumentError, "args ignored when block given" unless args.empty? - @expected_calls[name] << { :retval => retval, :block => blk } - else - raise ArgumentError, "args must be an array" unless Array === args - @expected_calls[name] << { :retval => retval, :args => args } - end - self - end - - def __call name, data # :nodoc: - case data - when Hash then - "#{name}(#{data[:args].inspect[1..-2]}) => #{data[:retval].inspect}" - else - data.map { |d| __call name, d }.join ", " - end - end - - ## - # Verify that all methods were called as expected. Raises - # +MockExpectationError+ if the mock object was not called as - # expected. - - def verify - @expected_calls.each do |name, calls| - calls.each do |expected| - msg1 = "expected #{__call name, expected}" - msg2 = "#{msg1}, got [#{__call name, @actual_calls[name]}]" - - raise MockExpectationError, msg2 if - @actual_calls.has_key?(name) and - not @actual_calls[name].include?(expected) - - raise MockExpectationError, msg1 unless - @actual_calls.has_key?(name) and - @actual_calls[name].include?(expected) - end - end - true - end - - def method_missing(sym, *args) # :nodoc: - unless @expected_calls.has_key?(sym) then - raise NoMethodError, "unmocked method %p, expected one of %p" % - [sym, @expected_calls.keys.sort_by(&:to_s)] - end - - index = @actual_calls[sym].length - expected_call = @expected_calls[sym][index] - - unless expected_call then - raise MockExpectationError, "No more expects available for %p: %p" % - [sym, args] - end - - expected_args, retval, val_block = - expected_call.values_at(:args, :retval, :block) - - if val_block then - raise MockExpectationError, "mocked method %p failed block w/ %p" % - [sym, args] unless val_block.call(args) - - # keep "verify" happy - @actual_calls[sym] << expected_call - return retval - end - - if expected_args.size != args.size then - raise ArgumentError, "mocked method %p expects %d arguments, got %d" % - [sym, expected_args.size, args.size] - end - - fully_matched = expected_args.zip(args).all? { |mod, a| - mod === a or mod == a - } - - unless fully_matched then - raise MockExpectationError, "mocked method %p called with unexpected arguments %p" % - [sym, args] - end - - @actual_calls[sym] << { - :retval => retval, - :args => expected_args.zip(args).map { |mod, a| mod === a ? mod : a } - } - - retval - end - - def respond_to?(sym, include_private = false) # :nodoc: - return true if @expected_calls.has_key?(sym.to_sym) - return __respond_to?(sym, include_private) - end - end -end - -class Object # :nodoc: - - ## - # Add a temporary stubbed method replacing +name+ for the duration - # of the +block+. If +val_or_callable+ responds to #call, then it - # returns the result of calling it, otherwise returns the value - # as-is. Cleans up the stub at the end of the +block+. The method - # +name+ must exist before stubbing. - # - # def test_stale_eh - # obj_under_test = Something.new - # refute obj_under_test.stale? - # - # Time.stub :now, Time.at(0) do - # assert obj_under_test.stale? - # end - # end - - def stub name, val_or_callable, &block - new_name = "__minitest_stub__#{name}" - - metaclass = class << self; self; end - - if respond_to? name and not methods.map(&:to_s).include? name.to_s then - metaclass.send :define_method, name do |*args| - super(*args) - end - end - - metaclass.send :alias_method, new_name, name - - metaclass.send :define_method, name do |*args| - if val_or_callable.respond_to? :call then - val_or_callable.call(*args) - else - val_or_callable - end - end - - yield self - ensure - metaclass.send :undef_method, name - metaclass.send :alias_method, name, new_name - metaclass.send :undef_method, new_name - end -end diff --git a/test/lib/minitest/unit.rb b/test/lib/minitest/unit.rb deleted file mode 100644 index 88daaafc..00000000 --- a/test/lib/minitest/unit.rb +++ /dev/null @@ -1,1416 +0,0 @@ -# encoding: utf-8 -# frozen_string_literal: true - -require "optparse" -require "rbconfig" -require "leakchecker" - -## -# Minimal (mostly drop-in) replacement for test-unit. -# -# :include: README.txt - -module MiniTest - - def self.const_missing name # :nodoc: - case name - when :MINI_DIR then - msg = "MiniTest::MINI_DIR was removed. Don't violate other's internals." - warn "WAR\NING: #{msg}" - warn "WAR\NING: Used by #{caller.first}." - const_set :MINI_DIR, "bad value" - else - super - end - end - - ## - # Assertion base class - - class Assertion < Exception; end - - ## - # Assertion raised when skipping a test - - class Skip < Assertion; end - - class << self - ## - # Filter object for backtraces. - - attr_accessor :backtrace_filter - end - - class BacktraceFilter # :nodoc: - def filter bt - return ["No backtrace"] unless bt - - new_bt = [] - - unless $DEBUG then - bt.each do |line| - break if line =~ /lib\/minitest/ - new_bt << line - end - - new_bt = bt.reject { |line| line =~ /lib\/minitest/ } if new_bt.empty? - new_bt = bt.dup if new_bt.empty? - else - new_bt = bt.dup - end - - new_bt - end - end - - self.backtrace_filter = BacktraceFilter.new - - def self.filter_backtrace bt # :nodoc: - backtrace_filter.filter bt - end - - ## - # MiniTest Assertions. All assertion methods accept a +msg+ which is - # printed if the assertion fails. - - module Assertions - ## - # Returns the diff command to use in #diff. Tries to intelligently - # figure out what diff to use. - - def self.diff - @diff = if (RbConfig::CONFIG['host_os'] =~ /mswin|mingw/ && - system("diff.exe", __FILE__, __FILE__)) then - "diff.exe -u" - elsif Minitest::Unit::Guard.maglev? then # HACK - "diff -u" - elsif system("gdiff", __FILE__, __FILE__) - "gdiff -u" # solaris and kin suck - elsif system("diff", __FILE__, __FILE__) - "diff -u" - else - nil - end unless defined? @diff - - @diff - end - - ## - # Set the diff command to use in #diff. - - def self.diff= o - @diff = o - end - - ## - # Returns a diff between +exp+ and +act+. If there is no known - # diff command or if it doesn't make sense to diff the output - # (single line, short output), then it simply returns a basic - # comparison between the two. - - def diff exp, act - require "tempfile" - - expect = mu_pp_for_diff exp - butwas = mu_pp_for_diff act - result = nil - - need_to_diff = - MiniTest::Assertions.diff && - (expect.include?("\n") || - butwas.include?("\n") || - expect.size > 30 || - butwas.size > 30 || - expect == butwas) - - return "Expected: #{mu_pp exp}\n Actual: #{mu_pp act}" unless - need_to_diff - - tempfile_a = nil - tempfile_b = nil - - Tempfile.open("expect") do |a| - tempfile_a = a - a.puts expect - a.flush - - Tempfile.open("butwas") do |b| - tempfile_b = b - b.puts butwas - b.flush - - result = `#{MiniTest::Assertions.diff} #{a.path} #{b.path}` - result.sub!(/^\-\-\- .+/, "--- expected") - result.sub!(/^\+\+\+ .+/, "+++ actual") - - if result.empty? then - klass = exp.class - result = [ - "No visible difference in the #{klass}#inspect output.\n", - "You should look at the implementation of #== on ", - "#{klass} or its members.\n", - expect, - ].join - end - end - end - - result - ensure - tempfile_a.close! if tempfile_a - tempfile_b.close! if tempfile_b - end - - ## - # This returns a human-readable version of +obj+. By default - # #inspect is called. You can override this to use #pretty_print - # if you want. - - def mu_pp obj - s = obj.inspect - s = s.encode Encoding.default_external if defined? Encoding - s - end - - ## - # This returns a diff-able human-readable version of +obj+. This - # differs from the regular mu_pp because it expands escaped - # newlines and makes hex-values generic (like object_ids). This - # uses mu_pp to do the first pass and then cleans it up. - - def mu_pp_for_diff obj - mu_pp(obj).gsub(/\\n/, "\n").gsub(/:0x[a-fA-F0-9]{4,}/m, ':0xXXXXXX') - end - - def _assertions= n # :nodoc: - @_assertions = n - end - - def _assertions # :nodoc: - @_assertions ||= 0 - end - - ## - # Fails unless +test+ is a true value. - - def assert test, msg = nil - msg ||= "Failed assertion, no message given." - self._assertions += 1 - unless test then - msg = msg.call if Proc === msg - raise MiniTest::Assertion, msg - end - true - end - - ## - # Fails unless +obj+ is empty. - - def assert_empty obj, msg = nil - msg = message(msg) { "Expected #{mu_pp(obj)} to be empty" } - assert_respond_to obj, :empty? - assert obj.empty?, msg - end - - ## - # Fails unless exp == act printing the difference between - # the two, if possible. - # - # If there is no visible difference but the assertion fails, you - # should suspect that your #== is buggy, or your inspect output is - # missing crucial details. - # - # For floats use assert_in_delta. - # - # See also: MiniTest::Assertions.diff - - def assert_equal exp, act, msg = nil - msg = message(msg, "") { diff exp, act } - assert exp == act, msg - end - - ## - # For comparing Floats. Fails unless +exp+ and +act+ are within +delta+ - # of each other. - # - # assert_in_delta Math::PI, (22.0 / 7.0), 0.01 - - def assert_in_delta exp, act, delta = 0.001, msg = nil - n = (exp - act).abs - msg = message(msg) { - "Expected |#{exp} - #{act}| (#{n}) to be <= #{delta}" - } - assert delta >= n, msg - end - - ## - # For comparing Floats. Fails unless +exp+ and +act+ have a relative - # error less than +epsilon+. - - def assert_in_epsilon a, b, epsilon = 0.001, msg = nil - assert_in_delta a, b, [a.abs, b.abs].min * epsilon, msg - end - - ## - # Fails unless +collection+ includes +obj+. - - def assert_includes collection, obj, msg = nil - msg = message(msg) { - "Expected #{mu_pp(collection)} to include #{mu_pp(obj)}" - } - assert_respond_to collection, :include? - assert collection.include?(obj), msg - end - - ## - # Fails unless +obj+ is an instance of +cls+. - - def assert_instance_of cls, obj, msg = nil - msg = message(msg) { - "Expected #{mu_pp(obj)} to be an instance of #{cls}, not #{obj.class}" - } - - assert obj.instance_of?(cls), msg - end - - ## - # Fails unless +obj+ is a kind of +cls+. - - def assert_kind_of cls, obj, msg = nil # TODO: merge with instance_of - msg = message(msg) { - "Expected #{mu_pp(obj)} to be a kind of #{cls}, not #{obj.class}" } - - assert obj.kind_of?(cls), msg - end - - ## - # Fails unless +matcher+ =~ +obj+. - - def assert_match matcher, obj, msg = nil - msg = message(msg) { "Expected #{mu_pp matcher} to match #{mu_pp obj}" } - assert_respond_to matcher, :"=~" - matcher = Regexp.new Regexp.escape matcher if String === matcher - assert matcher =~ obj, msg - end - - ## - # Fails unless +obj+ is nil - - def assert_nil obj, msg = nil - msg = message(msg) { "Expected #{mu_pp(obj)} to be nil" } - assert obj.nil?, msg - end - - ## - # For testing with binary operators. - # - # assert_operator 5, :<=, 4 - - def assert_operator o1, op, o2 = (predicate = true; nil), msg = nil - return assert_predicate o1, op, msg if predicate - msg = message(msg) { "Expected #{mu_pp(o1)} to be #{op} #{mu_pp(o2)}" } - assert o1.__send__(op, o2), msg - end - - ## - # Fails if stdout or stderr do not output the expected results. - # Pass in nil if you don't care about that streams output. Pass in - # "" if you require it to be silent. Pass in a regexp if you want - # to pattern match. - # - # NOTE: this uses #capture_io, not #capture_subprocess_io. - # - # See also: #assert_silent - - def assert_output stdout = nil, stderr = nil - out, err = capture_io do - yield - end - - err_msg = Regexp === stderr ? :assert_match : :assert_equal if stderr - out_msg = Regexp === stdout ? :assert_match : :assert_equal if stdout - - y = send err_msg, stderr, err, "In stderr" if err_msg - x = send out_msg, stdout, out, "In stdout" if out_msg - - (!stdout || x) && (!stderr || y) - end - - ## - # For testing with predicates. - # - # assert_predicate str, :empty? - # - # This is really meant for specs and is front-ended by assert_operator: - # - # str.must_be :empty? - - def assert_predicate o1, op, msg = nil - msg = message(msg) { "Expected #{mu_pp(o1)} to be #{op}" } - assert o1.__send__(op), msg - end - - ## - # Fails unless the block raises one of +exp+. Returns the - # exception matched so you can check the message, attributes, etc. - - def assert_raises *exp - msg = "#{exp.pop}.\n" if String === exp.last - - begin - yield - rescue MiniTest::Skip => e - return e if exp.include? MiniTest::Skip - raise e - rescue Exception => e - expected = exp.any? { |ex| - if ex.instance_of? Module then - e.kind_of? ex - else - e.instance_of? ex - end - } - - assert expected, proc { - exception_details(e, "#{msg}#{mu_pp(exp)} exception expected, not") - } - - return e - end - - exp = exp.first if exp.size == 1 - - flunk "#{msg}#{mu_pp(exp)} expected but nothing was raised." - end - - ## - # Fails unless +obj+ responds to +meth+. - - def assert_respond_to obj, meth, msg = nil - msg = message(msg) { - "Expected #{mu_pp(obj)} (#{obj.class}) to respond to ##{meth}" - } - assert obj.respond_to?(meth), msg - end - - ## - # Fails unless +exp+ and +act+ are #equal? - - def assert_same exp, act, msg = nil - msg = message(msg) { - data = [mu_pp(act), act.object_id, mu_pp(exp), exp.object_id] - "Expected %s (oid=%d) to be the same as %s (oid=%d)" % data - } - assert exp.equal?(act), msg - end - - ## - # +send_ary+ is a receiver, message and arguments. - # - # Fails unless the call returns a true value - # TODO: I should prolly remove this from specs - - def assert_send send_ary, m = nil - recv, msg, *args = send_ary - m = message(m) { - "Expected #{mu_pp(recv)}.#{msg}(*#{mu_pp(args)}) to return true" } - assert recv.__send__(msg, *args), m - end - - ## - # Fails if the block outputs anything to stderr or stdout. - # - # See also: #assert_output - - def assert_silent - assert_output "", "" do - yield - end - end - - ## - # Fails unless the block throws +sym+ - - def assert_throws sym, msg = nil - default = "Expected #{mu_pp(sym)} to have been thrown" - caught = true - catch(sym) do - begin - yield - rescue ThreadError => e # wtf?!? 1.8 + threads == suck - default += ", not \:#{e.message[/uncaught throw \`(\w+?)\'/, 1]}" - rescue ArgumentError => e # 1.9 exception - default += ", not #{e.message.split(/ /).last}" - rescue NameError => e # 1.8 exception - default += ", not #{e.name.inspect}" - end - caught = false - end - - assert caught, message(msg) { default } - end - - ## - # Captures $stdout and $stderr into strings: - # - # out, err = capture_io do - # puts "Some info" - # warn "You did a bad thing" - # end - # - # assert_match %r%info%, out - # assert_match %r%bad%, err - # - # NOTE: For efficiency, this method uses StringIO and does not - # capture IO for subprocesses. Use #capture_subprocess_io for - # that. - - def capture_io - require 'stringio' - - captured_stdout, captured_stderr = StringIO.new, StringIO.new - - synchronize do - orig_stdout, orig_stderr = $stdout, $stderr - $stdout, $stderr = captured_stdout, captured_stderr - - begin - yield - ensure - $stdout = orig_stdout - $stderr = orig_stderr - end - end - - return captured_stdout.string, captured_stderr.string - end - - ## - # Captures $stdout and $stderr into strings, using Tempfile to - # ensure that subprocess IO is captured as well. - # - # out, err = capture_subprocess_io do - # system "echo Some info" - # system "echo You did a bad thing 1>&2" - # end - # - # assert_match %r%info%, out - # assert_match %r%bad%, err - # - # NOTE: This method is approximately 10x slower than #capture_io so - # only use it when you need to test the output of a subprocess. - - def capture_subprocess_io - require 'tempfile' - - captured_stdout, captured_stderr = Tempfile.new("out"), Tempfile.new("err") - - synchronize do - orig_stdout, orig_stderr = $stdout.dup, $stderr.dup - $stdout.reopen captured_stdout - $stderr.reopen captured_stderr - - begin - yield - - $stdout.rewind - $stderr.rewind - - [captured_stdout.read, captured_stderr.read] - ensure - $stdout.reopen orig_stdout - $stderr.reopen orig_stderr - orig_stdout.close - orig_stderr.close - captured_stdout.close! - captured_stderr.close! - end - end - end - - ## - # Returns details for exception +e+ - - def exception_details e, msg - [ - "#{msg}", - "Class: <#{e.class}>", - "Message: <#{e.message.inspect}>", - "---Backtrace---", - "#{MiniTest::filter_backtrace(e.backtrace).join("\n")}", - "---------------", - ].join "\n" - end - - ## - # Fails with +msg+ - - def flunk msg = nil - msg ||= "Epic Fail!" - assert false, msg - end - - ## - # Returns a proc that will output +msg+ along with the default message. - - def message msg = nil, ending = ".", &default - proc { - msg = msg.call.chomp(".") if Proc === msg - custom_message = "#{msg}.\n" unless msg.nil? or msg.to_s.empty? - "#{custom_message}#{default.call}#{ending}" - } - end - - ## - # used for counting assertions - - def pass msg = nil - assert true - end - - ## - # Fails if +test+ is a true value - - def refute test, msg = nil - msg ||= "Failed refutation, no message given" - not assert(! test, msg) - end - - ## - # Fails if +obj+ is empty. - - def refute_empty obj, msg = nil - msg = message(msg) { "Expected #{mu_pp(obj)} to not be empty" } - assert_respond_to obj, :empty? - refute obj.empty?, msg - end - - ## - # Fails if exp == act. - # - # For floats use refute_in_delta. - - def refute_equal exp, act, msg = nil - msg = message(msg) { - "Expected #{mu_pp(act)} to not be equal to #{mu_pp(exp)}" - } - refute exp == act, msg - end - - ## - # For comparing Floats. Fails if +exp+ is within +delta+ of +act+. - # - # refute_in_delta Math::PI, (22.0 / 7.0) - - def refute_in_delta exp, act, delta = 0.001, msg = nil - n = (exp - act).abs - msg = message(msg) { - "Expected |#{exp} - #{act}| (#{n}) to not be <= #{delta}" - } - refute delta >= n, msg - end - - ## - # For comparing Floats. Fails if +exp+ and +act+ have a relative error - # less than +epsilon+. - - def refute_in_epsilon a, b, epsilon = 0.001, msg = nil - refute_in_delta a, b, a * epsilon, msg - end - - ## - # Fails if +collection+ includes +obj+. - - def refute_includes collection, obj, msg = nil - msg = message(msg) { - "Expected #{mu_pp(collection)} to not include #{mu_pp(obj)}" - } - assert_respond_to collection, :include? - refute collection.include?(obj), msg - end - - ## - # Fails if +obj+ is an instance of +cls+. - - def refute_instance_of cls, obj, msg = nil - msg = message(msg) { - "Expected #{mu_pp(obj)} to not be an instance of #{cls}" - } - refute obj.instance_of?(cls), msg - end - - ## - # Fails if +obj+ is a kind of +cls+. - - def refute_kind_of cls, obj, msg = nil # TODO: merge with instance_of - msg = message(msg) { "Expected #{mu_pp(obj)} to not be a kind of #{cls}" } - refute obj.kind_of?(cls), msg - end - - ## - # Fails if +matcher+ =~ +obj+. - - def refute_match matcher, obj, msg = nil - msg = message(msg) {"Expected #{mu_pp matcher} to not match #{mu_pp obj}"} - assert_respond_to matcher, :"=~" - matcher = Regexp.new Regexp.escape matcher if String === matcher - refute matcher =~ obj, msg - end - - ## - # Fails if +obj+ is nil. - - def refute_nil obj, msg = nil - msg = message(msg) { "Expected #{mu_pp(obj)} to not be nil" } - refute obj.nil?, msg - end - - ## - # Fails if +o1+ is not +op+ +o2+. Eg: - # - # refute_operator 1, :>, 2 #=> pass - # refute_operator 1, :<, 2 #=> fail - - def refute_operator o1, op, o2 = (predicate = true; nil), msg = nil - return refute_predicate o1, op, msg if predicate - msg = message(msg) { "Expected #{mu_pp(o1)} to not be #{op} #{mu_pp(o2)}"} - refute o1.__send__(op, o2), msg - end - - ## - # For testing with predicates. - # - # refute_predicate str, :empty? - # - # This is really meant for specs and is front-ended by refute_operator: - # - # str.wont_be :empty? - - def refute_predicate o1, op, msg = nil - msg = message(msg) { "Expected #{mu_pp(o1)} to not be #{op}" } - refute o1.__send__(op), msg - end - - ## - # Fails if +obj+ responds to the message +meth+. - - def refute_respond_to obj, meth, msg = nil - msg = message(msg) { "Expected #{mu_pp(obj)} to not respond to #{meth}" } - - refute obj.respond_to?(meth), msg - end - - ## - # Fails if +exp+ is the same (by object identity) as +act+. - - def refute_same exp, act, msg = nil - msg = message(msg) { - data = [mu_pp(act), act.object_id, mu_pp(exp), exp.object_id] - "Expected %s (oid=%d) to not be the same as %s (oid=%d)" % data - } - refute exp.equal?(act), msg - end - - ## - # Skips the current test. Gets listed at the end of the run but - # doesn't cause a failure exit code. - - def skip msg = nil, bt = caller - msg ||= "Skipped, no message given" - @skip = true - raise MiniTest::Skip, msg, bt - end - - ## - # Was this testcase skipped? Meant for #teardown. - - def skipped? - defined?(@skip) and @skip - end - - ## - # Takes a block and wraps it with the runner's shared mutex. - - def synchronize - Minitest::Unit.runner.synchronize do - yield - end - end - end - - class Unit # :nodoc: - VERSION = "4.7.5" # :nodoc: - - attr_accessor :report, :failures, :errors, :skips # :nodoc: - attr_accessor :assertion_count # :nodoc: - attr_writer :test_count # :nodoc: - attr_accessor :start_time # :nodoc: - attr_accessor :help # :nodoc: - attr_accessor :verbose # :nodoc: - attr_writer :options # :nodoc: - - ## - # :attr: - # - # if true, installs an "INFO" signal handler (only available to BSD and - # OS X users) which prints diagnostic information about the test run. - # - # This is auto-detected by default but may be overridden by custom - # runners. - - attr_accessor :info_signal - - ## - # Lazy accessor for options. - - def options - @options ||= {} - end - - @@installed_at_exit ||= false - @@out = $stdout - @@after_tests = [] - - ## - # A simple hook allowing you to run a block of code after _all_ of - # the tests are done. Eg: - # - # MiniTest::Unit.after_tests { p $debugging_info } - - def self.after_tests &block - @@after_tests << block - end - - ## - # Registers MiniTest::Unit to run tests at process exit - - def self.autorun - at_exit { - # don't run if there was a non-exit exception - next if $! and not $!.kind_of? SystemExit - - # the order here is important. The at_exit handler must be - # installed before anyone else gets a chance to install their - # own, that way we can be assured that our exit will be last - # to run (at_exit stacks). - exit_code = nil - - at_exit { - @@after_tests.reverse_each(&:call) - exit false if exit_code && exit_code != 0 - } - - exit_code = MiniTest::Unit.new.run ARGV - } unless @@installed_at_exit - @@installed_at_exit = true - end - - ## - # Returns the stream to use for output. - - def self.output - @@out - end - - ## - # Sets MiniTest::Unit to write output to +stream+. $stdout is the default - # output - - def self.output= stream - @@out = stream - end - - ## - # Tells MiniTest::Unit to delegate to +runner+, an instance of a - # MiniTest::Unit subclass, when MiniTest::Unit#run is called. - - def self.runner= runner - @@runner = runner - end - - ## - # Returns the MiniTest::Unit subclass instance that will be used - # to run the tests. A MiniTest::Unit instance is the default - # runner. - - def self.runner - @@runner ||= self.new - end - - ## - # Return all plugins' run methods (methods that start with "run_"). - - def self.plugins - @@plugins ||= (["run_tests"] + - public_instance_methods(false). - grep(/^run_/).map { |s| s.to_s }).uniq - end - - ## - # Return the IO for output. - - def output - self.class.output - end - - def puts *a # :nodoc: - output.puts(*a) - end - - def print *a # :nodoc: - output.print(*a) - end - - def test_count # :nodoc: - @test_count ||= 0 - end - - ## - # Runner for a given +type+ (eg, test vs bench). - - def _run_anything type - suites = TestCase.send "#{type}_suites" - return if suites.empty? - - puts - puts "# Running #{type}s:" - puts - - @test_count, @assertion_count = 0, 0 - test_count = assertion_count = 0 - sync = output.respond_to? :"sync=" # stupid emacs - old_sync, output.sync = output.sync, true if sync - - count = 0 - begin - start = Time.now - - results = _run_suites suites, type - - @test_count = results.inject(0) { |sum, (tc, _)| sum + tc } - @assertion_count = results.inject(0) { |sum, (_, ac)| sum + ac } - test_count += @test_count - assertion_count += @assertion_count - t = Time.now - start - count += 1 - unless @repeat_count - puts - puts - end - puts "Finished%s %ss in %.6fs, %.4f tests/s, %.4f assertions/s.\n" % - [(@repeat_count ? "(#{count}/#{@repeat_count}) " : ""), type, - t, @test_count.fdiv(t), @assertion_count.fdiv(t)] - end while @repeat_count && count < @repeat_count && - report.empty? && failures.zero? && errors.zero? - - output.sync = old_sync if sync - - report.each_with_index do |msg, i| - puts "\n%3d) %s" % [i + 1, msg] - end - - puts - @test_count = test_count - @assertion_count = assertion_count - - status - end - - ## - # Runs all the +suites+ for a given +type+. - # - - def _run_suites suites, type - suites.map { |suite| _run_suite suite, type } - end - - ## - # Run a single +suite+ for a given +type+. - - def _run_suite suite, type - header = "#{type}_suite_header" - puts send(header, suite) if respond_to? header - - filter = options[:filter] || '/./' - filter = Regexp.new $1 if filter =~ /\/(.*)\// - - all_test_methods = suite.send "#{type}_methods" - - filtered_test_methods = all_test_methods.find_all { |m| - filter === m || filter === "#{suite}##{m}" - } - - leakchecker = LeakChecker.new - - assertions = filtered_test_methods.map { |method| - inst = suite.new method - inst._assertions = 0 - - print "#{suite}##{method} = " if @verbose - - start_time = Time.now if @verbose - result = inst.run self - - print "%.2f s = " % (Time.now - start_time) if @verbose - print result - puts if @verbose - $stdout.flush - - if !(defined?(RubyVM::MJIT) && RubyVM::MJIT.enabled?) # compiler process is wrongly considered as leaked - leakchecker.check("#{inst.class}\##{inst.__name__}") - end - - inst._assertions - } - - return assertions.size, assertions.inject(0) { |sum, n| sum + n } - end - - ## - # Record the result of a single test. Makes it very easy to gather - # information. Eg: - # - # class StatisticsRecorder < MiniTest::Unit - # def record suite, method, assertions, time, error - # # ... record the results somewhere ... - # end - # end - # - # MiniTest::Unit.runner = StatisticsRecorder.new - # - # NOTE: record might be sent more than once per test. It will be - # sent once with the results from the test itself. If there is a - # failure or error in teardown, it will be sent again with the - # error or failure. - - def record suite, method, assertions, time, error - end - - def location e # :nodoc: - last_before_assertion = "" - e.backtrace.reverse_each do |s| - break if s =~ /in .(assert|refute|flunk|pass|fail|raise|must|wont)/ - last_before_assertion = s - end - last_before_assertion.sub(/:in .*$/, '') - end - - ## - # Writes status for failed test +meth+ in +klass+ which finished with - # exception +e+ - - def puke klass, meth, e - e = case e - when MiniTest::Skip then - @skips += 1 - return "S" unless @verbose - "Skipped:\n#{klass}##{meth} [#{location e}]:\n#{e.message}\n" - when MiniTest::Assertion then - @failures += 1 - "Failure:\n#{klass}##{meth} [#{location e}]:\n#{e.message}\n" - else - @errors += 1 - bt = MiniTest::filter_backtrace(e.backtrace).join "\n " - "Error:\n#{klass}##{meth}:\n#{e.class}: #{e.message.b}\n #{bt}\n" - end - @report << e - e[0, 1] - end - - def initialize # :nodoc: - @report = [] - @errors = @failures = @skips = 0 - @verbose = false - @mutex = Thread::Mutex.new - @info_signal = Signal.list['INFO'] - @repeat_count = nil - end - - def synchronize # :nodoc: - if @mutex then - @mutex.synchronize { yield } - else - yield - end - end - - def process_args args = [] # :nodoc: - options = {} - orig_args = args.dup - - OptionParser.new do |opts| - opts.banner = 'minitest options:' - opts.version = MiniTest::Unit::VERSION - - opts.on '-h', '--help', 'Display this help.' do - puts opts - exit - end - - opts.on '-s', '--seed SEED', Integer, "Sets random seed" do |m| - options[:seed] = m.to_i - end - - opts.on '-v', '--verbose', "Verbose. Show progress processing files." do - options[:verbose] = true - end - - opts.on '-n', '--name PATTERN', "Filter test names on pattern (e.g. /foo/)" do |a| - options[:filter] = a - end - - opts.parse! args - orig_args -= args - end - - unless options[:seed] then - srand - options[:seed] = srand % 0xFFFF - orig_args << "--seed" << options[:seed].to_s - end - - srand options[:seed] - - self.verbose = options[:verbose] - @help = orig_args.map { |s| s =~ /[\s|&<>$()]/ ? s.inspect : s }.join " " - - options - end - - ## - # Begins the full test run. Delegates to +runner+'s #_run method. - - def run args = [] - self.class.runner._run(args) - end - - ## - # Top level driver, controls all output and filtering. - - def _run args = [] - args = process_args args # ARGH!! blame test/unit process_args - self.options.merge! args - - puts "Run options: #{help}" - - self.class.plugins.each do |plugin| - send plugin - break unless report.empty? - end - - return failures + errors if self.test_count > 0 # or return nil... - rescue Interrupt - abort 'Interrupted' - end - - ## - # Runs test suites matching +filter+. - - def run_tests - _run_anything :test - end - - ## - # Writes status to +io+ - - def status io = self.output - format = "%d tests, %d assertions, %d failures, %d errors, %d skips" - io.puts format % [test_count, assertion_count, failures, errors, skips] - end - - ## - # Provides a simple set of guards that you can use in your tests - # to skip execution if it is not applicable. These methods are - # mixed into TestCase as both instance and class methods so you - # can use them inside or outside of the test methods. - # - # def test_something_for_mri - # skip "bug 1234" if jruby? - # # ... - # end - # - # if windows? then - # # ... lots of test methods ... - # end - - module Guard - - ## - # Is this running on jruby? - - def jruby? platform = RUBY_PLATFORM - "java" == platform - end - - ## - # Is this running on mri? - - def maglev? platform = defined?(RUBY_ENGINE) && RUBY_ENGINE - "maglev" == platform - end - - module_function :maglev? - - ## - # Is this running on mri? - - def mri? platform = RUBY_DESCRIPTION - /^ruby/ =~ platform - end - - ## - # Is this running on rubinius? - - def rubinius? platform = defined?(RUBY_ENGINE) && RUBY_ENGINE - "rbx" == platform - end - - ## - # Is this running on windows? - - def windows? platform = RUBY_PLATFORM - /mswin|mingw/ =~ platform - end - end - - ## - # Provides before/after hooks for setup and teardown. These are - # meant for library writers, NOT for regular test authors. See - # #before_setup for an example. - - module LifecycleHooks - ## - # Runs before every test, after setup. This hook is meant for - # libraries to extend minitest. It is not meant to be used by - # test developers. - # - # See #before_setup for an example. - - def after_setup; end - - ## - # Runs before every test, before setup. This hook is meant for - # libraries to extend minitest. It is not meant to be used by - # test developers. - # - # As a simplistic example: - # - # module MyMinitestPlugin - # def before_setup - # super - # # ... stuff to do before setup is run - # end - # - # def after_setup - # # ... stuff to do after setup is run - # super - # end - # - # def before_teardown - # super - # # ... stuff to do before teardown is run - # end - # - # def after_teardown - # # ... stuff to do after teardown is run - # super - # end - # end - # - # class MiniTest::Unit::TestCase - # include MyMinitestPlugin - # end - - def before_setup; end - - ## - # Runs after every test, before teardown. This hook is meant for - # libraries to extend minitest. It is not meant to be used by - # test developers. - # - # See #before_setup for an example. - - def before_teardown; end - - ## - # Runs after every test, after teardown. This hook is meant for - # libraries to extend minitest. It is not meant to be used by - # test developers. - # - # See #before_setup for an example. - - def after_teardown; end - end - - ## - # Subclass TestCase to create your own tests. Typically you'll want a - # TestCase subclass per implementation class. - # - # See MiniTest::Assertions - - class TestCase - include LifecycleHooks - include Guard - extend Guard - - attr_reader :__name__ # :nodoc: - - PASSTHROUGH_EXCEPTIONS = [NoMemoryError, SignalException, - Interrupt, SystemExit] # :nodoc: - - ## - # Runs the tests reporting the status to +runner+ - - def run runner - trap "INFO" do - runner.report.each_with_index do |msg, i| - warn "\n%3d) %s" % [i + 1, msg] - end - warn '' - time = runner.start_time ? Time.now - runner.start_time : 0 - warn "Current Test: %s#%s %.2fs" % [self.class, self.__name__, time] - runner.status $stderr - end if runner.info_signal - - start_time = Time.now - - result = "" - begin - @passed = nil - self.before_setup - self.setup - self.after_setup - self.run_test self.__name__ - result = "." unless io? - time = Time.now - start_time - runner.record self.class, self.__name__, self._assertions, time, nil - @passed = true - rescue *PASSTHROUGH_EXCEPTIONS - raise - rescue Exception => e - @passed = Skip === e - time = Time.now - start_time - runner.record self.class, self.__name__, self._assertions, time, e - result = runner.puke self.class, self.__name__, e - ensure - %w{ before_teardown teardown after_teardown }.each do |hook| - begin - self.send hook - rescue *PASSTHROUGH_EXCEPTIONS - raise - rescue Exception => e - @passed = false - runner.record self.class, self.__name__, self._assertions, time, e - result = runner.puke self.class, self.__name__, e - end - end - trap 'INFO', 'DEFAULT' if runner.info_signal - end - result - end - - alias :run_test :__send__ - - def initialize name # :nodoc: - @__name__ = name - @__io__ = nil - @passed = nil - @@current = self # FIX: make thread local - end - - def self.current # :nodoc: - @@current # FIX: make thread local - end - - ## - # Return the output IO object - - def io - @__io__ = true - MiniTest::Unit.output - end - - ## - # Have we hooked up the IO yet? - - def io? - @__io__ - end - - def self.reset # :nodoc: - @@test_suites = {} - end - - reset - - ## - # Make diffs for this TestCase use #pretty_inspect so that diff - # in assert_equal can be more details. NOTE: this is much slower - # than the regular inspect but much more usable for complex - # objects. - - def self.make_my_diffs_pretty! - require 'pp' - - define_method :mu_pp do |o| - o.pretty_inspect - end - end - - def self.inherited klass # :nodoc: - @@test_suites[klass] = true - super - end - - def self.test_order # :nodoc: - :random - end - - def self.test_suites # :nodoc: - @@test_suites.keys.sort_by { |ts| ts.name.to_s } - end - - def self.test_methods # :nodoc: - methods = public_instance_methods(true).grep(/^test/).map { |m| m.to_s } - - case self.test_order - when :parallel - max = methods.size - ParallelEach.new methods.sort.sort_by { rand max } - when :random then - max = methods.size - methods.sort.sort_by { rand max } - when :alpha, :sorted then - methods.sort - else - raise "Unknown test_order: #{self.test_order.inspect}" - end - end - - ## - # Returns true if the test passed. - - def passed? - @passed - end - - ## - # Runs before every test. Use this to set up before each test - # run. - - def setup; end - - ## - # Runs after every test. Use this to clean up after each test - # run. - - def teardown; end - - include MiniTest::Assertions - end # class TestCase - end # class Unit - - Test = Unit::TestCase -end # module MiniTest - -Minitest = MiniTest # :nodoc: because ugh... I typo this all the time diff --git a/test/lib/profile_test_all.rb b/test/lib/profile_test_all.rb deleted file mode 100644 index 4771b72a..00000000 --- a/test/lib/profile_test_all.rb +++ /dev/null @@ -1,91 +0,0 @@ -# frozen_string_literal: true -# -# purpose: -# Profile memory usage of each tests. -# -# usage: -# RUBY_TEST_ALL_PROFILE=[file] make test-all -# -# output: -# [file] specified by RUBY_TEST_ALL_PROFILE -# If [file] is 'true', then it is ./test_all_profile -# -# collected information: -# - ObjectSpace.memsize_of_all -# - GC.stat -# - /proc/meminfo (some fields, if exists) -# - /proc/self/status (some fields, if exists) -# - /proc/self/statm (if exists) -# - -require 'objspace' - -class MiniTest::Unit::TestCase - alias orig_run run - - file = ENV['RUBY_TEST_ALL_PROFILE'] - file = 'test-all-profile-result' if file == 'true' - TEST_ALL_PROFILE_OUT = open(file, 'w') - TEST_ALL_PROFILE_GC_STAT_HASH = {} - TEST_ALL_PROFILE_BANNER = ['name'] - TEST_ALL_PROFILE_PROCS = [] - - def self.add *name, &b - TEST_ALL_PROFILE_BANNER.concat name - TEST_ALL_PROFILE_PROCS << b - end - - add 'failed?' do |result, tc| - result << (tc.passed? ? 0 : 1) - end - - add 'memsize_of_all' do |result, *| - result << ObjectSpace.memsize_of_all - end - - add *GC.stat.keys do |result, *| - GC.stat(TEST_ALL_PROFILE_GC_STAT_HASH) - result.concat TEST_ALL_PROFILE_GC_STAT_HASH.values - end - - def self.add_proc_meminfo file, fields - return unless FileTest.exist?(file) - regexp = /(#{fields.join("|")}):\s*(\d+) kB/ - # check = {}; fields.each{|e| check[e] = true} - add *fields do |result, *| - text = File.read(file) - text.scan(regexp){ - # check.delete $1 - result << $2 - '' - } - # raise check.inspect unless check.empty? - end - end - - add_proc_meminfo '/proc/meminfo', %w(MemTotal MemFree) - add_proc_meminfo '/proc/self/status', %w(VmPeak VmSize VmHWM VmRSS) - - if FileTest.exist?('/proc/self/statm') - add *%w(size resident share text lib data dt) do |result, *| - result.concat File.read('/proc/self/statm').split(/\s+/) - end - end - - def memprofile_test_all_result_result - result = ["#{self.class}\##{self.__name__.to_s.gsub(/\s+/, '')}"] - TEST_ALL_PROFILE_PROCS.each{|proc| - proc.call(result, self) - } - result.join("\t") - end - - def run runner - result = orig_run(runner) - TEST_ALL_PROFILE_OUT.puts memprofile_test_all_result_result - TEST_ALL_PROFILE_OUT.flush - result - end - - TEST_ALL_PROFILE_OUT.puts TEST_ALL_PROFILE_BANNER.join("\t") -end diff --git a/test/lib/test/unit.rb b/test/lib/test/unit.rb deleted file mode 100644 index 51c8960c..00000000 --- a/test/lib/test/unit.rb +++ /dev/null @@ -1,1175 +0,0 @@ -# frozen_string_literal: true -begin - gem 'minitest', '< 5.0.0' if defined? Gem -rescue Gem::LoadError -end -require 'minitest/unit' -require 'test/unit/assertions' -require_relative '../envutil' -require 'test/unit/testcase' -require 'optparse' - -# See Test::Unit -module Test - ## - # Test::Unit is an implementation of the xUnit testing framework for Ruby. - # - # If you are writing new test code, please use MiniTest instead of Test::Unit. - # - # Test::Unit has been left in the standard library to support legacy test - # suites. - module Unit - TEST_UNIT_IMPLEMENTATION = 'test/unit compatibility layer using minitest' # :nodoc: - - module RunCount # :nodoc: all - @@run_count = 0 - - def self.have_run? - @@run_count.nonzero? - end - - def run(*) - @@run_count += 1 - super - end - - def run_once - return if have_run? - return if $! # don't run if there was an exception - yield - end - module_function :run_once - end - - module Options # :nodoc: all - def initialize(*, &block) - @init_hook = block - @options = nil - super(&nil) - end - - def option_parser - @option_parser ||= OptionParser.new - end - - def process_args(args = []) - return @options if @options - orig_args = args.dup - options = {} - opts = option_parser - setup_options(opts, options) - opts.parse!(args) - orig_args -= args - args = @init_hook.call(args, options) if @init_hook - non_options(args, options) - @run_options = orig_args - @help = orig_args.map { |s| s =~ /[\s|&<>$()]/ ? s.inspect : s }.join " " - @options = options - end - - private - def setup_options(opts, options) - opts.separator 'minitest options:' - opts.version = MiniTest::Unit::VERSION - - opts.on '-h', '--help', 'Display this help.' do - puts opts - exit - end - - opts.on '-s', '--seed SEED', Integer, "Sets random seed" do |m| - options[:seed] = m - end - - opts.on '-v', '--verbose', "Verbose. Show progress processing files." do - options[:verbose] = true - self.verbose = options[:verbose] - end - - opts.on '-n', '--name PATTERN', "Filter test method names on pattern: /REGEXP/, !/REGEXP/ or STRING" do |a| - (options[:filter] ||= []) << a - end - - opts.on '--test-order=random|alpha|sorted', [:random, :alpha, :sorted] do |a| - MiniTest::Unit::TestCase.test_order = a - end - end - - def non_options(files, options) - filter = options[:filter] - if filter - pos_pat = /\A\/(.*)\/\z/ - neg_pat = /\A!\/(.*)\/\z/ - negative, positive = filter.partition {|s| neg_pat =~ s} - if positive.empty? - filter = nil - elsif negative.empty? and positive.size == 1 and pos_pat !~ positive[0] - filter = positive[0] - else - filter = Regexp.union(*positive.map! {|s| Regexp.new(s[pos_pat, 1] || "\\A#{Regexp.quote(s)}\\z")}) - end - unless negative.empty? - negative = Regexp.union(*negative.map! {|s| Regexp.new(s[neg_pat, 1])}) - filter = /\A(?=.*#{filter})(?!.*#{negative})/ - end - if Regexp === filter - # bypass conversion in minitest - def filter.=~(other) # :nodoc: - super unless Regexp === other - end - end - options[:filter] = filter - end - true - end - end - - module Parallel # :nodoc: all - def process_args(args = []) - return @options if @options - options = super - if @options[:parallel] - @files = args - end - options - end - - def non_options(files, options) - @jobserver = nil - if !options[:parallel] and - /(?:\A|\s)--jobserver-(?:auth|fds)=(\d+),(\d+)/ =~ ENV["MAKEFLAGS"] - begin - r = IO.for_fd($1.to_i(10), "rb", autoclose: false) - w = IO.for_fd($2.to_i(10), "wb", autoclose: false) - rescue - r.close if r - nil - else - @jobserver = [r, w] - options[:parallel] ||= 1 - end - end - super - end - - def status(*args) - result = super - raise @interrupt if @interrupt - result - end - - private - def setup_options(opts, options) - super - - opts.separator "parallel test options:" - - options[:retry] = true - - opts.on '-j N', '--jobs N', /\A(t)?(\d+)\z/, "Allow run tests with N jobs at once" do |_, t, a| - options[:testing] = true & t # For testing - options[:parallel] = a.to_i - end - - opts.on '--separate', "Restart job process after one testcase has done" do - options[:parallel] ||= 1 - options[:separate] = true - end - - opts.on '--retry', "Retry running testcase when --jobs specified" do - options[:retry] = true - end - - opts.on '--no-retry', "Disable --retry" do - options[:retry] = false - end - - opts.on '--ruby VAL', "Path to ruby which is used at -j option" do |a| - options[:ruby] = a.split(/ /).reject(&:empty?) - end - end - - class Worker - def self.launch(ruby,args=[]) - io = IO.popen([*ruby, "-W1", - "#{File.dirname(__FILE__)}/unit/parallel.rb", - *args], "rb+") - new(io, io.pid, :waiting) - end - - attr_reader :quit_called - - def initialize(io, pid, status) - @io = io - @pid = pid - @status = status - @file = nil - @real_file = nil - @loadpath = [] - @hooks = {} - @quit_called = false - end - - def puts(*args) - @io.puts(*args) - end - - def run(task,type) - @file = File.basename(task, ".rb") - @real_file = task - begin - puts "loadpath #{[Marshal.dump($:-@loadpath)].pack("m0")}" - @loadpath = $:.dup - puts "run #{task} #{type}" - @status = :prepare - rescue Errno::EPIPE - died - rescue IOError - raise unless /stream closed|closed stream/ =~ $!.message - died - end - end - - def hook(id,&block) - @hooks[id] ||= [] - @hooks[id] << block - self - end - - def read - res = (@status == :quit) ? @io.read : @io.gets - res && res.chomp - end - - def close - @io.close unless @io.closed? - self - rescue IOError - end - - def quit - return if @io.closed? - @quit_called = true - @io.puts "quit" - end - - def kill - Process.kill(:KILL, @pid) - rescue Errno::ESRCH - end - - def died(*additional) - @status = :quit - @io.close - status = $? - if status and status.signaled? - additional[0] ||= SignalException.new(status.termsig) - end - - call_hook(:dead,*additional) - end - - def to_s - if @file and @status != :ready - "#{@pid}=#{@file}" - else - "#{@pid}:#{@status.to_s.ljust(7)}" - end - end - - attr_reader :io, :pid - attr_accessor :status, :file, :real_file, :loadpath - - private - - def call_hook(id,*additional) - @hooks[id] ||= [] - @hooks[id].each{|hook| hook[self,additional] } - self - end - - end - - def flush_job_tokens - if @jobserver - r, w = @jobserver.shift(2) - @jobserver = nil - w << @job_tokens.slice!(0..-1) - r.close - w.close - end - end - - def after_worker_down(worker, e=nil, c=false) - return unless @options[:parallel] - return if @interrupt - flush_job_tokens - warn e if e - real_file = worker.real_file and warn "running file: #{real_file}" - @need_quit = true - warn "" - warn "Some worker was crashed. It seems ruby interpreter's bug" - warn "or, a bug of test/unit/parallel.rb. try again without -j" - warn "option." - warn "" - STDERR.flush - exit c - end - - def after_worker_quit(worker) - return unless @options[:parallel] - return if @interrupt - worker.close - if @jobserver and (token = @job_tokens.slice!(0)) - @jobserver[1] << token - end - @workers.delete(worker) - @dead_workers << worker - @ios = @workers.map(&:io) - end - - def launch_worker - begin - worker = Worker.launch(@options[:ruby], @run_options) - rescue => e - abort "ERROR: Failed to launch job process - #{e.class}: #{e.message}" - end - worker.hook(:dead) do |w,info| - after_worker_quit w - after_worker_down w, *info if !info.empty? && !worker.quit_called - end - @workers << worker - @ios << worker.io - @workers_hash[worker.io] = worker - worker - end - - def delete_worker(worker) - @workers_hash.delete worker.io - @workers.delete worker - @ios.delete worker.io - end - - def quit_workers - return if @workers.empty? - @workers.reject! do |worker| - begin - Timeout.timeout(1) do - worker.quit - end - rescue Errno::EPIPE - rescue Timeout::Error - end - worker.close - end - - return if @workers.empty? - begin - Timeout.timeout(0.2 * @workers.size) do - Process.waitall - end - rescue Timeout::Error - @workers.each do |worker| - worker.kill - end - @worker.clear - end - end - - FakeClass = Struct.new(:name) - def fake_class(name) - (@fake_classes ||= {})[name] ||= FakeClass.new(name) - end - - def deal(io, type, result, rep, shutting_down = false) - worker = @workers_hash[io] - cmd = worker.read - cmd.sub!(/\A\.+/, '') if cmd # read may return nil - case cmd - when '' - # just only dots, ignore - when /^okay$/ - worker.status = :running - when /^ready(!)?$/ - bang = $1 - worker.status = :ready - - unless task = @tasks.shift - worker.quit - return nil - end - if @options[:separate] and not bang - worker.quit - worker = add_worker - end - worker.run(task, type) - @test_count += 1 - - jobs_status(worker) - when /^done (.+?)$/ - begin - r = Marshal.load($1.unpack("m")[0]) - rescue - print "unknown object: #{$1.unpack("m")[0].dump}" - return true - end - result << r[0..1] unless r[0..1] == [nil,nil] - rep << {file: worker.real_file, report: r[2], result: r[3], testcase: r[5]} - $:.push(*r[4]).uniq! - jobs_status(worker) if @options[:job_status] == :replace - return true - when /^record (.+?)$/ - begin - r = Marshal.load($1.unpack("m")[0]) - rescue => e - print "unknown record: #{e.message} #{$1.unpack("m")[0].dump}" - return true - end - record(fake_class(r[0]), *r[1..-1]) - when /^p (.+?)$/ - del_jobs_status - print $1.unpack("m")[0] - jobs_status(worker) if @options[:job_status] == :replace - when /^after (.+?)$/ - @warnings << Marshal.load($1.unpack("m")[0]) - when /^bye (.+?)$/ - after_worker_down worker, Marshal.load($1.unpack("m")[0]) - when /^bye$/, nil - if shutting_down || worker.quit_called - after_worker_quit worker - else - after_worker_down worker - end - else - print "unknown command: #{cmd.dump}\n" - end - return false - end - - def _run_parallel suites, type, result - if @options[:parallel] < 1 - warn "Error: parameter of -j option should be greater than 0." - return - end - - # Require needed thing for parallel running - require 'timeout' - @tasks = @files.dup # Array of filenames. - @need_quit = false - @dead_workers = [] # Array of dead workers. - @warnings = [] - @total_tests = @tasks.size.to_s(10) - rep = [] # FIXME: more good naming - - @workers = [] # Array of workers. - @workers_hash = {} # out-IO => worker - @ios = [] # Array of worker IOs - @job_tokens = String.new(encoding: Encoding::ASCII_8BIT) if @jobserver - begin - [@tasks.size, @options[:parallel]].min.times {launch_worker} - - while _io = IO.select(@ios)[0] - break if _io.any? do |io| - @need_quit or - (deal(io, type, result, rep).nil? and - !@workers.any? {|x| [:running, :prepare].include? x.status}) - end - if @jobserver and @job_tokens and !@tasks.empty? and !@workers.any? {|x| x.status == :ready} - t = @jobserver[0].read_nonblock([@tasks.size, @options[:parallel]].min, exception: false) - if String === t - @job_tokens << t - t.size.times {launch_worker} - end - end - end - rescue Interrupt => ex - @interrupt = ex - return result - ensure - if @interrupt - @ios.select!{|x| @workers_hash[x].status == :running } - while !@ios.empty? && (__io = IO.select(@ios,[],[],10)) - __io[0].reject! {|io| deal(io, type, result, rep, true)} - end - end - - quit_workers - flush_job_tokens - - unless @interrupt || !@options[:retry] || @need_quit - parallel = @options[:parallel] - @options[:parallel] = false - suites, rep = rep.partition {|r| r[:testcase] && r[:file] && r[:report].any? {|e| !e[2].is_a?(MiniTest::Skip)}} - suites.map {|r| r[:file]}.uniq.each {|file| require file} - suites.map! {|r| eval("::"+r[:testcase])} - del_status_line or puts - unless suites.empty? - puts "\n""Retrying..." - _run_suites(suites, type) - end - @options[:parallel] = parallel - end - unless @options[:retry] - del_status_line or puts - end - unless rep.empty? - rep.each do |r| - r[:report].each do |f| - puke(*f) if f - end - end - if @options[:retry] - @errors += rep.map{|x| x[:result][0] }.inject(:+) - @failures += rep.map{|x| x[:result][1] }.inject(:+) - @skips += rep.map{|x| x[:result][2] }.inject(:+) - end - end - unless @warnings.empty? - warn "" - @warnings.uniq! {|w| w[1].message} - @warnings.each do |w| - warn "#{w[0]}: #{w[1].message} (#{w[1].class})" - end - warn "" - end - end - end - - def _run_suites suites, type - _prepare_run(suites, type) - @interrupt = nil - result = [] - GC.start - if @options[:parallel] - _run_parallel suites, type, result - else - suites.each {|suite| - begin - result << _run_suite(suite, type) - rescue Interrupt => e - @interrupt = e - break - end - } - end - del_status_line - result - end - end - - module Skipping # :nodoc: all - def failed(s) - super if !s or @options[:hide_skip] - end - - private - def setup_options(opts, options) - super - - opts.separator "skipping options:" - - options[:hide_skip] = true - - opts.on '-q', '--hide-skip', 'Hide skipped tests' do - options[:hide_skip] = true - end - - opts.on '--show-skip', 'Show skipped tests' do - options[:hide_skip] = false - end - end - - def _run_suites(suites, type) - result = super - report.reject!{|r| r.start_with? "Skipped:" } if @options[:hide_skip] - report.sort_by!{|r| r.start_with?("Skipped:") ? 0 : \ - (r.start_with?("Failure:") ? 1 : 2) } - failed(nil) - result - end - end - - module Statistics - def update_list(list, rec, max) - if i = list.empty? ? 0 : list.bsearch_index {|*a| yield(*a)} - list[i, 0] = [rec] - list[max..-1] = [] if list.size >= max - end - end - - def record(suite, method, assertions, time, error) - if @options.values_at(:longest, :most_asserted).any? - @tops ||= {} - rec = [suite.name, method, assertions, time, error] - if max = @options[:longest] - update_list(@tops[:longest] ||= [], rec, max) {|_,_,_,t,_|t 0 - end - $stdout.flush if flush - @status_line_size = 0 - end - - def add_status(line) - @status_line_size ||= 0 - if @options[:job_status] == :replace - line = line[0...(terminal_width-@status_line_size)] - end - print line - @status_line_size += line.size - end - - def jobs_status(worker) - return if !@options[:job_status] or @options[:verbose] - if @options[:job_status] == :replace - status_line = @workers.map(&:to_s).join(" ") - else - status_line = worker.to_s - end - update_status(status_line) or (puts; nil) - end - - def del_jobs_status - return unless @options[:job_status] == :replace && @status_line_size.nonzero? - del_status_line - end - - def output - (@output ||= nil) || super - end - - def _prepare_run(suites, type) - options[:job_status] ||= :replace if @tty && !@verbose - case options[:color] - when :always - color = true - when :auto, nil - color = (@tty || @options[:job_status] == :replace) && /dumb/ !~ ENV["TERM"] - else - color = false - end - if color - # dircolors-like style - colors = (colors = ENV['TEST_COLORS']) ? Hash[colors.scan(/(\w+)=([^:\n]*)/)] : {} - begin - File.read(File.join(__dir__, "../../colors")).scan(/(\w+)=([^:\n]*)/) do |n, c| - colors[n] ||= c - end - rescue - end - @passed_color = "\e[;#{colors["pass"] || "32"}m" - @failed_color = "\e[;#{colors["fail"] || "31"}m" - @skipped_color = "\e[;#{colors["skip"] || "33"}m" - @reset_color = "\e[m" - else - @passed_color = @failed_color = @skipped_color = @reset_color = "" - end - if color or @options[:job_status] == :replace - @verbose = !options[:parallel] - end - @output = Output.new(self) unless @options[:testing] - filter = options[:filter] - type = "#{type}_methods" - total = if filter - suites.inject(0) {|n, suite| n + suite.send(type).grep(filter).size} - else - suites.inject(0) {|n, suite| n + suite.send(type).size} - end - @test_count = 0 - @total_tests = total.to_s(10) - end - - def new_test(s) - @test_count += 1 - update_status(s) - end - - def update_status(s) - count = @test_count.to_s(10).rjust(@total_tests.size) - del_status_line(false) - print(@passed_color) - add_status("[#{count}/#{@total_tests}]") - print(@reset_color) - add_status(" #{s}") - $stdout.print "\r" if @options[:job_status] == :replace and !@verbose - $stdout.flush - end - - def _print(s); $stdout.print(s); end - def succeed; del_status_line; end - - def failed(s) - return if s and @options[:job_status] != :replace - sep = "\n" - @report_count ||= 0 - report.each do |msg| - if msg.start_with? "Skipped:" - if @options[:hide_skip] - del_status_line - next - end - color = @skipped_color - else - color = @failed_color - end - msg = msg.split(/$/, 2) - $stdout.printf("%s%s%3d) %s%s%s\n", - sep, color, @report_count += 1, - msg[0], @reset_color, msg[1]) - sep = nil - end - report.clear - end - - def initialize - super - @tty = $stdout.tty? - end - - def run(*args) - result = super - puts "\nruby -v: #{RUBY_DESCRIPTION}" - result - end - - private - def setup_options(opts, options) - super - - opts.separator "status line options:" - - options[:job_status] = nil - - opts.on '--jobs-status [TYPE]', [:normal, :replace, :none], - "Show status of jobs every file; Disabled when --jobs isn't specified." do |type| - options[:job_status] = (type || :normal if type != :none) - end - - opts.on '--color[=WHEN]', - [:always, :never, :auto], - "colorize the output. WHEN defaults to 'always'", "or can be 'never' or 'auto'." do |c| - options[:color] = c || :always - end - - opts.on '--tty[=WHEN]', - [:yes, :no], - "force to output tty control. WHEN defaults to 'yes'", "or can be 'no'." do |c| - @tty = c != :no - end - end - - class Output < Struct.new(:runner) # :nodoc: all - def puts(*a) $stdout.puts(*a) unless a.empty? end - def respond_to_missing?(*a) $stdout.respond_to?(*a) end - def method_missing(*a, &b) $stdout.__send__(*a, &b) end - - def print(s) - case s - when /\A(.*\#.*) = \z/ - runner.new_test($1) - when /\A(.* s) = \z/ - runner.add_status(" = #$1") - when /\A\.+\z/ - runner.succeed - when /\A[EFS]\z/ - runner.failed(s) - else - $stdout.print(s) - end - end - end - end - - module LoadPathOption # :nodoc: all - def non_options(files, options) - begin - require "rbconfig" - rescue LoadError - warn "#{caller(1, 1)[0]}: warning: Parallel running disabled because can't get path to ruby; run specify with --ruby argument" - options[:parallel] = nil - else - options[:ruby] ||= [RbConfig.ruby] - end - - super - end - - def setup_options(parser, options) - super - parser.separator "load path options:" - parser.on '-Idirectory', 'Add library load path' do |dirs| - dirs.split(':').each { |d| $LOAD_PATH.unshift d } - end - end - end - - module GlobOption # :nodoc: all - @@testfile_prefix = "test" - @@testfile_suffix = "test" - - def setup_options(parser, options) - super - parser.separator "globbing options:" - parser.on '-b', '--basedir=DIR', 'Base directory of test suites.' do |dir| - options[:base_directory] = dir - end - parser.on '-x', '--exclude REGEXP', 'Exclude test files on pattern.' do |pattern| - (options[:reject] ||= []) << pattern - end - end - - def non_options(files, options) - paths = [options.delete(:base_directory), nil].uniq - if reject = options.delete(:reject) - reject_pat = Regexp.union(reject.map {|r| %r"#{r}"}) - end - files.map! {|f| - f = f.tr(File::ALT_SEPARATOR, File::SEPARATOR) if File::ALT_SEPARATOR - ((paths if /\A\.\.?(?:\z|\/)/ !~ f) || [nil]).any? do |prefix| - if prefix - path = f.empty? ? prefix : "#{prefix}/#{f}" - else - next if f.empty? - path = f - end - if !(match = (Dir["#{path}/**/#{@@testfile_prefix}_*.rb"] + Dir["#{path}/**/*_#{@@testfile_suffix}.rb"]).uniq).empty? - if reject - match.reject! {|n| - n[(prefix.length+1)..-1] if prefix - reject_pat =~ n - } - end - break match - elsif !reject or reject_pat !~ f and File.exist? path - break path - end - end or - raise ArgumentError, "file not found: #{f}" - } - files.flatten! - super(files, options) - end - end - - module GCStressOption # :nodoc: all - def setup_options(parser, options) - super - parser.separator "GC options:" - parser.on '--[no-]gc-stress', 'Set GC.stress as true' do |flag| - options[:gc_stress] = flag - end - end - - def non_options(files, options) - if options.delete(:gc_stress) - MiniTest::Unit::TestCase.class_eval do - oldrun = instance_method(:run) - define_method(:run) do |runner| - begin - gc_stress, GC.stress = GC.stress, true - oldrun.bind(self).call(runner) - ensure - GC.stress = gc_stress - end - end - end - end - super - end - end - - module RequireFiles # :nodoc: all - def non_options(files, options) - return false if !super - errors = {} - result = false - files.each {|f| - d = File.dirname(path = File.realpath(f)) - unless $:.include? d - $: << d - end - begin - require path unless options[:parallel] - result = true - rescue LoadError - next if errors[$!.message] - errors[$!.message] = true - puts "#{f}: #{$!}" - end - } - result - end - end - - module RepeatOption # :nodoc: all - def setup_options(parser, options) - super - options[:repeat_count] = nil - parser.separator "repeat options:" - parser.on '--repeat-count=NUM', "Number of times to repeat", Integer do |n| - options[:repeat_count] = n - end - end - - def _run_anything(type) - @repeat_count = @options[:repeat_count] - super - end - end - - module ExcludesOption # :nodoc: all - class ExcludedMethods < Struct.new(:excludes) - def exclude(name, reason) - excludes[name] = reason - end - - def exclude_from(klass) - excludes = self.excludes - pattern = excludes.keys.grep(Regexp).tap {|k| - break (Regexp.new(k.join('|')) unless k.empty?) - } - klass.class_eval do - public_instance_methods(false).each do |method| - if excludes[method] or (pattern and pattern =~ method) - remove_method(method) - end - end - public_instance_methods(true).each do |method| - if excludes[method] or (pattern and pattern =~ method) - undef_method(method) - end - end - end - end - - def self.load(dirs, name) - return unless dirs and name - instance = nil - dirs.each do |dir| - path = File.join(dir, name.gsub(/::/, '/') + ".rb") - begin - src = File.read(path) - rescue Errno::ENOENT - nil - else - instance ||= new({}) - instance.instance_eval(src, path) - end - end - instance - end - end - - def setup_options(parser, options) - super - if excludes = ENV["EXCLUDES"] - excludes = excludes.split(File::PATH_SEPARATOR) - end - options[:excludes] = excludes || [] - parser.separator "excludes options:" - parser.on '-X', '--excludes-dir DIRECTORY', "Directory name of exclude files" do |d| - options[:excludes].concat d.split(File::PATH_SEPARATOR) - end - end - - def _run_suite(suite, type) - if ex = ExcludedMethods.load(@options[:excludes], suite.name) - ex.exclude_from(suite) - end - super - end - end - - module SubprocessOption - def setup_options(parser, options) - super - parser.separator "subprocess options:" - parser.on '--subprocess-timeout-scale NUM', "Scale subprocess timeout", Float do |scale| - raise OptionParser::InvalidArgument, "timeout scale must be positive" unless scale > 0 - options[:timeout_scale] = scale - end - if scale = options[:timeout_scale] or - (scale = ENV["RUBY_TEST_SUBPROCESS_TIMEOUT_SCALE"] and (scale = scale.to_f) > 0) - EnvUtil.subprocess_timeout_scale = scale - end - end - end - - class Runner < MiniTest::Unit # :nodoc: all - include Test::Unit::Options - include Test::Unit::StatusLine - include Test::Unit::Parallel - include Test::Unit::Statistics - include Test::Unit::Skipping - include Test::Unit::GlobOption - include Test::Unit::RepeatOption - include Test::Unit::LoadPathOption - include Test::Unit::GCStressOption - include Test::Unit::ExcludesOption - include Test::Unit::SubprocessOption - include Test::Unit::RunCount - - class << self; undef autorun; end - - @@stop_auto_run = false - def self.autorun - at_exit { - Test::Unit::RunCount.run_once { - exit(Test::Unit::Runner.new.run(ARGV) || true) - } unless @@stop_auto_run - } unless @@installed_at_exit - @@installed_at_exit = true - end - - alias mini_run_suite _run_suite - - # Overriding of MiniTest::Unit#puke - def puke klass, meth, e - # TODO: - # this overriding is for minitest feature that skip messages are - # hidden when not verbose (-v), note this is temporally. - n = report.size - rep = super - if MiniTest::Skip === e and /no message given\z/ =~ e.message - report.slice!(n..-1) - rep = "." - end - rep - end - end - - class AutoRunner # :nodoc: all - class Runner < Test::Unit::Runner - include Test::Unit::RequireFiles - end - - attr_accessor :to_run, :options - - def initialize(force_standalone = false, default_dir = nil, argv = ARGV) - @force_standalone = force_standalone - @runner = Runner.new do |files, options| - options[:base_directory] ||= default_dir - files << default_dir if files.empty? and default_dir - @to_run = files - yield self if block_given? - files - end - Runner.runner = @runner - @options = @runner.option_parser - if @force_standalone - @options.banner.sub!(/\[options\]/, '\& tests...') - end - @argv = argv - end - - def process_args(*args) - @runner.process_args(*args) - !@to_run.empty? - end - - def run - if @force_standalone and not process_args(@argv) - abort @options.banner - end - @runner.run(@argv) || true - end - - def self.run(*args) - new(*args).run - end - end - - class ProxyError < StandardError # :nodoc: all - def initialize(ex) - @message = ex.message - @backtrace = ex.backtrace - end - - attr_accessor :message, :backtrace - end - end -end - -module MiniTest # :nodoc: all - class Unit - end -end - -class MiniTest::Unit::TestCase # :nodoc: all - test_order = self.test_order - class << self - attr_writer :test_order - undef test_order - end - def self.test_order - defined?(@test_order) ? @test_order : superclass.test_order - end - self.test_order = test_order - undef run_test - RUN_TEST_TRACE = "#{__FILE__}:#{__LINE__+3}:in `run_test'".freeze - def run_test(name) - progname, $0 = $0, "#{$0}: #{self.class}##{name}" - self.__send__(name) - ensure - $@.delete(RUN_TEST_TRACE) if $@ - $0 = progname - end -end - -Test::Unit::Runner.autorun diff --git a/test/lib/test/unit/assertions.rb b/test/lib/test/unit/assertions.rb deleted file mode 100644 index 10fac047..00000000 --- a/test/lib/test/unit/assertions.rb +++ /dev/null @@ -1,943 +0,0 @@ -# frozen_string_literal: true -require 'minitest/unit' -require 'pp' - -module Test - module Unit - module Assertions - include MiniTest::Assertions - - def mu_pp(obj) #:nodoc: - obj.pretty_inspect.chomp - end - - MINI_DIR = File.join(File.dirname(File.dirname(File.expand_path(__FILE__))), "minitest") #:nodoc: - - # :call-seq: - # assert(test, [failure_message]) - # - #Tests if +test+ is true. - # - #+msg+ may be a String or a Proc. If +msg+ is a String, it will be used - #as the failure message. Otherwise, the result of calling +msg+ will be - #used as the message if the assertion fails. - # - #If no +msg+ is given, a default message will be used. - # - # assert(false, "This was expected to be true") - def assert(test, *msgs) - case msg = msgs.first - when String, Proc - when nil - msgs.shift - else - bt = caller.reject { |s| s.start_with?(MINI_DIR) } - raise ArgumentError, "assertion message must be String or Proc, but #{msg.class} was given.", bt - end unless msgs.empty? - super - end - - # :call-seq: - # assert_block( failure_message = nil ) - # - #Tests the result of the given block. If the block does not return true, - #the assertion will fail. The optional +failure_message+ argument is the same as in - #Assertions#assert. - # - # assert_block do - # [1, 2, 3].any? { |num| num < 1 } - # end - def assert_block(*msgs) - assert yield, *msgs - end - - # :call-seq: - # assert_raise( *args, &block ) - # - #Tests if the given block raises an exception. Acceptable exception - #types may be given as optional arguments. If the last argument is a - #String, it will be used as the error message. - # - # assert_raise do #Fails, no Exceptions are raised - # end - # - # assert_raise NameError do - # puts x #Raises NameError, so assertion succeeds - # end - def assert_raise(*exp, &b) - case exp.last - when String, Proc - msg = exp.pop - end - - begin - yield - rescue MiniTest::Skip => e - return e if exp.include? MiniTest::Skip - raise e - rescue Exception => e - expected = exp.any? { |ex| - if ex.instance_of? Module then - e.kind_of? ex - else - e.instance_of? ex - end - } - - assert expected, proc { - exception_details(e, message(msg) {"#{mu_pp(exp)} exception expected, not"}.call) - } - - return e - ensure - unless e - exp = exp.first if exp.size == 1 - - flunk(message(msg) {"#{mu_pp(exp)} expected but nothing was raised"}) - end - end - end - - def assert_raises(*exp, &b) - raise NoMethodError, "use assert_raise", caller - end - - # :call-seq: - # assert_raise_with_message(exception, expected, msg = nil, &block) - # - #Tests if the given block raises an exception with the expected - #message. - # - # assert_raise_with_message(RuntimeError, "foo") do - # nil #Fails, no Exceptions are raised - # end - # - # assert_raise_with_message(RuntimeError, "foo") do - # raise ArgumentError, "foo" #Fails, different Exception is raised - # end - # - # assert_raise_with_message(RuntimeError, "foo") do - # raise "bar" #Fails, RuntimeError is raised but the message differs - # end - # - # assert_raise_with_message(RuntimeError, "foo") do - # raise "foo" #Raises RuntimeError with the message, so assertion succeeds - # end - def assert_raise_with_message(exception, expected, msg = nil, &block) - case expected - when String - assert = :assert_equal - when Regexp - assert = :assert_match - else - raise TypeError, "Expected #{expected.inspect} to be a kind of String or Regexp, not #{expected.class}" - end - - ex = m = nil - EnvUtil.with_default_internal(expected.encoding) do - ex = assert_raise(exception, msg || proc {"Exception(#{exception}) with message matches to #{expected.inspect}"}) do - yield - end - m = ex.message - end - msg = message(msg, "") {"Expected Exception(#{exception}) was raised, but the message doesn't match"} - - if assert == :assert_equal - assert_equal(expected, m, msg) - else - msg = message(msg) { "Expected #{mu_pp expected} to match #{mu_pp m}" } - assert expected =~ m, msg - block.binding.eval("proc{|_|$~=_}").call($~) - end - ex - end - - # :call-seq: - # assert_nothing_raised( *args, &block ) - # - #If any exceptions are given as arguments, the assertion will - #fail if one of those exceptions are raised. Otherwise, the test fails - #if any exceptions are raised. - # - #The final argument may be a failure message. - # - # assert_nothing_raised RuntimeError do - # raise Exception #Assertion passes, Exception is not a RuntimeError - # end - # - # assert_nothing_raised do - # raise Exception #Assertion fails - # end - def assert_nothing_raised(*args) - self._assertions += 1 - if Module === args.last - msg = nil - else - msg = args.pop - end - begin - line = __LINE__; yield - rescue MiniTest::Skip - raise - rescue Exception => e - bt = e.backtrace - as = e.instance_of?(MiniTest::Assertion) - if as - ans = /\A#{Regexp.quote(__FILE__)}:#{line}:in /o - bt.reject! {|ln| ans =~ ln} - end - if ((args.empty? && !as) || - args.any? {|a| a.instance_of?(Module) ? e.is_a?(a) : e.class == a }) - msg = message(msg) { "Exception raised:\n<#{mu_pp(e)}>" } - raise MiniTest::Assertion, msg.call, bt - else - raise - end - end - end - - # :call-seq: - # assert_nothing_thrown( failure_message = nil, &block ) - # - #Fails if the given block uses a call to Kernel#throw, and - #returns the result of the block otherwise. - # - #An optional failure message may be provided as the final argument. - # - # assert_nothing_thrown "Something was thrown!" do - # throw :problem? - # end - def assert_nothing_thrown(msg=nil) - begin - ret = yield - rescue ArgumentError => error - raise error if /\Auncaught throw (.+)\z/m !~ error.message - msg = message(msg) { "<#{$1}> was thrown when nothing was expected" } - flunk(msg) - end - assert(true, "Expected nothing to be thrown") - ret - end - - # :call-seq: - # assert_throw( tag, failure_message = nil, &block ) - # - #Fails unless the given block throws +tag+, returns the caught - #value otherwise. - # - #An optional failure message may be provided as the final argument. - # - # tag = Object.new - # assert_throw(tag, "#{tag} was not thrown!") do - # throw tag - # end - def assert_throw(tag, msg = nil) - ret = catch(tag) do - begin - yield(tag) - rescue UncaughtThrowError => e - thrown = e.tag - end - msg = message(msg) { - "Expected #{mu_pp(tag)} to have been thrown"\ - "#{%Q[, not #{thrown}] if thrown}" - } - assert(false, msg) - end - assert(true) - ret - end - - # :call-seq: - # assert_equal( expected, actual, failure_message = nil ) - # - #Tests if +expected+ is equal to +actual+. - # - #An optional failure message may be provided as the final argument. - def assert_equal(exp, act, msg = nil) - msg = message(msg) { - exp_str = mu_pp(exp) - act_str = mu_pp(act) - exp_comment = '' - act_comment = '' - if exp_str == act_str - if (exp.is_a?(String) && act.is_a?(String)) || - (exp.is_a?(Regexp) && act.is_a?(Regexp)) - exp_comment = " (#{exp.encoding})" - act_comment = " (#{act.encoding})" - elsif exp.is_a?(Float) && act.is_a?(Float) - exp_str = "%\#.#{Float::DIG+2}g" % exp - act_str = "%\#.#{Float::DIG+2}g" % act - elsif exp.is_a?(Time) && act.is_a?(Time) - if exp.subsec * 1000_000_000 == exp.nsec - exp_comment = " (#{exp.nsec}[ns])" - else - exp_comment = " (subsec=#{exp.subsec})" - end - if act.subsec * 1000_000_000 == act.nsec - act_comment = " (#{act.nsec}[ns])" - else - act_comment = " (subsec=#{act.subsec})" - end - elsif exp.class != act.class - # a subclass of Range, for example. - exp_comment = " (#{exp.class})" - act_comment = " (#{act.class})" - end - elsif !Encoding.compatible?(exp_str, act_str) - if exp.is_a?(String) && act.is_a?(String) - exp_str = exp.dump - act_str = act.dump - exp_comment = " (#{exp.encoding})" - act_comment = " (#{act.encoding})" - else - exp_str = exp_str.dump - act_str = act_str.dump - end - end - "<#{exp_str}>#{exp_comment} expected but was\n<#{act_str}>#{act_comment}" - } - assert(exp == act, msg) - end - - # :call-seq: - # assert_not_nil( expression, failure_message = nil ) - # - #Tests if +expression+ is not nil. - # - #An optional failure message may be provided as the final argument. - def assert_not_nil(exp, msg=nil) - msg = message(msg) { "<#{mu_pp(exp)}> expected to not be nil" } - assert(!exp.nil?, msg) - end - - # :call-seq: - # assert_not_equal( expected, actual, failure_message = nil ) - # - #Tests if +expected+ is not equal to +actual+. - # - #An optional failure message may be provided as the final argument. - def assert_not_equal(exp, act, msg=nil) - msg = message(msg) { "<#{mu_pp(exp)}> expected to be != to\n<#{mu_pp(act)}>" } - assert(exp != act, msg) - end - - # :call-seq: - # assert_no_match( regexp, string, failure_message = nil ) - # - #Tests if the given Regexp does not match a given String. - # - #An optional failure message may be provided as the final argument. - def assert_no_match(regexp, string, msg=nil) - assert_instance_of(Regexp, regexp, "The first argument to assert_no_match should be a Regexp.") - self._assertions -= 1 - msg = message(msg) { "<#{mu_pp(regexp)}> expected to not match\n<#{mu_pp(string)}>" } - assert(regexp !~ string, msg) - end - - # :call-seq: - # assert_not_same( expected, actual, failure_message = nil ) - # - #Tests if +expected+ is not the same object as +actual+. - #This test uses Object#equal? to test equality. - # - #An optional failure message may be provided as the final argument. - # - # assert_not_same("x", "x") #Succeeds - def assert_not_same(expected, actual, message="") - msg = message(msg) { build_message(message, < -with id expected to not be equal\\? to - -with id . -EOT - assert(!actual.equal?(expected), msg) - end - - # :call-seq: - # assert_respond_to( object, method, failure_message = nil ) - # - #Tests if the given Object responds to +method+. - # - #An optional failure message may be provided as the final argument. - # - # assert_respond_to("hello", :reverse) #Succeeds - # assert_respond_to("hello", :does_not_exist) #Fails - def assert_respond_to(obj, (meth, *priv), msg = nil) - unless priv.empty? - msg = message(msg) { - "Expected #{mu_pp(obj)} (#{obj.class}) to respond to ##{meth}#{" privately" if priv[0]}" - } - return assert obj.respond_to?(meth, *priv), msg - end - #get rid of overcounting - if caller_locations(1, 1)[0].path.start_with?(MINI_DIR) - return if obj.respond_to?(meth) - end - super(obj, meth, msg) - end - - # :call-seq: - # assert_not_respond_to( object, method, failure_message = nil ) - # - #Tests if the given Object does not respond to +method+. - # - #An optional failure message may be provided as the final argument. - # - # assert_not_respond_to("hello", :reverse) #Fails - # assert_not_respond_to("hello", :does_not_exist) #Succeeds - def assert_not_respond_to(obj, (meth, *priv), msg = nil) - unless priv.empty? - msg = message(msg) { - "Expected #{mu_pp(obj)} (#{obj.class}) to not respond to ##{meth}#{" privately" if priv[0]}" - } - return assert !obj.respond_to?(meth, *priv), msg - end - #get rid of overcounting - if caller_locations(1, 1)[0].path.start_with?(MINI_DIR) - return unless obj.respond_to?(meth) - end - refute_respond_to(obj, meth, msg) - end - - # :call-seq: - # assert_send( +send_array+, failure_message = nil ) - # - # Passes if the method send returns a true value. - # - # +send_array+ is composed of: - # * A receiver - # * A method - # * Arguments to the method - # - # Example: - # assert_send(["Hello world", :include?, "Hello"]) # -> pass - # assert_send(["Hello world", :include?, "Goodbye"]) # -> fail - def assert_send send_ary, m = nil - recv, msg, *args = send_ary - m = message(m) { - if args.empty? - argsstr = "" - else - (argsstr = mu_pp(args)).sub!(/\A\[(.*)\]\z/m, '(\1)') - end - "Expected #{mu_pp(recv)}.#{msg}#{argsstr} to return true" - } - assert recv.__send__(msg, *args), m - end - - # :call-seq: - # assert_not_send( +send_array+, failure_message = nil ) - # - # Passes if the method send doesn't return a true value. - # - # +send_array+ is composed of: - # * A receiver - # * A method - # * Arguments to the method - # - # Example: - # assert_not_send([[1, 2], :member?, 1]) # -> fail - # assert_not_send([[1, 2], :member?, 4]) # -> pass - def assert_not_send send_ary, m = nil - recv, msg, *args = send_ary - m = message(m) { - if args.empty? - argsstr = "" - else - (argsstr = mu_pp(args)).sub!(/\A\[(.*)\]\z/m, '(\1)') - end - "Expected #{mu_pp(recv)}.#{msg}#{argsstr} to return false" - } - assert !recv.__send__(msg, *args), m - end - - ms = instance_methods(true).map {|sym| sym.to_s } - ms.grep(/\Arefute_/) do |m| - mname = ('assert_not_'.dup << m.to_s[/.*?_(.*)/, 1]) - alias_method(mname, m) unless ms.include? mname - end - alias assert_include assert_includes - alias assert_not_include assert_not_includes - - def assert_all?(obj, m = nil, &blk) - failed = [] - obj.each do |*a, &b| - unless blk.call(*a, &b) - failed << (a.size > 1 ? a : a[0]) - end - end - assert(failed.empty?, message(m) {failed.pretty_inspect}) - end - - def assert_not_all?(obj, m = nil, &blk) - failed = [] - obj.each do |*a, &b| - if blk.call(*a, &b) - failed << (a.size > 1 ? a : a[0]) - end - end - assert(failed.empty?, message(m) {failed.pretty_inspect}) - end - - # compatibility with test-unit - alias pend skip - - if defined?(RubyVM::InstructionSequence) - def syntax_check(code, fname, line) - code = code.dup.force_encoding(Encoding::UTF_8) - RubyVM::InstructionSequence.compile(code, fname, fname, line) - :ok - end - else - def syntax_check(code, fname, line) - code = code.b - code.sub!(/\A(?:\xef\xbb\xbf)?(\s*\#.*$)*(\n)?/n) { - "#$&#{"\n" if $1 && !$2}BEGIN{throw tag, :ok}\n" - } - code = code.force_encoding(Encoding::UTF_8) - catch {|tag| eval(code, binding, fname, line - 1)} - end - end - - def prepare_syntax_check(code, fname = caller_locations(2, 1)[0], mesg = fname.to_s, verbose: nil) - verbose, $VERBOSE = $VERBOSE, verbose - case - when Array === fname - fname, line = *fname - when defined?(fname.path) && defined?(fname.lineno) - fname, line = fname.path, fname.lineno - else - line = 1 - end - yield(code, fname, line, mesg) - ensure - $VERBOSE = verbose - end - - def assert_valid_syntax(code, *args) - prepare_syntax_check(code, *args) do |src, fname, line, mesg| - yield if defined?(yield) - assert_nothing_raised(SyntaxError, mesg) do - assert_equal(:ok, syntax_check(src, fname, line), mesg) - end - end - end - - def assert_syntax_error(code, error, *args) - prepare_syntax_check(code, *args) do |src, fname, line, mesg| - yield if defined?(yield) - e = assert_raise(SyntaxError, mesg) do - syntax_check(src, fname, line) - end - assert_match(error, e.message, mesg) - e - end - end - - def assert_normal_exit(testsrc, message = '', child_env: nil, **opt) - assert_valid_syntax(testsrc, caller_locations(1, 1)[0]) - if child_env - child_env = [child_env] - else - child_env = [] - end - out, _, status = EnvUtil.invoke_ruby(child_env + %W'-W0', testsrc, true, :merge_to_stdout, **opt) - assert !status.signaled?, FailDesc[status, message, out] - end - - FailDesc = proc do |status, message = "", out = ""| - pid = status.pid - now = Time.now - faildesc = proc do - if signo = status.termsig - signame = Signal.signame(signo) - sigdesc = "signal #{signo}" - end - log = EnvUtil.diagnostic_reports(signame, pid, now) - if signame - sigdesc = "SIG#{signame} (#{sigdesc})" - end - if status.coredump? - sigdesc = "#{sigdesc} (core dumped)" - end - full_message = ''.dup - message = message.call if Proc === message - if message and !message.empty? - full_message << message << "\n" - end - full_message << "pid #{pid}" - full_message << " exit #{status.exitstatus}" if status.exited? - full_message << " killed by #{sigdesc}" if sigdesc - if out and !out.empty? - full_message << "\n" << out.b.gsub(/^/, '| ') - full_message.sub!(/(? marshal_error - ignore_stderr = nil - end - if res - if bt = res.backtrace - bt.each do |l| - l.sub!(/\A-:(\d+)/){"#{file}:#{line + $1.to_i}"} - end - bt.concat(caller) - else - res.set_backtrace(caller) - end - raise res unless SystemExit === res - end - - # really is it succeed? - unless ignore_stderr - # the body of assert_separately must not output anything to detect error - assert(stderr.empty?, FailDesc[status, "assert_separately failed with error message", stderr]) - end - assert(status.success?, FailDesc[status, "assert_separately failed", stderr]) - raise marshal_error if marshal_error - end - - def assert_warning(pat, msg = nil) - stderr = EnvUtil.with_default_internal(pat.encoding) { - EnvUtil.verbose_warning { - yield - } - } - msg = message(msg) {diff pat, stderr} - assert(pat === stderr, msg) - end - - def assert_warn(*args) - assert_warning(*args) {$VERBOSE = false; yield} - end - - def assert_no_memory_leak(args, prepare, code, message=nil, limit: 2.0, rss: false, **opt) - require_relative '../../memory_status' - raise MiniTest::Skip, "unsupported platform" unless defined?(Memory::Status) - - token = "\e[7;1m#{$$.to_s}:#{Time.now.strftime('%s.%L')}:#{rand(0x10000).to_s(16)}:\e[m" - token_dump = token.dump - token_re = Regexp.quote(token) - envs = args.shift if Array === args and Hash === args.first - args = [ - "--disable=gems", - "-r", File.expand_path("../../../memory_status", __FILE__), - *args, - "-v", "-", - ] - if defined? Memory::NO_MEMORY_LEAK_ENVS then - envs ||= {} - newenvs = envs.merge(Memory::NO_MEMORY_LEAK_ENVS) { |_, _, _| break } - envs = newenvs if newenvs - end - args.unshift(envs) if envs - cmd = [ - 'END {STDERR.puts '"#{token_dump}"'"FINAL=#{Memory::Status.new}"}', - prepare, - 'STDERR.puts('"#{token_dump}"'"START=#{$initial_status = Memory::Status.new}")', - '$initial_size = $initial_status.size', - code, - 'GC.start', - ].join("\n") - _, err, status = EnvUtil.invoke_ruby(args, cmd, true, true, **opt) - before = err.sub!(/^#{token_re}START=(\{.*\})\n/, '') && Memory::Status.parse($1) - after = err.sub!(/^#{token_re}FINAL=(\{.*\})\n/, '') && Memory::Status.parse($1) - assert(status.success?, FailDesc[status, message, err]) - ([:size, (rss && :rss)] & after.members).each do |n| - b = before[n] - a = after[n] - next unless a > 0 and b > 0 - assert_operator(a.fdiv(b), :<, limit, message(message) {"#{n}: #{b} => #{a}"}) - end - rescue LoadError - skip - end - - def assert_cpu_usage_low(msg = nil, pct: 0.01) - require 'benchmark' - - tms = Benchmark.measure(msg || '') { yield } - max = pct * tms.real - if tms.real < 0.1 # TIME_QUANTUM_USEC in thread_pthread.c - warn "test #{msg || 'assert_cpu_usage_low'} too short to be accurate" - end - - # kernel resolution can limit the minimum time we can measure - # [ruby-core:81540] - min_hz = windows? ? 67 : 100 - min_measurable = 1.0 / min_hz - min_measurable *= 1.10 # add a little (10%) to account for misc. overheads - if max < min_measurable - max = min_measurable - end - - assert_operator tms.total, :<=, max, msg - end - - def assert_is_minus_zero(f) - assert(1.0/f == -Float::INFINITY, "#{f} is not -0.0") - end - - def assert_file - AssertFile - end - - # pattern_list is an array which contains regexp and :*. - # :* means any sequence. - # - # pattern_list is anchored. - # Use [:*, regexp, :*] for non-anchored match. - def assert_pattern_list(pattern_list, actual, message=nil) - rest = actual - anchored = true - pattern_list.each_with_index {|pattern, i| - if pattern == :* - anchored = false - else - if anchored - match = /\A#{pattern}/.match(rest) - else - match = pattern.match(rest) - end - unless match - msg = message(msg) { - expect_msg = "Expected #{mu_pp pattern}\n" - if /\n[^\n]/ =~ rest - actual_mesg = +"to match\n" - rest.scan(/.*\n+/) { - actual_mesg << ' ' << $&.inspect << "+\n" - } - actual_mesg.sub!(/\+\n\z/, '') - else - actual_mesg = "to match " + mu_pp(rest) - end - actual_mesg << "\nafter #{i} patterns with #{actual.length - rest.length} characters" - expect_msg + actual_mesg - } - assert false, msg - end - rest = match.post_match - anchored = true - end - } - if anchored - assert_equal("", rest) - end - end - - # threads should respond to shift method. - # Array can be used. - def assert_join_threads(threads, message = nil) - errs = [] - values = [] - while th = threads.shift - begin - values << th.value - rescue Exception - errs << [th, $!] - end - end - if !errs.empty? - msg = "exceptions on #{errs.length} threads:\n" + - errs.map {|t, err| - "#{t.inspect}:\n" + - err.backtrace.map.with_index {|line, i| - if i == 0 - "#{line}: #{err.message} (#{err.class})" - else - "\tfrom #{line}" - end - }.join("\n") - }.join("\n---\n") - if message - msg = "#{message}\n#{msg}" - end - raise MiniTest::Assertion, msg - end - values - end - - class << (AssertFile = Struct.new(:failure_message).new) - include Assertions - def assert_file_predicate(predicate, *args) - if /\Anot_/ =~ predicate - predicate = $' - neg = " not" - end - result = File.__send__(predicate, *args) - result = !result if neg - mesg = "Expected file ".dup << args.shift.inspect - mesg << "#{neg} to be #{predicate}" - mesg << mu_pp(args).sub(/\A\[(.*)\]\z/m, '(\1)') unless args.empty? - mesg << " #{failure_message}" if failure_message - assert(result, mesg) - end - alias method_missing assert_file_predicate - - def for(message) - clone.tap {|a| a.failure_message = message} - end - end - - class AllFailures - attr_reader :failures - - def initialize - @count = 0 - @failures = {} - end - - def for(key) - @count += 1 - yield - rescue Exception => e - @failures[key] = [@count, e] - end - - def foreach(*keys) - keys.each do |key| - @count += 1 - begin - yield key - rescue Exception => e - @failures[key] = [@count, e] - end - end - end - - def message - i = 0 - total = @count.to_s - fmt = "%#{total.size}d" - @failures.map {|k, (n, v)| - v = v.message - "\n#{i+=1}. [#{fmt%n}/#{total}] Assertion for #{k.inspect}\n#{v.b.gsub(/^/, ' | ').force_encoding(v.encoding)}" - }.join("\n") - end - - def pass? - @failures.empty? - end - end - - def assert_all_assertions(msg = nil) - all = AllFailures.new - yield all - ensure - assert(all.pass?, message(msg) {all.message.chomp(".")}) - end - alias all_assertions assert_all_assertions - - def assert_all_assertions_foreach(msg = nil, *keys, &block) - all = AllFailures.new - all.foreach(*keys, &block) - ensure - assert(all.pass?, message(msg) {all.message.chomp(".")}) - end - alias all_assertions_foreach assert_all_assertions_foreach - - def build_message(head, template=nil, *arguments) #:nodoc: - template &&= template.chomp - template.gsub(/\G((?:[^\\]|\\.)*?)(\\)?\?/) { $1 + ($2 ? "?" : mu_pp(arguments.shift)) } - end - - def message(msg = nil, *args, &default) # :nodoc: - if Proc === msg - super(nil, *args) do - ary = [msg.call, (default.call if default)].compact.reject(&:empty?) - if 1 < ary.length - ary[0...-1] = ary[0...-1].map {|str| str.sub(/(? e - begin - trace = e.backtrace || ['unknown method'] - err = ["#{trace.shift}: #{e.message} (#{e.class})"] + trace.map{|t| t.prepend("\t") } - - _report "bye", Marshal.dump(err.join("\n")) - rescue Errno::EPIPE;end - exit - ensure - @stdin.close if @stdin - @stdout.close if @stdout - end - end - - def _report(res, *args) # :nodoc: - @stdout.write(args.empty? ? "#{res}\n" : "#{res} #{args.pack("m0")}\n") - end - - def puke(klass, meth, e) # :nodoc: - if e.is_a?(MiniTest::Skip) - new_e = MiniTest::Skip.new(e.message) - new_e.set_backtrace(e.backtrace) - e = new_e - end - @partial_report << [klass.name, meth, e.is_a?(MiniTest::Assertion) ? e : ProxyError.new(e)] - super - end - - def record(suite, method, assertions, time, error) # :nodoc: - case error - when nil - when MiniTest::Assertion, MiniTest::Skip - case error.cause - when nil, MiniTest::Assertion, MiniTest::Skip - else - bt = error.backtrace - error = error.class.new(error.message) - error.set_backtrace(bt) - end - else - error = ProxyError.new(error) - end - _report "record", Marshal.dump([suite.name, method, assertions, time, error]) - super - end - end - end -end - -if $0 == __FILE__ - module Test - module Unit - class TestCase < MiniTest::Unit::TestCase # :nodoc: all - undef on_parallel_worker? - def on_parallel_worker? - true - end - end - end - end - require 'rubygems' - module Gem # :nodoc: - end - class Gem::TestCase < MiniTest::Unit::TestCase # :nodoc: - @@project_dir = File.expand_path('../../../../..', __FILE__) - end - - Test::Unit::Worker.new.run(ARGV) -end diff --git a/test/lib/test/unit/testcase.rb b/test/lib/test/unit/testcase.rb deleted file mode 100644 index 58cfbcab..00000000 --- a/test/lib/test/unit/testcase.rb +++ /dev/null @@ -1,36 +0,0 @@ -# frozen_string_literal: true -require 'test/unit/assertions' - -module Test - module Unit - # remove silly TestCase class - remove_const(:TestCase) if defined?(self::TestCase) - - class TestCase < MiniTest::Unit::TestCase # :nodoc: all - include Assertions - - def on_parallel_worker? - false - end - - def run runner - @options = runner.options - super runner - end - - def self.test_order - :sorted - end - - def self.method_added(name) - super - return unless name.to_s.start_with?("test_") - @test_methods ||= {} - if @test_methods[name] - warn "test/unit warning: method #{ self }##{ name } is redefined" - end - @test_methods[name] = true - end - end - end -end diff --git a/test/lib/tracepointchecker.rb b/test/lib/tracepointchecker.rb deleted file mode 100644 index 47822ece..00000000 --- a/test/lib/tracepointchecker.rb +++ /dev/null @@ -1,126 +0,0 @@ -# frozen_string_literal: true -module TracePointChecker - STATE = { - count: 0, - running: false, - } - - module ZombieTraceHunter - def tracepoint_capture_stat_get - TracePoint.stat.map{|k, (activated, deleted)| - deleted = 0 unless @tracepoint_captured_singlethread - [k, activated, deleted] - } - end - - def before_setup - @tracepoint_captured_singlethread = (Thread.list.size == 1) - @tracepoint_captured_stat = tracepoint_capture_stat_get() - super - end - - def after_teardown - super - - # detect zombie traces. - assert_equal( - @tracepoint_captured_stat, - tracepoint_capture_stat_get(), - "The number of active/deleted trace events was changed" - ) - # puts "TracePoint - deleted: #{deleted}" if deleted > 0 - - TracePointChecker.check if STATE[:running] - end - end - - MAIN_THREAD = Thread.current - TRACES = [] - - def self.prefix event - case event - when :call, :return - :n - when :c_call, :c_return - :c - when :b_call, :b_return - :b - end - end - - def self.clear_call_stack - Thread.current[:call_stack] = [] - end - - def self.call_stack - stack = Thread.current[:call_stack] - stack = clear_call_stack unless stack - stack - end - - def self.verbose_out label, method - puts label => call_stack, :count => STATE[:count], :method => method - end - - def self.method_label tp - "#{prefix(tp.event)}##{tp.method_id}" - end - - def self.start verbose: false, stop_at_failure: false - call_events = %i(a_call) - return_events = %i(a_return) - clear_call_stack - - STATE[:running] = true - - TRACES << TracePoint.new(*call_events){|tp| - next if Thread.current != MAIN_THREAD - - method = method_label(tp) - call_stack.push method - STATE[:count] += 1 - - verbose_out :psuh, method if verbose - } - - TRACES << TracePoint.new(*return_events){|tp| - next if Thread.current != MAIN_THREAD - STATE[:count] += 1 - - method = "#{prefix(tp.event)}##{tp.method_id}" - verbose_out :pop1, method if verbose - - stored_method = call_stack.pop - next if stored_method.nil? - - verbose_out :pop2, method if verbose - - if stored_method != method - stop if stop_at_failure - RubyVM::SDR() if defined? RubyVM::SDR() - call_stack.clear - raise "#{stored_method} is expected, but #{method} (count: #{STATE[:count]})" - end - } - - TRACES.each{|trace| trace.enable} - end - - def self.stop - STATE[:running] = true - TRACES.each{|trace| trace.disable} - TRACES.clear - end - - def self.check - TRACES.each{|trace| - raise "trace #{trace} should not be deactivated" unless trace.enabled? - } - end -end if defined?(TracePoint.stat) - -class ::Test::Unit::TestCase - include TracePointChecker::ZombieTraceHunter -end if defined?(TracePointChecker) - -# TracePointChecker.start verbose: false diff --git a/test/lib/with_different_ofs.rb b/test/lib/with_different_ofs.rb deleted file mode 100644 index b7ac646f..00000000 --- a/test/lib/with_different_ofs.rb +++ /dev/null @@ -1,18 +0,0 @@ -# frozen_string_literal: true -module DifferentOFS - module WithDifferentOFS - def setup - super - @ofs, $, = $,, "-" - end - def teardown - $, = @ofs - super - end - end - - def self.extended(klass) - super(klass) - klass.const_set(:DifferentOFS, Class.new(klass).class_eval {include WithDifferentOFS}).name - end -end diff --git a/test/lib/zombie_hunter.rb b/test/lib/zombie_hunter.rb deleted file mode 100644 index ea94844b..00000000 --- a/test/lib/zombie_hunter.rb +++ /dev/null @@ -1,13 +0,0 @@ -# frozen_string_literal: true - -# There might be compiler processes executed by MJIT -return if RubyVM::MJIT.enabled? - -module ZombieHunter - def after_teardown - super - assert_empty(Process.waitall) - end -end - -Test::Unit::TestCase.include ZombieHunter diff --git a/test/rexml/listener.rb b/test/listener.rb similarity index 100% rename from test/rexml/listener.rb rename to test/listener.rb diff --git a/test/rexml/parse/test_document_type_declaration.rb b/test/parse/test_document_type_declaration.rb similarity index 100% rename from test/rexml/parse/test_document_type_declaration.rb rename to test/parse/test_document_type_declaration.rb diff --git a/test/rexml/parse/test_element.rb b/test/parse/test_element.rb similarity index 100% rename from test/rexml/parse/test_element.rb rename to test/parse/test_element.rb diff --git a/test/rexml/parse/test_notation_declaration.rb b/test/parse/test_notation_declaration.rb similarity index 100% rename from test/rexml/parse/test_notation_declaration.rb rename to test/parse/test_notation_declaration.rb diff --git a/test/rexml/parse/test_processing_instruction.rb b/test/parse/test_processing_instruction.rb similarity index 100% rename from test/rexml/parse/test_processing_instruction.rb rename to test/parse/test_processing_instruction.rb diff --git a/test/rexml/parser/test_sax2.rb b/test/parser/test_sax2.rb similarity index 100% rename from test/rexml/parser/test_sax2.rb rename to test/parser/test_sax2.rb diff --git a/test/rexml/parser/test_stream.rb b/test/parser/test_stream.rb similarity index 100% rename from test/rexml/parser/test_stream.rb rename to test/parser/test_stream.rb diff --git a/test/rexml/parser/test_tree.rb b/test/parser/test_tree.rb similarity index 100% rename from test/rexml/parser/test_tree.rb rename to test/parser/test_tree.rb diff --git a/test/rexml/parser/test_ultra_light.rb b/test/parser/test_ultra_light.rb similarity index 100% rename from test/rexml/parser/test_ultra_light.rb rename to test/parser/test_ultra_light.rb diff --git a/test/rexml/rexml_test_utils.rb b/test/rexml/rexml_test_utils.rb deleted file mode 100644 index 8bb002ce..00000000 --- a/test/rexml/rexml_test_utils.rb +++ /dev/null @@ -1,10 +0,0 @@ -# frozen_string_literal: false - -require "test/unit" -require "rexml/document" - -module REXMLTestUtils - def fixture_path(*components) - File.join(File.dirname(__FILE__), "data", *components) - end -end diff --git a/test/run.rb b/test/run.rb new file mode 100755 index 00000000..089318b0 --- /dev/null +++ b/test/run.rb @@ -0,0 +1,13 @@ +#!/usr/bin/env ruby + +$VERBOSE = true + +base_dir = File.dirname(File.expand_path(__dir__)) +lib_dir = File.join(base_dir, "lib") +test_dir = File.join(base_dir, "test") + +$LOAD_PATH.unshift(lib_dir) + +require_relative "helper" + +exit(Test::Unit::AutoRunner.run(true, test_dir)) diff --git a/test/rexml/test_attribute.rb b/test/test_attribute.rb similarity index 90% rename from test/rexml/test_attribute.rb rename to test/test_attribute.rb index 5175bd44..b66e462d 100644 --- a/test/rexml/test_attribute.rb +++ b/test/test_attribute.rb @@ -1,5 +1,3 @@ -require_relative "rexml_test_utils" - module REXMLTests class AttributeTest < Test::Unit::TestCase def test_empty_prefix diff --git a/test/rexml/test_attributes.rb b/test/test_attributes.rb similarity index 99% rename from test/rexml/test_attributes.rb rename to test/test_attributes.rb index b0d87221..91fc68a5 100644 --- a/test/rexml/test_attributes.rb +++ b/test/test_attributes.rb @@ -1,7 +1,5 @@ # frozen_string_literal: false -require_relative "rexml_test_utils" - module REXMLTests class AttributesTester < Test::Unit::TestCase include REXML diff --git a/test/rexml/test_attributes_mixin.rb b/test/test_attributes_mixin.rb similarity index 96% rename from test/rexml/test_attributes_mixin.rb rename to test/test_attributes_mixin.rb index 3de34f8c..2b9108cb 100644 --- a/test/rexml/test_attributes_mixin.rb +++ b/test/test_attributes_mixin.rb @@ -1,7 +1,5 @@ # frozen_string_literal: false -require_relative "rexml_test_utils" - module REXMLTests class TestAttributes < Test::Unit::TestCase def setup diff --git a/test/rexml/test_changing_encoding.rb b/test/test_changing_encoding.rb similarity index 96% rename from test/rexml/test_changing_encoding.rb rename to test/test_changing_encoding.rb index 73a61ef7..a2dc0725 100644 --- a/test/rexml/test_changing_encoding.rb +++ b/test/test_changing_encoding.rb @@ -1,7 +1,6 @@ # -*- coding: utf-8 -*- # frozen_string_literal: false -require_relative "rexml_test_utils" require 'rexml/encoding' module REXMLTests diff --git a/test/rexml/test_comment.rb b/test/test_comment.rb similarity index 93% rename from test/rexml/test_comment.rb rename to test/test_comment.rb index aa026bc9..f6f4d809 100644 --- a/test/rexml/test_comment.rb +++ b/test/test_comment.rb @@ -1,7 +1,5 @@ # frozen_string_literal: false -require_relative "rexml_test_utils" - module REXMLTests class CommentTester < Test::Unit::TestCase # Bug #5278 diff --git a/test/rexml/test_contrib.rb b/test/test_contrib.rb similarity index 99% rename from test/rexml/test_contrib.rb rename to test/test_contrib.rb index 8462b3c2..ee5be2f6 100644 --- a/test/rexml/test_contrib.rb +++ b/test/test_contrib.rb @@ -1,15 +1,12 @@ # coding: binary # frozen_string_literal: false -require_relative "rexml_test_utils" - -require "rexml/document" require "rexml/parseexception" require "rexml/formatters/default" module REXMLTests class ContribTester < Test::Unit::TestCase - include REXMLTestUtils + include Helper::Fixture include REXML XML_STRING_01 = < #{@encoded_root}", out ) + assert_equal( "#{@encoded_root}".b, out ) end # * Given an encoded document, accessing text and attribute nodes @@ -97,7 +96,7 @@ def test_parse_utf16 end def test_parse_utf16_with_utf8_default_internal - EnvUtil.with_default_internal("UTF-8") do + with_default_internal("UTF-8") do utf16 = File.open(fixture_path("utf16.xml")) do |f| REXML::Document.new(f) end diff --git a/test/rexml/test_entity.rb b/test/test_entity.rb similarity index 99% rename from test/rexml/test_entity.rb rename to test/test_entity.rb index 9bb26db6..a2b262f7 100644 --- a/test/rexml/test_entity.rb +++ b/test/test_entity.rb @@ -1,7 +1,5 @@ # frozen_string_literal: false -require_relative "rexml_test_utils" - require 'rexml/entity' require 'rexml/source' diff --git a/test/rexml/test_instruction.rb b/test/test_instruction.rb similarity index 90% rename from test/rexml/test_instruction.rb rename to test/test_instruction.rb index 96fa909e..5451e367 100644 --- a/test/rexml/test_instruction.rb +++ b/test/test_instruction.rb @@ -1,5 +1,3 @@ -require_relative "rexml_test_utils" - module REXMLTests class InstructionTest < Test::Unit::TestCase def test_target_nil diff --git a/test/rexml/test_jaxen.rb b/test/test_jaxen.rb similarity index 98% rename from test/rexml/test_jaxen.rb rename to test/test_jaxen.rb index 9640b829..6038e88e 100644 --- a/test/rexml/test_jaxen.rb +++ b/test/test_jaxen.rb @@ -1,5 +1,4 @@ # frozen_string_literal: false -require_relative 'rexml_test_utils' require "rexml/document" require "rexml/xpath" @@ -9,7 +8,7 @@ module REXMLTests class JaxenTester < Test::Unit::TestCase - include REXMLTestUtils + include Helper::Fixture include REXML def test_axis ; process_test_case("axis") ; end diff --git a/test/rexml/test_light.rb b/test/test_light.rb similarity index 97% rename from test/rexml/test_light.rb rename to test/test_light.rb index 99bd9cac..3a10fb2c 100644 --- a/test/rexml/test_light.rb +++ b/test/test_light.rb @@ -1,11 +1,11 @@ # frozen_string_literal: false -require_relative "rexml_test_utils" + require "rexml/light/node" require "rexml/parsers/lightparser" module REXMLTests class LightTester < Test::Unit::TestCase - include REXMLTestUtils + include Helper::Fixture include REXML::Light def test_parse_large diff --git a/test/rexml/test_lightparser.rb b/test/test_lightparser.rb similarity index 84% rename from test/rexml/test_lightparser.rb rename to test/test_lightparser.rb index 1aeac072..533f9fb8 100644 --- a/test/rexml/test_lightparser.rb +++ b/test/test_lightparser.rb @@ -1,10 +1,10 @@ # frozen_string_literal: false -require_relative 'rexml_test_utils' + require 'rexml/parsers/lightparser' module REXMLTests class LightParserTester < Test::Unit::TestCase - include REXMLTestUtils + include Helper::Fixture include REXML def test_parsing File.open(fixture_path("documentation.xml")) do |f| diff --git a/test/rexml/test_listener.rb b/test/test_listener.rb similarity index 97% rename from test/rexml/test_listener.rb rename to test/test_listener.rb index 322d368b..5e40d7f7 100644 --- a/test/rexml/test_listener.rb +++ b/test/test_listener.rb @@ -1,14 +1,11 @@ # coding: binary # frozen_string_literal: false -require_relative 'rexml_test_utils' - -require 'rexml/document' require 'rexml/streamlistener' module REXMLTests class BaseTester < Test::Unit::TestCase - include REXMLTestUtils + include Helper::Fixture def test_empty return unless defined? @listener # Empty. diff --git a/test/rexml/test_martin_fowler.rb b/test/test_martin_fowler.rb similarity index 95% rename from test/rexml/test_martin_fowler.rb rename to test/test_martin_fowler.rb index 216df846..3d27c7a0 100644 --- a/test/rexml/test_martin_fowler.rb +++ b/test/test_martin_fowler.rb @@ -1,7 +1,5 @@ # frozen_string_literal: false -require_relative "rexml_test_utils" - module REXMLTests class OrderTesterMF < Test::Unit::TestCase DOC = < diff --git a/test/rexml/test_preceding_sibling.rb b/test/test_preceding_sibling.rb similarity index 96% rename from test/rexml/test_preceding_sibling.rb rename to test/test_preceding_sibling.rb index c92e4549..7e661eb0 100644 --- a/test/rexml/test_preceding_sibling.rb +++ b/test/test_preceding_sibling.rb @@ -1,8 +1,6 @@ # frozen_string_literal: false # ISSUE 32 -require_relative "rexml_test_utils" - module REXMLTests # daz - for report by Dan Kohn in: # http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/156328 diff --git a/test/rexml/test_pullparser.rb b/test/test_pullparser.rb similarity index 98% rename from test/rexml/test_pullparser.rb rename to test/test_pullparser.rb index 6af53aeb..53a985ba 100644 --- a/test/rexml/test_pullparser.rb +++ b/test/test_pullparser.rb @@ -1,7 +1,5 @@ # frozen_string_literal: false -require_relative "rexml_test_utils" - require 'rexml/parsers/pullparser' module REXMLTests diff --git a/test/rexml/test_rexml_issuezilla.rb b/test/test_rexml_issuezilla.rb similarity index 82% rename from test/rexml/test_rexml_issuezilla.rb rename to test/test_rexml_issuezilla.rb index 1c54c9d5..7bcbefcf 100644 --- a/test/rexml/test_rexml_issuezilla.rb +++ b/test/test_rexml_issuezilla.rb @@ -1,10 +1,8 @@ # frozen_string_literal: false -require_relative 'rexml_test_utils' -require 'rexml/document' module REXMLTests class TestIssuezillaParsing < Test::Unit::TestCase - include REXMLTestUtils + include Helper::Fixture def test_rexml doc = File.open(fixture_path("ofbiz-issues-full-177.xml")) do |f| REXML::Document.new(f) diff --git a/test/rexml/test_sax.rb b/test/test_sax.rb similarity index 99% rename from test/rexml/test_sax.rb rename to test/test_sax.rb index 00539f0d..6f775183 100644 --- a/test/rexml/test_sax.rb +++ b/test/test_sax.rb @@ -1,12 +1,11 @@ # frozen_string_literal: false -require_relative "rexml_test_utils" + require 'rexml/sax2listener' require 'rexml/parsers/sax2parser' -require 'rexml/document' module REXMLTests class SAX2Tester < Test::Unit::TestCase - include REXMLTestUtils + include Helper::Fixture include REXML def test_characters d = Document.new( "@blah@" ) diff --git a/test/rexml/test_stream.rb b/test/test_stream.rb similarity index 98% rename from test/rexml/test_stream.rb rename to test/test_stream.rb index fd9d0c62..545d5349 100644 --- a/test/rexml/test_stream.rb +++ b/test/test_stream.rb @@ -1,7 +1,5 @@ # frozen_string_literal: false -require_relative "rexml_test_utils" - require 'rexml/streamlistener' require 'stringio' diff --git a/test/rexml/test_text.rb b/test/test_text.rb similarity index 98% rename from test/rexml/test_text.rb rename to test/test_text.rb index e9a246e2..bae21656 100644 --- a/test/rexml/test_text.rb +++ b/test/test_text.rb @@ -1,7 +1,5 @@ # frozen_string_literal: false -require_relative "rexml_test_utils" - module REXMLTests class TextTester < Test::Unit::TestCase include REXML diff --git a/test/rexml/test_ticket_80.rb b/test/test_ticket_80.rb similarity index 98% rename from test/rexml/test_ticket_80.rb rename to test/test_ticket_80.rb index 70557e4d..daebdc59 100644 --- a/test/rexml/test_ticket_80.rb +++ b/test/test_ticket_80.rb @@ -7,8 +7,6 @@ # copy: (C) CopyLoose 2006 Bib Development Team atdot #------------------------------------------------------------------------------ -require_relative "rexml_test_utils" - module REXMLTests class Ticket80 < Test::Unit::TestCase diff --git a/test/rexml/test_validation_rng.rb b/test/test_validation_rng.rb similarity index 99% rename from test/rexml/test_validation_rng.rb rename to test/test_validation_rng.rb index c6821131..a29e8d86 100644 --- a/test/rexml/test_validation_rng.rb +++ b/test/test_validation_rng.rb @@ -1,7 +1,5 @@ # frozen_string_literal: false -require_relative "rexml_test_utils" - require "rexml/validation/relaxng" module REXMLTests diff --git a/test/rexml/test_xml_declaration.rb b/test/test_xml_declaration.rb similarity index 97% rename from test/rexml/test_xml_declaration.rb rename to test/test_xml_declaration.rb index e9bd538b..6db54bab 100644 --- a/test/rexml/test_xml_declaration.rb +++ b/test/test_xml_declaration.rb @@ -3,8 +3,6 @@ # Created by Henrik Mårtensson on 2007-02-18. # Copyright (c) 2007. All rights reserved. -require_relative "rexml_test_utils" - module REXMLTests class TestXmlDeclaration < Test::Unit::TestCase def setup diff --git a/test/rexml/xpath/test_attribute.rb b/test/xpath/test_attribute.rb similarity index 96% rename from test/rexml/xpath/test_attribute.rb rename to test/xpath/test_attribute.rb index d1e088f9..b778ff81 100644 --- a/test/rexml/xpath/test_attribute.rb +++ b/test/xpath/test_attribute.rb @@ -1,7 +1,5 @@ # frozen_string_literal: false -require_relative "../rexml_test_utils" - module REXMLTests class TestXPathAttribute < Test::Unit::TestCase def setup diff --git a/test/rexml/xpath/test_axis_preceding_sibling.rb b/test/xpath/test_axis_preceding_sibling.rb similarity index 96% rename from test/rexml/xpath/test_axis_preceding_sibling.rb rename to test/xpath/test_axis_preceding_sibling.rb index 0e208505..9c44ad63 100644 --- a/test/rexml/xpath/test_axis_preceding_sibling.rb +++ b/test/xpath/test_axis_preceding_sibling.rb @@ -1,7 +1,5 @@ # frozen_string_literal: false -require_relative "../rexml_test_utils" - module REXMLTests class TestXPathAxisPredcedingSibling < Test::Unit::TestCase include REXML diff --git a/test/rexml/xpath/test_axis_self.rb b/test/xpath/test_axis_self.rb similarity index 93% rename from test/rexml/xpath/test_axis_self.rb rename to test/xpath/test_axis_self.rb index da934349..4e422f54 100644 --- a/test/rexml/xpath/test_axis_self.rb +++ b/test/xpath/test_axis_self.rb @@ -1,7 +1,5 @@ # frozen_string_literal: false -require_relative "../rexml_test_utils" - module REXMLTests class TestXPathAxisSelf < Test::Unit::TestCase def test_only diff --git a/test/rexml/xpath/test_base.rb b/test/xpath/test_base.rb similarity index 99% rename from test/rexml/xpath/test_base.rb rename to test/xpath/test_base.rb index 9eac3716..5156bbbe 100644 --- a/test/rexml/xpath/test_base.rb +++ b/test/xpath/test_base.rb @@ -1,10 +1,8 @@ # frozen_string_literal: false -require_relative "../rexml_test_utils" - module REXMLTests class TestXPathBase < Test::Unit::TestCase - include REXMLTestUtils + include Helper::Fixture include REXML SOURCE = <<-EOF diff --git a/test/rexml/xpath/test_compare.rb b/test/xpath/test_compare.rb similarity index 99% rename from test/rexml/xpath/test_compare.rb rename to test/xpath/test_compare.rb index c2d25fc3..11d11e55 100644 --- a/test/rexml/xpath/test_compare.rb +++ b/test/xpath/test_compare.rb @@ -1,7 +1,5 @@ # frozen_string_literal: false -require_relative "../rexml_test_utils" - module REXMLTests class TestXPathCompare < Test::Unit::TestCase def match(xml, xpath) diff --git a/test/rexml/xpath/test_node.rb b/test/xpath/test_node.rb similarity index 95% rename from test/rexml/xpath/test_node.rb rename to test/xpath/test_node.rb index 185dbd59..742bfbba 100644 --- a/test/rexml/xpath/test_node.rb +++ b/test/xpath/test_node.rb @@ -1,8 +1,6 @@ # -*- coding: utf-8 -*- # frozen_string_literal: false -require_relative "../rexml_test_utils" - module REXMLTests class TestXPathNode < Test::Unit::TestCase def matches(xml, xpath) diff --git a/test/rexml/xpath/test_predicate.rb b/test/xpath/test_predicate.rb similarity index 98% rename from test/rexml/xpath/test_predicate.rb rename to test/xpath/test_predicate.rb index 32bd9b80..c8520712 100644 --- a/test/rexml/xpath/test_predicate.rb +++ b/test/xpath/test_predicate.rb @@ -1,7 +1,5 @@ # frozen_string_literal: false -require_relative "../rexml_test_utils" - require "rexml/xpath" require "rexml/parsers/xpathparser" diff --git a/test/rexml/xpath/test_text.rb b/test/xpath/test_text.rb similarity index 98% rename from test/rexml/xpath/test_text.rb rename to test/xpath/test_text.rb index 854f554d..dccc4c83 100644 --- a/test/rexml/xpath/test_text.rb +++ b/test/xpath/test_text.rb @@ -1,7 +1,5 @@ # frozen_string_literal: false -require_relative "../rexml_test_utils" - require 'rexml/element' require 'rexml/xpath' From 635e351c9ffc247cae2837e53665f481a8cf2b80 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Thu, 7 Jan 2021 07:06:44 +0900 Subject: [PATCH 15/56] ci: use TruffleRuby only on Ubuntu It seems that it's not available on macOS and Windows. --- .github/workflows/test.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index b40a82b5..b7e25209 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -18,7 +18,9 @@ jobs: - "2.6" - "2.7" - jruby - - truffleruby + include: + - runs-on: ubuntu-latest + ruby-version: truffleruby steps: - uses: actions/checkout@v2 - uses: ruby/setup-ruby@v1 From 150b43ab6b41fed63d5a9bfa681149f116f30d05 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Thu, 7 Jan 2021 07:13:22 +0900 Subject: [PATCH 16/56] ci: disable JRuby on Windows It can't find rake installed by bundle install. --- .github/workflows/test.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index b7e25209..c627719e 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -18,6 +18,9 @@ jobs: - "2.6" - "2.7" - jruby + exclude: + - runs-on: windows-latest + ruby-version: jruby include: - runs-on: ubuntu-latest ruby-version: truffleruby From e044720d9c4a4abf07e7ae4110aa555110c7e96c Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Thu, 7 Jan 2021 07:34:59 +0900 Subject: [PATCH 17/56] test: ensure comparing as Hash --- test/test_core.rb | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/test/test_core.rb b/test/test_core.rb index 9909cc80..544c137a 100644 --- a/test/test_core.rb +++ b/test/test_core.rb @@ -1499,8 +1499,10 @@ def test_ticket_138 "" => attribute("version", "1.0"), }, } - assert_equal(expected, doc.root.attributes) - assert_equal(expected, REXML::Document.new(doc.root.to_s).root.attributes) + assert_equal(expected, + doc.root.attributes.to_h) + assert_equal(expected, + REXML::Document.new(doc.root.to_s).root.attributes.to_h) end def test_empty_doc From 731185c91337dbb396f75c527534260b5bdbabbb Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Thu, 7 Jan 2021 07:35:17 +0900 Subject: [PATCH 18/56] ci: disable TruffleRuby Because there are some test failures. --- .github/workflows/test.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index c627719e..1ff1b845 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -21,9 +21,9 @@ jobs: exclude: - runs-on: windows-latest ruby-version: jruby - include: - - runs-on: ubuntu-latest - ruby-version: truffleruby + # include: + # - runs-on: ubuntu-latest + # ruby-version: truffleruby steps: - uses: actions/checkout@v2 - uses: ruby/setup-ruby@v1 From 233c2ef6906a29fc273ba5363cbd05e4745d16a5 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Thu, 7 Jan 2021 09:06:11 +0900 Subject: [PATCH 19/56] ci use "rake test" for JRuby on Windows This is workaround of https://github.com/rubygems/rubygems/issues/3256 . --- .github/workflows/test.yml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 1ff1b845..7654e9e9 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -18,9 +18,6 @@ jobs: - "2.6" - "2.7" - jruby - exclude: - - runs-on: windows-latest - ruby-version: jruby # include: # - runs-on: ubuntu-latest # ruby-version: truffleruby @@ -31,7 +28,7 @@ jobs: ruby-version: ${{ matrix.ruby-version }} bundler-cache: true - name: Test - run: bundle exec rake + run: bundle exec rake test gem: name: ${{ matrix.ruby-version }} on ${{ matrix.runs-on }} From 5c2ebef31dcba56c08d123fb28e43db29622bbcf Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Wed, 27 Jan 2021 18:39:44 -0600 Subject: [PATCH 20/56] Enhanced RDoc for Element (#41) --- lib/rexml/element.rb | 210 ++++++++++++++++++++++++++++++++----------- 1 file changed, 159 insertions(+), 51 deletions(-) diff --git a/lib/rexml/element.rb b/lib/rexml/element.rb index c706a7c2..1f81a4be 100644 --- a/lib/rexml/element.rb +++ b/lib/rexml/element.rb @@ -30,32 +30,62 @@ class Element < Parent # whitespace handling. attr_accessor :context - # Constructor - # arg:: - # if not supplied, will be set to the default value. - # If a String, the name of this object will be set to the argument. - # If an Element, the object will be shallowly cloned; name, - # attributes, and namespaces will be copied. Children will +not+ be - # copied. - # parent:: - # if supplied, must be a Parent, and will be used as - # the parent of this object. - # context:: - # If supplied, must be a hash containing context items. Context items - # include: - # * :respect_whitespace the value of this is :+all+ or an array of - # strings being the names of the elements to respect - # whitespace for. Defaults to :+all+. - # * :compress_whitespace the value can be :+all+ or an array of - # strings being the names of the elements to ignore whitespace on. + # :call-seq: + # Element.new(name = 'UNDEFINED', parent = nil, context = nil) -> new_element + # Element.new(element, parent = nil, context = nil) -> new_element + # + # Returns a new \REXML::Element object. + # + # When no arguments are given, + # returns an element with name 'UNDEFINED': + # + # e = Element.new # => + # e.class # => REXML::Element + # e.name # => "UNDEFINED" + # + # When only argument +name+ is given, + # returns an element of the given name: + # + # Element.new('foo') # => + # + # When only argument +element+ is given, it must be an \Element object; + # returns a shallow copy of the given element: + # + # e0 = Element.new('foo') + # Element.new(e0) # => + # + # When argument +parent+ is also given, it must be a Parent object: + # + # e = Element.new('foo', Parent.new) + # e.parent # => #]> + # + # When argument +context+ is also given, it must be a hash + # that may contain the following entries: + # + # :respect_whitespace:: + # +:all+ (default) or an array of names of elements + # whose whitespace is to be respected. + # :compress_whitespace:: + # +:all+ or an array of names of elements + # whose whitespace is to be ignored. # Overrides :+respect_whitespace+. - # * :ignore_whitespace_nodes the value can be :+all+ or an array - # of strings being the names of the elements in which to ignore - # whitespace-only nodes. If this is set, Text nodes which contain only - # whitespace will not be added to the document tree. - # * :raw can be :+all+, or an array of strings being the names of - # the elements to process in raw mode. In raw mode, special - # characters in text is not converted to or from entities. + # :ignore_whitespace_nodes:: + # +:all+ or an array of names of elements + # to be ignored if whitespace-only; + # "ignored" here means "not added to the document tree." + # :raw:: + # +:all+, or an array names of elements to be processed in raw mode. + # In raw mode, special characters in text are not converted to or from entities. + # + # Example: + # + # context = { + # respect_whitespace: :all, + # raw: :all + # } + # e = Element.new('foo', Parent.new, context) + # e.context # => {:respect_whitespace=>:all, :raw=>:all} + # def initialize( arg = UNDEFINED, parent=nil, context=nil ) super(parent) @@ -74,6 +104,27 @@ def initialize( arg = UNDEFINED, parent=nil, context=nil ) end end + # :call-seq: + # inspect -> string + # + # Returns a string representation of the element. + # + # For an element with no attributes and no children, shows the element name: + # + # Element.new.inspect # => "" + # + # Shows attributes, if any: + # + # e = Element.new('foo') + # e.add_attributes({'bar' => 0, 'baz' => 1}) + # e.inspect # => "" + # + # Shows an ellipsis (...), if there are child elements: + # + # e.add_element(Element.new('bar')) + # e.add_element(Element.new('baz')) + # e.inspect # => " ... " + # def inspect rv = "<#@expanded_name" @@ -89,46 +140,103 @@ def inspect end end - - # Creates a shallow copy of self. - # d = Document.new "" - # new_a = d.root.clone - # puts new_a # => "" + # :call-seq: + # clone -> new_element + # + # Returns a shallow copy of the element, containing the name and attributes, + # but not the parent or children: + # + # e = Element.new('foo') + # e.add_attributes({'bar' => 0, 'baz' => 1}) + # e.clone # => + # def clone self.class.new self end - # Evaluates to the root node of the document that this element - # belongs to. If this element doesn't belong to a document, but does - # belong to another Element, the parent's root will be returned, until the - # earliest ancestor is found. - # - # Note that this is not the same as the document element. - # In the following example, is the document element, and the root - # node is the parent node of the document element. You may ask yourself - # why the root node is useful: consider the doctype and XML declaration, - # and any processing instructions before the document element... they - # are children of the root node, or siblings of the document element. - # The only time this isn't true is when an Element is created that is - # not part of any Document. In this case, the ancestor that has no - # parent acts as the root node. - # d = Document.new '' - # a = d[1] ; c = a[1][1] - # d.root_node == d # TRUE - # a.root_node # namely, d - # c.root_node # again, d + # :call-seq: + # root_node -> document or element + # + # Returns the most distant ancestor of +self+. + # + # When the element is part of a document, + # returns the root node of the document. + # Note that the root node is different from the document element; + # in this example +a+ is document element and the root node is its parent: + # + # d = Document.new('') + # top_element = d.first # => ... + # child = top_element.first # => ... + # d.root_node == d # => true + # top_element.root_node == d # => true + # child.root_node == d # => true + # + # When the element is not part of a document, but does have ancestor elements, + # returns the most distant ancestor element: + # + # e0 = Element.new('foo') + # e1 = Element.new('bar') + # e1.parent = e0 + # e2 = Element.new('baz') + # e2.parent = e1 + # e2.root_node == e0 # => true + # + # When the element has no ancestor elements, + # returns +self+: + # + # e = Element.new('foo') + # e.root_node == e # => true + # + # Related: #root, #document. + # def root_node parent.nil? ? self : parent.root_node end + # :call-seq: + # root -> element + # + # Returns the most distant _element_ (not document) ancestor of the element: + # + # d = Document.new('') + # top_element = d.first + # child = top_element.first + # top_element.root == top_element # => true + # child.root == top_element # => true + # + # For a document, returns the topmost element: + # + # d.root == top_element # => true + # + # Related: #root_node, #document. + # def root return elements[1] if self.kind_of? Document return self if parent.kind_of? Document or parent.nil? return parent.root end - # Evaluates to the document to which this element belongs, or nil if this - # element doesn't belong to a document. + # :call-seq: + # document -> document or nil + # + # If the element is part of a document, returns that document: + # + # d = Document.new('') + # top_element = d.first + # child = top_element.first + # top_element.document == d # => true + # child.document == d # => true + # + # If the element is not part of a document, returns +nil+: + # + # Element.new.document # => nil + # + # For a document, returns +self+: + # + # d.document == d # => true + # + # Related: #root, #root_node.. + # def document rt = root rt.parent if rt From b278863f7de1a70f1af0a8537214ab3757d2f2b2 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Sat, 30 Jan 2021 06:31:55 +0900 Subject: [PATCH 21/56] Fix indent --- lib/rexml/element.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/rexml/element.rb b/lib/rexml/element.rb index 1f81a4be..d0b72a95 100644 --- a/lib/rexml/element.rb +++ b/lib/rexml/element.rb @@ -288,7 +288,7 @@ def raw @raw = (@context and @context[:raw] and (@context[:raw] == :all or @context[:raw].include? expanded_name)) - @raw + @raw end #once :whitespace, :raw, :ignore_whitespace_nodes From 5b7fb4ad400ffa9756b99858373fd2e905e4a415 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Thu, 4 Feb 2021 16:09:35 -0600 Subject: [PATCH 22/56] doc: add Element::Context (#44) --- .gitignore | 1 - doc/rexml/context.rdoc | 143 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 143 insertions(+), 1 deletion(-) create mode 100644 doc/rexml/context.rdoc diff --git a/.gitignore b/.gitignore index 4ea57987..ff2a440a 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,6 @@ /.yardoc /_yardoc/ /coverage/ -/doc/ /pkg/ /spec/reports/ /tmp/ diff --git a/doc/rexml/context.rdoc b/doc/rexml/context.rdoc new file mode 100644 index 00000000..7ef01f7b --- /dev/null +++ b/doc/rexml/context.rdoc @@ -0,0 +1,143 @@ +== Element Context + +Notes: +- All code on this page presupposes that the following has been executed: + + require 'rexml/document' + +- For convenience, examples on this page use +REXML::Document.new+, not +REXML::Element.new+. + This is completely valid, because REXML::Document is a subclass of REXML::Element. + +The context for an element is a hash of processing directives +that influence the way \XML is read, stored, and written. +The context entries are: + +- +:respect_whitespace+: controls treatment of whitespace. +- +:compress_whitespace+: determines whether whitespace is compressed. +- +:ignore_whitespace_nodes+: determines whether whitespace-only nodes are to be ignored. +- +:raw+: controls treatment of special characters and entities. + +The default context for a new element is {}. +You can set the context at element-creation time: + + d = REXML::Document.new('', {compress_whitespace: :all, raw: :all}) + d.context # => {:compress_whitespace=>:all, :raw=>:all} + +You can reset the entire context by assigning a new hash: + + d.context = {ignore_whitespace_nodes: :all} + d.context # => {:ignore_whitespace_nodes=>:all} + +Or you can create or modify an individual entry: + + d.context[:raw] = :all + d.context # => {:ignore_whitespace_nodes=>:all, :raw=>:all} + +=== +:respect_whitespace+ + +Affects: +REXML::Element.new+, +REXML::Element.text=+. + +By default, all parsed whitespace is respected (that is, stored whitespace not compressed): + + xml_string = 'a b c d e f' + d = REXML::Document.new(xml_string) + d.to_s # => "a b c d e f" + +Use +:respect_whitespace+ with an array of element names +to specify the elements that _are_ to have their whitespace respected; +other elements' whitespace, and whitespace between elements, will be compressed. + +In this example: +foo+ and +baz+ will have their whitespace respected; ++bar+ and the space between elements will have their whitespace compressed: + + d = REXML::Document.new(xml_string, {respect_whitespace: ['foo', 'baz']}) + d.to_s # => "a b c d e f" + bar = d.root[2] # => ... + bar.text = 'X Y' + d.to_s # => "a b X Y e f" + +=== +:compress_whitespace+ + +Affects: +REXML::Element.new+, +REXML::Element.text=+. + +Use compress_whitespace: :all +to compress whitespace both within and between elements: + + xml_string = 'a b c d e f' + d = REXML::Document.new(xml_string, {compress_whitespace: :all}) + d.to_s # => "a b c d e f" + +Use +:compress_whitespace+ with an array of element names +to compress whitespace in those elements, +but not in other elements nor between elements. + +In this example, +foo+ and +baz+ will have their whitespace compressed; ++bar+ and the space between elements will not: + + d = REXML::Document.new(xml_string, {compress_whitespace: ['foo', 'baz']}) + d.to_s # => "a b c d e f" + foo = d.root[0] # => ... + foo.text= 'X Y' + d.to_s # => "X Y c d e f" + +=== +:ignore_whitespace_nodes+ + +Affects: +REXML::Element.new+. + +Use ignore_whitespace_nodes: :all to omit all whitespace-only elements. + +In this example, +bar+ has a text node, while nodes +foo+ and +baz+ do not: + + xml_string = ' BAR ' + d = REXML::Document.new(xml_string, {ignore_whitespace_nodes: :all}) + d.to_s # => " FOO BAZ " + root = d.root # => ... + foo = root[0] # => + bar = root[1] # => ... + baz = root[2] # => + foo.first.class # => NilClass + bar.first.class # => REXML::Text + baz.first.class # => NilClass + +Use +:ignore_whitespace_nodes+ with an array of element names +to specify the elements that are to have whitespace nodes ignored. + +In this example, +bar+ and +baz+ have text nodes, while node +foo+ does not. + + xml_string = ' BAR ' + d = REXML::Document.new(xml_string, {ignore_whitespace_nodes: ['foo']}) + d.to_s # => " BAR " + root = d.root # => ... + foo = root[0] # => + bar = root[1] # => ... + baz = root[2] # => ... + foo.first.class # => NilClass + bar.first.class # => REXML::Text + baz.first.class # => REXML::Text + +=== +:raw+ + +Affects: +Element.text=+, +Element.add_text+, +Text.to_s+. + +Parsing of +a+ elements is not affected by +raw+: + + xml_string = '0 < 11 > 0' + d = REXML::Document.new(xml_string, {:raw => ['a']}) + d.root.to_s # => "0 < 11 > 0" + a, b = *d.root.elements + a.to_s # => "0 < 1" + b.to_s # => "1 > 0" + +But Element#text= is affected: + + a.text = '0 < 1' + b.text = '1 > 0' + a.to_s # => "0 < 1" + b.to_s # => "1 &gt; 0" + +As is Element.add_text: + + a.add_text(' so 1 > 0') + b.add_text(' so 0 < 1') + a.to_s # => "0 < 1 so 1 > 0" + b.to_s # => "1 &gt; 0 so 0 &lt; 1" From d8f8971d92446fb6762bde1c8c18ee06c6012b7f Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Fri, 5 Feb 2021 15:32:34 -0600 Subject: [PATCH 23/56] Enhanced RDoc for Element (#45) --- lib/rexml/element.rb | 76 ++++++++++++++++---------------------------- 1 file changed, 28 insertions(+), 48 deletions(-) diff --git a/lib/rexml/element.rb b/lib/rexml/element.rb index d0b72a95..6fdaf487 100644 --- a/lib/rexml/element.rb +++ b/lib/rexml/element.rb @@ -39,52 +39,32 @@ class Element < Parent # When no arguments are given, # returns an element with name 'UNDEFINED': # - # e = Element.new # => - # e.class # => REXML::Element - # e.name # => "UNDEFINED" + # e = REXML::Element.new # => + # e.class # => REXML::Element + # e.name # => "UNDEFINED" # # When only argument +name+ is given, # returns an element of the given name: # - # Element.new('foo') # => + # REXML::Element.new('foo') # => # - # When only argument +element+ is given, it must be an \Element object; + # When only argument +element+ is given, it must be an \REXML::Element object; # returns a shallow copy of the given element: # - # e0 = Element.new('foo') - # Element.new(e0) # => + # e0 = REXML::Element.new('foo') + # e1 = REXML::Element.new(e0) # => # - # When argument +parent+ is also given, it must be a Parent object: + # When argument +parent+ is also given, it must be an REXML::Parent object: # - # e = Element.new('foo', Parent.new) + # e = REXML::Element.new('foo', REXML::Parent.new) # e.parent # => #]> # # When argument +context+ is also given, it must be a hash - # that may contain the following entries: - # - # :respect_whitespace:: - # +:all+ (default) or an array of names of elements - # whose whitespace is to be respected. - # :compress_whitespace:: - # +:all+ or an array of names of elements - # whose whitespace is to be ignored. - # Overrides :+respect_whitespace+. - # :ignore_whitespace_nodes:: - # +:all+ or an array of names of elements - # to be ignored if whitespace-only; - # "ignored" here means "not added to the document tree." - # :raw:: - # +:all+, or an array names of elements to be processed in raw mode. - # In raw mode, special characters in text are not converted to or from entities. - # - # Example: - # - # context = { - # respect_whitespace: :all, - # raw: :all - # } - # e = Element.new('foo', Parent.new, context) - # e.context # => {:respect_whitespace=>:all, :raw=>:all} + # representing the context for the element; + # see {Element Context}[../doc/rexml/context_rdoc.html]: + # + # e = REXML::Element.new('foo', nil, {raw: :all}) + # e.context # => {:raw=>:all} # def initialize( arg = UNDEFINED, parent=nil, context=nil ) super(parent) @@ -111,18 +91,18 @@ def initialize( arg = UNDEFINED, parent=nil, context=nil ) # # For an element with no attributes and no children, shows the element name: # - # Element.new.inspect # => "" + # REXML::Element.new.inspect # => "" # # Shows attributes, if any: # - # e = Element.new('foo') + # e = REXML::Element.new('foo') # e.add_attributes({'bar' => 0, 'baz' => 1}) # e.inspect # => "" # # Shows an ellipsis (...), if there are child elements: # - # e.add_element(Element.new('bar')) - # e.add_element(Element.new('baz')) + # e.add_element(REXML::Element.new('bar')) + # e.add_element(REXML::Element.new('baz')) # e.inspect # => " ... " # def inspect @@ -146,7 +126,7 @@ def inspect # Returns a shallow copy of the element, containing the name and attributes, # but not the parent or children: # - # e = Element.new('foo') + # e = REXML::Element.new('foo') # e.add_attributes({'bar' => 0, 'baz' => 1}) # e.clone # => # @@ -164,7 +144,7 @@ def clone # Note that the root node is different from the document element; # in this example +a+ is document element and the root node is its parent: # - # d = Document.new('') + # d = REXML::Document.new('') # top_element = d.first # => ... # child = top_element.first # => ... # d.root_node == d # => true @@ -174,17 +154,17 @@ def clone # When the element is not part of a document, but does have ancestor elements, # returns the most distant ancestor element: # - # e0 = Element.new('foo') - # e1 = Element.new('bar') + # e0 = REXML::Element.new('foo') + # e1 = REXML::Element.new('bar') # e1.parent = e0 - # e2 = Element.new('baz') + # e2 = REXML::Element.new('baz') # e2.parent = e1 # e2.root_node == e0 # => true # # When the element has no ancestor elements, # returns +self+: # - # e = Element.new('foo') + # e = REXML::Element.new('foo') # e.root_node == e # => true # # Related: #root, #document. @@ -198,7 +178,7 @@ def root_node # # Returns the most distant _element_ (not document) ancestor of the element: # - # d = Document.new('') + # d = REXML::Document.new('') # top_element = d.first # child = top_element.first # top_element.root == top_element # => true @@ -221,7 +201,7 @@ def root # # If the element is part of a document, returns that document: # - # d = Document.new('') + # d = REXML::Document.new('') # top_element = d.first # child = top_element.first # top_element.document == d # => true @@ -229,13 +209,13 @@ def root # # If the element is not part of a document, returns +nil+: # - # Element.new.document # => nil + # REXML::Element.new.document # => nil # # For a document, returns +self+: # # d.document == d # => true # - # Related: #root, #root_node.. + # Related: #root, #root_node. # def document rt = root From 76b6e3f9e64ac123a523949635bcfd1573ada48f Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Sun, 7 Feb 2021 07:05:32 +0900 Subject: [PATCH 24/56] Add support for generating RDoc HTML --- .github/workflows/test.yml | 45 +++++++++++++++++++++- .gitignore | 1 + Rakefile | 20 ++++++++++ rexml.gemspec | 77 +++++++++++++------------------------- 4 files changed, 89 insertions(+), 54 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 7654e9e9..819f46c0 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -4,7 +4,7 @@ on: - pull_request jobs: inplace: - name: ${{ matrix.ruby-version }} on ${{ matrix.runs-on }} + name: "Inplace: ${{ matrix.ruby-version }} on ${{ matrix.runs-on }}" runs-on: ${{ matrix.runs-on }} strategy: fail-fast: false @@ -31,7 +31,7 @@ jobs: run: bundle exec rake test gem: - name: ${{ matrix.ruby-version }} on ${{ matrix.runs-on }} + name: "Gem: ${{ matrix.ruby-version }} on ${{ matrix.runs-on }}" runs-on: ${{ matrix.runs-on }} strategy: fail-fast: false @@ -57,3 +57,44 @@ jobs: ruby -run -e cp -- -p -r test tmp cd tmp ruby test/run.rb + + document: + name: "Document" + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby-version }} + - name: Install dependencies + run: | + bundle install + - name: Build document + run: | + bundle exec rake warning:error rdoc + - uses: actions/checkout@v2 + if: | + github.event_name == 'push' + with: + ref: gh-pages + path: gh-pages + - name: Deploy + if: | + github.event_name == 'push' + run: | + rm html/created.rid + touch html/.nojekyll + cd gh-pages + rsync \ + -a \ + --delete \ + --exclude "/.git/" \ + ../html/ \ + ./ + if [ "$(git status --porcelain)" != "" ]; then + git add --all + git config user.name github-actions + git config user.email github-actions@github.com + git commit -m "Generate (${GITHUB_SHA})" + git push + fi diff --git a/.gitignore b/.gitignore index ff2a440a..aeae5f29 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ /.yardoc /_yardoc/ /coverage/ +/html/ /pkg/ /spec/reports/ /tmp/ diff --git a/Rakefile b/Rakefile index 7d9c3cce..e0485b20 100644 --- a/Rakefile +++ b/Rakefile @@ -1,8 +1,28 @@ +require "rdoc/task" + require "bundler/gem_tasks" +spec = Bundler::GemHelper.gemspec + desc "Run test" task :test do ruby("test/run.rb") end task :default => :test + +namespace :warning do + desc "Treat warning as error" + task :error do + def Warning.warn(*message) + super + raise "Treat warning as error:\n" + message.join("\n") + end + end +end + +RDoc::Task.new do |rdoc| + rdoc.options = spec.rdoc_options + rdoc.rdoc_files.include(*spec.source_paths) + rdoc.rdoc_files.include(*spec.extra_rdoc_files) +end diff --git a/rexml.gemspec b/rexml.gemspec index b3db38b4..660dca27 100644 --- a/rexml.gemspec +++ b/rexml.gemspec @@ -16,64 +16,37 @@ Gem::Specification.new do |spec| spec.homepage = "https://github.com/ruby/rexml" spec.license = "BSD-2-Clause" - spec.files = [ + files = [ "LICENSE.txt", "NEWS.md", "README.md", - "lib/rexml.rb", - "lib/rexml/attlistdecl.rb", - "lib/rexml/attribute.rb", - "lib/rexml/cdata.rb", - "lib/rexml/child.rb", - "lib/rexml/comment.rb", - "lib/rexml/doctype.rb", - "lib/rexml/document.rb", - "lib/rexml/dtd/attlistdecl.rb", - "lib/rexml/dtd/dtd.rb", - "lib/rexml/dtd/elementdecl.rb", - "lib/rexml/dtd/entitydecl.rb", - "lib/rexml/dtd/notationdecl.rb", - "lib/rexml/element.rb", - "lib/rexml/encoding.rb", - "lib/rexml/entity.rb", - "lib/rexml/formatters/default.rb", - "lib/rexml/formatters/pretty.rb", - "lib/rexml/formatters/transitive.rb", - "lib/rexml/functions.rb", - "lib/rexml/instruction.rb", - "lib/rexml/light/node.rb", - "lib/rexml/namespace.rb", - "lib/rexml/node.rb", - "lib/rexml/output.rb", - "lib/rexml/parent.rb", - "lib/rexml/parseexception.rb", - "lib/rexml/parsers/baseparser.rb", - "lib/rexml/parsers/lightparser.rb", - "lib/rexml/parsers/pullparser.rb", - "lib/rexml/parsers/sax2parser.rb", - "lib/rexml/parsers/streamparser.rb", - "lib/rexml/parsers/treeparser.rb", - "lib/rexml/parsers/ultralightparser.rb", - "lib/rexml/parsers/xpathparser.rb", - "lib/rexml/quickpath.rb", - "lib/rexml/rexml.rb", - "lib/rexml/sax2listener.rb", - "lib/rexml/security.rb", - "lib/rexml/source.rb", - "lib/rexml/streamlistener.rb", - "lib/rexml/text.rb", - "lib/rexml/undefinednamespaceexception.rb", - "lib/rexml/validation/relaxng.rb", - "lib/rexml/validation/validation.rb", - "lib/rexml/validation/validationexception.rb", - "lib/rexml/xmldecl.rb", - "lib/rexml/xmltokens.rb", - "lib/rexml/xpath.rb", - "lib/rexml/xpath_parser.rb", ] + rdoc_files = files.dup + lib_path = "lib" + spec.require_paths = [lib_path] + lib_dir = File.join(__dir__, lib_path) + if File.exist?(lib_dir) + Dir.chdir(lib_dir) do + Dir.glob("**/*.rb").each do |file| + files << "lib/#{file}" + end + end + end + doc_path = "doc" + doc_dir = File.join(__dir__, doc_path) + if File.exist?(doc_dir) + Dir.chdir(doc_dir) do + Dir.glob("**/*.rdoc").each do |rdoc_file| + files << "#{doc_path}/#{rdoc_file}" + rdoc_files << "#{doc_path}/#{rdoc_file}" + end + end + end + spec.files = files + spec.rdoc_options.concat(["--main", "README.md"]) + spec.extra_rdoc_files = rdoc_files spec.bindir = "exe" spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) } - spec.require_paths = ["lib"] spec.add_development_dependency "bundler" spec.add_development_dependency "rake" From 3b3bbeb9417c6e7056551e3e552408f9b1f34071 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sat, 6 Feb 2021 16:07:12 -0600 Subject: [PATCH 25/56] Enhanced RDoc for Element (#46) --- lib/rexml/element.rb | 35 +++++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 12 deletions(-) diff --git a/lib/rexml/element.rb b/lib/rexml/element.rb index 6fdaf487..6b08274f 100644 --- a/lib/rexml/element.rb +++ b/lib/rexml/element.rb @@ -222,15 +222,16 @@ def document rt.parent if rt end - # Evaluates to +true+ if whitespace is respected for this element. This - # is the case if: - # 1. Neither :+respect_whitespace+ nor :+compress_whitespace+ has any value - # 2. The context has :+respect_whitespace+ set to :+all+ or - # an array containing the name of this element, and - # :+compress_whitespace+ isn't set to :+all+ or an array containing the - # name of this element. - # The evaluation is tested against +expanded_name+, and so is namespace - # sensitive. + # :call-seq: + # whitespace + # + # Returns +true+ if whitespace is respected for this element, + # +false+ otherwise. + # + # See {Element Context}[../doc/rexml/context_rdoc.html]. + # + # The evaluation is tested against the element's +expanded_name+, + # and so is namespace-sensitive. def whitespace @whitespace = nil if @context @@ -247,6 +248,13 @@ def whitespace @whitespace end + # :call-seq: + # ignore_whitespace_nodes + # + # Returns +true+ if whitespace nodes are ignored for the element. + # + # See {Element Context}[../doc/rexml/context_rdoc.html]. + # def ignore_whitespace_nodes @ignore_whitespace_nodes = false if @context @@ -258,9 +266,12 @@ def ignore_whitespace_nodes end end - # Evaluates to +true+ if raw mode is set for this element. This - # is the case if the context has :+raw+ set to :+all+ or - # an array containing the name of this element. + # :call-seq: + # raw + # + # Returns +true+ if raw mode is set for the element. + # + # See {Element Context}[../doc/rexml/context_rdoc.html]. # # The evaluation is tested against +expanded_name+, and so is namespace # sensitive. From 9f244352f2abc8d4f91a998c236ee8480655878f Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Sun, 7 Feb 2021 07:09:07 +0900 Subject: [PATCH 26/56] ci: remove garbage --- .github/workflows/test.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 819f46c0..2c8057c4 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -64,8 +64,6 @@ jobs: steps: - uses: actions/checkout@v2 - uses: ruby/setup-ruby@v1 - with: - ruby-version: ${{ matrix.ruby-version }} - name: Install dependencies run: | bundle install From 14c32303ce6e5f60ada16028583e701b1b4168b1 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Sun, 7 Feb 2021 07:10:51 +0900 Subject: [PATCH 27/56] ci: use actions/setup-ruby to use the default Ruby --- .github/workflows/test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 2c8057c4..1563ed08 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -63,7 +63,7 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - - uses: ruby/setup-ruby@v1 + - uses: actions/setup-ruby@v1 - name: Install dependencies run: | bundle install From 2d5055806279171bcb4cdc0af732ce2829c2aee7 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sun, 7 Feb 2021 14:32:10 -0600 Subject: [PATCH 28/56] Enhanced RDoc for Document (#47) --- lib/rexml/document.rb | 134 +++++++++++++++++++++++++++++++++++------- 1 file changed, 113 insertions(+), 21 deletions(-) diff --git a/lib/rexml/document.rb b/lib/rexml/document.rb index adec2930..7ceb1baa 100644 --- a/lib/rexml/document.rb +++ b/lib/rexml/document.rb @@ -14,25 +14,72 @@ require_relative "parsers/treeparser" module REXML - # Represents a full XML document, including PIs, a doctype, etc. A - # Document has a single child that can be accessed by root(). - # Note that if you want to have an XML declaration written for a document - # you create, you must add one; REXML documents do not write a default - # declaration for you. See |DECLARATION| and |write|. + # Represents an XML document. + # + # A document may have: + # + # - A single child that may be accessed via method #root. + # - An XML declaration. + # - A document type. + # - Processing instructions. + # class Document < Element - # A convenient default XML declaration. If you want an XML declaration, - # the easiest way to add one is mydoc << Document::DECLARATION - # +DEPRECATED+ - # Use: mydoc << XMLDecl.default + # A convenient default XML declaration. Use: + # + # mydoc << XMLDecl.default + # DECLARATION = XMLDecl.default - # Constructor - # @param source if supplied, must be a Document, String, or IO. - # Documents have their context and Element attributes cloned. - # Strings are expected to be valid XML documents. IOs are expected - # to be sources of valid XML documents. - # @param context if supplied, contains the context of the document; - # this should be a Hash. + # :call-seq: + # new(string = nil, context = {}) -> new_document + # new(io_stream = nil, context = {}) -> new_document + # new(document = nil, context = {}) -> new_document + # + # Returns a new \REXML::Document object. + # + # When no arguments are given, + # returns an empty document: + # + # d = REXML::Document.new + # d.to_s # => "" + # + # When argument +string+ is given, it must be a string + # containing a valid XML document: + # + # xml_string = 'FooBar' + # d = REXML::Document.new(xml_string) + # d.to_s # => "FooBar" + # + # When argument +io_stream+ is given, it must be an \IO object + # that is opened for reading, and when read must return a valid XML document: + # + # File.write('t.xml', xml_string) + # d = File.open('t.xml', 'r') do |io| + # REXML::Document.new(io) + # end + # d.to_s # => "FooBar" + # + # When argument +document+ is given, it must be an existing + # document object, whose context and attributes (but not chidren) + # are cloned into the new document: + # + # d = REXML::Document.new(xml_string) + # d.children # => [ ... ] + # d.context = {raw: :all, compress_whitespace: :all} + # d.add_attributes({'bar' => 0, 'baz' => 1}) + # d1 = REXML::Document.new(d) + # d1.children # => [] + # d1.context # => {:raw=>:all, :compress_whitespace=>:all} + # d1.attributes # => {"bar"=>bar='0', "baz"=>baz='1'} + # + # When argument +context+ is given, it must be a hash + # containing context entries for the document; + # see {Element Context}[../doc/rexml/context_rdoc.html]: + # + # context = {raw: :all, compress_whitespace: :all} + # d = REXML::Document.new(xml_string, context) + # d.context # => {:raw=>:all, :compress_whitespace=>:all} + # def initialize( source = nil, context = {} ) @entity_expansion_count = 0 super() @@ -46,26 +93,71 @@ def initialize( source = nil, context = {} ) end end + # :call-seq: + # node_type -> :document + # + # Returns the symbol +:document+. + # def node_type :document end - # Should be obvious + # :call-seq: + # clone -> new_document + # + # Returns the new document resulting from executing + # Document.new(self). See Document.new. + # def clone Document.new self end - # According to the XML spec, a root node has no expanded name + # :call-seq: + # expanded_name -> empty_string + # + # Returns an empty string. + # def expanded_name '' #d = doc_type #d ? d.name : "UNDEFINED" end - alias :name :expanded_name - # We override this, because XMLDecls and DocTypes must go at the start - # of the document + # :call-seq: + # add(xml_decl) -> self + # add(doc_type) -> self + # add(object) -> self + # + # Adds an object to the document; returns +self+. + # + # When argument +xml_decl+ is given, + # it must be an REXML::XMLDecl object, + # which becomes the XML declaration for the document, + # replacing the previous XML declaration if any: + # + # d = REXML::Document.new + # d.xml_decl.to_s # => "" + # d.add(REXML::XMLDecl.new('2.0')) + # d.xml_decl.to_s # => "" + # + # When argument +doc_type+ is given, + # it must be an REXML::DocType object, + # which becomes the document type for the document, + # replacing the previous document type, if any: + # + # d = REXML::Document.new + # d.doctype.to_s # => "" + # d.add(REXML::DocType.new('foo')) + # d.doctype.to_s # => "" + # + # When argument +object+ (not an REXML::XMLDecl or REXML::DocType object) + # is given it is added as the last child: + # + # d = REXML::Document.new + # d.add(REXML::Element.new('foo')) + # d.to_s # => "" + # def add( child ) if child.kind_of? XMLDecl if @children[0].kind_of? XMLDecl From 7fcc72bc4e6a06c865ff464c9e40413e09f545a8 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sun, 7 Feb 2021 18:43:29 -0600 Subject: [PATCH 29/56] Enhanced RDoc for Element (#48) --- lib/rexml/element.rb | 136 ++++++++++++++++++++++++++++++------------- 1 file changed, 97 insertions(+), 39 deletions(-) diff --git a/lib/rexml/element.rb b/lib/rexml/element.rb index 6b08274f..5e81f97e 100644 --- a/lib/rexml/element.rb +++ b/lib/rexml/element.rb @@ -288,10 +288,25 @@ def raw # Namespaces # ################################################# - # Evaluates to an +Array+ containing the prefixes (names) of all defined - # namespaces at this context node. - # doc = Document.new("") - # doc.elements['//b'].prefixes # -> ['x', 'y'] + # :call-seq: + # prefixes -> array_of_namespace_prefixes + # + # Returns an array of the string prefixes (names) of all defined namespaces + # in the element and its ancestors: + # + # xml_string = <<-EOT + # + # + # + # + # + # + # EOT + # d = REXML::Document.new(xml_string, {compress_whitespace: :all}) + # d.elements['//a'].prefixes # => ["x", "y"] + # d.elements['//b'].prefixes # => ["x", "y"] + # d.elements['//c'].prefixes # => ["x", "y", "z"] + # def prefixes prefixes = [] prefixes = parent.prefixes if parent @@ -299,6 +314,25 @@ def prefixes return prefixes end + # :call-seq: + # namespaces -> array_of_namespace_names + # + # Returns a hash of all defined namespaces + # in the element and its ancestors: + # + # xml_string = <<-EOT + # + # + # + # + # + # + # EOT + # d = REXML::Document.new(xml_string) + # d.elements['//a'].namespaces # => {"x"=>"1", "y"=>"2"} + # d.elements['//b'].namespaces # => {"x"=>"1", "y"=>"2"} + # d.elements['//c'].namespaces # => {"x"=>"1", "y"=>"2", "z"=>"3"} + # def namespaces namespaces = {} namespaces = parent.namespaces if parent @@ -306,19 +340,26 @@ def namespaces return namespaces end - # Evaluates to the URI for a prefix, or the empty string if no such - # namespace is declared for this element. Evaluates recursively for - # ancestors. Returns the default namespace, if there is one. - # prefix:: - # the prefix to search for. If not supplied, returns the default - # namespace if one exists - # Returns:: - # the namespace URI as a String, or nil if no such namespace - # exists. If the namespace is undefined, returns an empty string - # doc = Document.new("") - # b = doc.elements['//b'] - # b.namespace # -> '1' - # b.namespace("y") # -> '2' + # :call-seq: + # namespace(prefix = nil) -> string_uri or nil + # + # Returns the string namespace URI for the element, + # possibly deriving from one of its ancestors. + # + # xml_string = <<-EOT + # + # + # + # + # + # + # EOT + # d = REXML::Document.new(xml_string) + # b = d.elements['//b'] + # b.namespace # => "1" + # b.namespace('y') # => "2" + # b.namespace('nosuch') # => nil + # def namespace(prefix=nil) if prefix.nil? prefix = prefix() @@ -334,19 +375,24 @@ def namespace(prefix=nil) return ns end - # Adds a namespace to this element. - # prefix:: - # the prefix string, or the namespace URI if +uri+ is not - # supplied - # uri:: - # the namespace URI. May be nil, in which +prefix+ is used as - # the URI - # Evaluates to: this Element - # a = Element.new("a") - # a.add_namespace("xmlns:foo", "bar" ) - # a.add_namespace("foo", "bar") # shorthand for previous line - # a.add_namespace("twiddle") - # puts a #-> + # :call-seq: + # add_namespace(prefix, uri = nil) -> self + # + # Adds a namespace to the element; returns +self+. + # + # With the single argument +prefix+, + # adds a namespace using the given +prefix+ and the namespace URI: + # + # e = REXML::Element.new('foo') + # e.add_namespace('bar') + # e.namespaces # => {"xmlns"=>"bar"} + # + # With both arguments +prefix+ and +uri+ given, + # adds a namespace using both arguments: + # + # e.add_namespace('baz', 'bat') + # e.namespaces # => {"xmlns"=>"bar", "baz"=>"bat"} + # def add_namespace( prefix, uri=nil ) unless uri @attributes["xmlns"] = prefix @@ -357,16 +403,28 @@ def add_namespace( prefix, uri=nil ) self end - # Removes a namespace from this node. This only works if the namespace is - # actually declared in this node. If no argument is passed, deletes the - # default namespace. + # :call-seq: + # delete_namespace(namespace = 'xmlns') -> self + # + # Removes a namespace from the element. + # + # With no argument, removes the default namespace: + # + # d = REXML::Document.new "" + # d.to_s # => "" + # d.root.delete_namespace # => + # d.to_s # => "" + # + # With argument +namespace+, removes the specified namespace: + # + # d.root.delete_namespace('foo') + # d.to_s # => "" + # + # Does nothing if no such namespace is found: + # + # d.root.delete_namespace('nosuch') + # d.to_s # => "" # - # Evaluates to: this element - # doc = Document.new "" - # doc.root.delete_namespace - # puts doc # -> - # doc.root.delete_namespace 'foo' - # puts doc # -> def delete_namespace namespace="xmlns" namespace = "xmlns:#{namespace}" unless namespace == 'xmlns' attribute = attributes.get_attribute(namespace) From 1c413184c728affa067d5992daed208723477981 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sun, 7 Feb 2021 18:44:39 -0600 Subject: [PATCH 30/56] Enhanced RDoc for Document (#49) --- lib/rexml/document.rb | 85 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 72 insertions(+), 13 deletions(-) diff --git a/lib/rexml/document.rb b/lib/rexml/document.rb index 7ceb1baa..b8db6ef3 100644 --- a/lib/rexml/document.rb +++ b/lib/rexml/document.rb @@ -191,49 +191,108 @@ def add( child ) end alias :<< :add + # :call-seq: + # add_element(name_or_element = nil, attributes = nil) -> new_element + # + # Adds an element to the document by calling REXML::Element.add_element: + # + # REXML::Element.add_element(name_or_element, attributes) def add_element(arg=nil, arg2=nil) rv = super raise "attempted adding second root element to document" if @elements.size > 1 rv end - # @return the root Element of the document, or nil if this document - # has no children. + # :call-seq: + # root -> root_element or nil + # + # Returns the root element of the document, if it exists, otherwise +nil+: + # + # d = REXML::Document.new('') + # d.root # => + # d = REXML::Document.new('') + # d.root # => nil + # def root elements[1] #self #@children.find { |item| item.kind_of? Element } end - # @return the DocType child of the document, if one exists, - # and nil otherwise. + # :call-seq: + # doctype -> doc_type or nil + # + # Returns the DocType object for the document, if it exists, otherwise +nil+: + # + # d = REXML::Document.new('') + # d.doctype.class # => REXML::DocType + # d = REXML::Document.new('') + # d.doctype.class # => nil + # def doctype @children.find { |item| item.kind_of? DocType } end - # @return the XMLDecl of this document; if no XMLDecl has been - # set, the default declaration is returned. + # :call-seq: + # xml_decl -> xml_decl + # + # Returns the XMLDecl object for the document, if it exists, + # otherwise the default XMLDecl object: + # + # d = REXML::Document.new('') + # d.xml_decl.class # => REXML::XMLDecl + # d.xml_decl.to_s # => "" + # d = REXML::Document.new('') + # d.xml_decl.class # => REXML::XMLDecl + # d.xml_decl.to_s # => "" + # def xml_decl rv = @children[0] return rv if rv.kind_of? XMLDecl @children.unshift(XMLDecl.default)[0] end - # @return the XMLDecl version of this document as a String. - # If no XMLDecl has been set, returns the default version. + # :call-seq: + # version -> version_string + # + # Returns the XMLDecl version of this document as a string, + # if it has been set, otherwise the default version: + # + # d = REXML::Document.new('') + # d.version # => "2.0" + # d = REXML::Document.new('') + # d.version # => "1.0" + # def version xml_decl().version end - # @return the XMLDecl encoding of this document as an - # Encoding object. - # If no XMLDecl has been set, returns the default encoding. + # :call-seq: + # encoding -> encoding_string + # + # Returns the XMLDecl encoding of the document, + # if it has been set, otherwise the default encoding: + # + # d = REXML::Document.new('') + # d.encoding # => "UTF-16" + # d = REXML::Document.new('') + # d.encoding # => "UTF-8" + # def encoding xml_decl().encoding end - # @return the XMLDecl standalone value of this document as a String. - # If no XMLDecl has been set, returns the default setting. + # :call-seq: + # stand_alone? + # + # Returns the XMLDecl standalone value of the document as a string, + # if it has been set, otherwise the default standalone value: + # + # d = REXML::Document.new('') + # d.stand_alone? # => "yes" + # d = REXML::Document.new('') + # d.stand_alone? # => nil + # def stand_alone? xml_decl().stand_alone? end From 71ad86950de431bb60e6499b5ab271b1f39689e3 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Mon, 8 Feb 2021 19:56:23 -0600 Subject: [PATCH 31/56] Enhanced RDoc for Elements (#50) --- lib/rexml/element.rb | 280 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 223 insertions(+), 57 deletions(-) diff --git a/lib/rexml/element.rb b/lib/rexml/element.rb index 5e81f97e..67f89134 100644 --- a/lib/rexml/element.rb +++ b/lib/rexml/element.rb @@ -915,35 +915,118 @@ def each_with_something( test, max=0, name=nil ) # XPath search support. You are expected to only encounter this class as # the element.elements object. Therefore, you are # _not_ expected to instantiate this yourself. + # + # xml_string = <<-EOT + # + # + # + # Everyday Italian + # Giada De Laurentiis + # 2005 + # 30.00 + # + # + # Harry Potter + # J K. Rowling + # 2005 + # 29.99 + # + # + # XQuery Kick Start + # James McGovern + # Per Bothner + # Kurt Cagle + # James Linn + # Vaidyanathan Nagarajan + # 2003 + # 49.99 + # + # + # Learning XML + # Erik T. Ray + # 2003 + # 39.95 + # + # + # EOT + # d = REXML::Document.new(xml_string) + # elements = d.root.elements + # elements # => # ... > + # class Elements include Enumerable - # Constructor - # parent:: the parent Element + # :call-seq: + # new(base_element) -> new_elements_object + # + # Returns a new \Elements object with the given +base_element+. + # Does _not_ assign base_element.elements = self: + # + # d = REXML::Document.new(xml_string) + # eles = REXML::Elements.new(d.root) + # eles # => # ... > + # eles == d.root.elements # => false + # + # To retrieve the given +base_element+: + # + # eles['.'] # => ... + # def initialize parent @element = parent end - # Fetches a child element. Filters only Element children, regardless of - # the XPath match. - # index:: - # the search parameter. This is either an Integer, which - # will be used to find the index'th child Element, or an XPath, - # which will be used to search for the Element. Because - # of the nature of XPath searches, any element in the connected XML - # document can be fetched through any other element. The - # Integer index is 1-based, not 0-based. This means that the first - # child element is at index 1, not 0, and the +n+th element is at index - # +n+, not n-1. This is because XPath indexes element children - # starting from 1, not 0, and the indexes should be the same. - # name:: - # optional, and only used in the first argument is an - # Integer. In that case, the index'th child Element that has the - # supplied name will be returned. Note again that the indexes start at 1. - # Returns:: the first matching Element, or nil if no child matched - # doc = Document.new '' - # doc.root.elements[1] #-> - # doc.root.elements['c'] #-> - # doc.root.elements[2,'c'] #-> + # :call-seq: + # elements[index] -> element or nil + # elements[xpath] -> element or nil + # elements[n, name] -> element or nil + # + # Returns the first \Element object selected by the arguments, + # if any found, or +nil+ if none found. + # + # Notes: + # - The +index+ is 1-based, not 0-based, so that: + # - The first element has index 1 + # - The _nth_ element has index +n+. + # - The selection ignores non-\Element nodes. + # + # When the single argument +index+ is given, + # returns the element given by the index, if any; otherwise, +nil+: + # + # d = REXML::Document.new(xml_string) + # eles = d.root.elements + # eles # => # ... > + # eles[1] # => ... + # eles.size # => 4 + # eles[4] # => ... + # eles[5] # => nil + # + # The node at this index is not an \Element, and so is not returned: + # + # eles = d.root.first.first # => ... </> + # eles.to_a # => ["Everyday Italian"] + # eles[1] # => nil + # + # When the single argument +xpath+ is given, + # returns the first element found via that +xpath+, if any; otherwise, +nil+: + # + # eles = d.root.elements # => #<REXML::Elements @element=<bookstore> ... </>> + # eles['/bookstore'] # => <bookstore> ... </> + # eles['//book'] # => <book category='cooking'> ... </> + # eles['//book [@category="children"]'] # => <book category='children'> ... </> + # eles['/nosuch'] # => nil + # eles['//nosuch'] # => nil + # eles['//book [@category="nosuch"]'] # => nil + # eles['.'] # => <bookstore> ... </> + # eles['..'].class # => REXML::Document + # + # With arguments +n+ and +name+ given, + # returns the _nth_ found element that has the given +name+, + # or +nil+ if there is no such _nth_ element: + # + # eles = d.root.elements # => #<REXML::Elements @element=<bookstore> ... </>> + # eles[1, 'book'] # => <book category='cooking'> ... </> + # eles[4, 'book'] # => <book category='web' cover='paperback'> ... </> + # eles[5, 'book'] # => nil + # def []( index, name=nil) if index.kind_of? Integer raise "index (#{index}) must be >= 1" if index < 1 @@ -963,19 +1046,42 @@ def []( index, name=nil) end end - # Sets an element, replacing any previous matching element. If no - # existing element is found ,the element is added. - # index:: Used to find a matching element to replace. See [](). - # element:: - # The element to replace the existing element with - # the previous element - # Returns:: nil if no previous element was found. - # - # doc = Document.new '<a/>' - # doc.root.elements[10] = Element.new('b') #-> <a><b/></a> - # doc.root.elements[1] #-> <b/> - # doc.root.elements[1] = Element.new('c') #-> <a><c/></a> - # doc.root.elements['c'] = Element.new('d') #-> <a><d/></a> + # :call-seq: + # elements[] = index, replacement_element -> replacement_element or nil + # + # Replaces or adds an element. + # + # When <tt>eles[index]</tt> exists, replaces it with +replacement_element+ + # and returns +replacement_element+: + # + # d = REXML::Document.new(xml_string) + # eles = d.root.elements # => #<REXML::Elements @element=<bookstore> ... </>> + # eles[1] # => <book category='cooking'> ... </> + # eles[1] = REXML::Element.new('foo') + # eles[1] # => <foo/> + # + # Does nothing (or raises an exception) + # if +replacement_element+ is not an \Element: + # eles[2] # => <book category='web' cover='paperback'> ... </> + # eles[2] = REXML::Text.new('bar') + # eles[2] # => <book category='web' cover='paperback'> ... </> + # + # When <tt>eles[index]</tt> does not exist, + # adds +replacement_element+ to the element and returns + # + # d = REXML::Document.new(xml_string) + # eles = d.root.elements # => #<REXML::Elements @element=<bookstore> ... </>> + # eles.size # => 4 + # eles[50] = REXML::Element.new('foo') # => <foo/> + # eles.size # => 5 + # eles[5] # => <foo/> + # + # Does nothing (or raises an exception) + # if +replacement_element+ is not an \Element: + # + # eles[50] = REXML::Text.new('bar') # => "bar" + # eles.size # => 5 + # def []=( index, element ) previous = self[index] if previous.nil? @@ -986,14 +1092,34 @@ def []=( index, element ) return previous end - # Returns +true+ if there are no +Element+ children, +false+ otherwise + # :call-seq: + # empty? -> true or false + # + # Returns +true+ if there are no children, +false+ otherwise. + # + # d = REXML::Document.new('') + # d.elements.empty? # => true + # d = REXML::Document.new(xml_string) + # d.elements.empty? # => false + # def empty? @element.find{ |child| child.kind_of? Element}.nil? end - # Returns the index of the supplied child (starting at 1), or -1 if - # the element is not a child - # element:: an +Element+ child + # :call-seq: + # index(element) + # + # Returns the 1-based index of the given +element+, if found; + # otherwise, returns -1: + # + # d = REXML::Document.new(xml_string) + # elements = d.root.elements + # ele_1, ele_2, ele_3, ele_4 = *elements + # elements.index(ele_4) # => 4 + # elements.delete(ele_3) + # elements.index(ele_4) # => 3 + # elements.index(ele_3) # => -1 + # def index element rv = 0 found = @element.find do |child| @@ -1005,17 +1131,47 @@ def index element return -1 end - # Deletes a child Element - # element:: - # Either an Element, which is removed directly; an - # xpath, where the first matching child is removed; or an Integer, - # where the n'th Element is removed. - # Returns:: the removed child - # doc = Document.new '<a><b/><c/><c id="1"/></a>' - # b = doc.root.elements[1] - # doc.root.elements.delete b #-> <a><c/><c id="1"/></a> - # doc.elements.delete("a/c[@id='1']") #-> <a><c/></a> - # doc.root.elements.delete 1 #-> <a/> + # :call-seq: + # delete(index) -> removed_element or nil + # delete(element) -> removed_element or nil + # delete(xpath) -> removed_element or nil + # + # Removes an element; returns the removed element, or +nil+ if none removed. + # + # With integer argument +index+ given, + # removes the child element at that offset: + # + # d = REXML::Document.new(xml_string) + # elements = d.root.elements + # elements.size # => 4 + # elements[2] # => <book category='children'> ... </> + # elements.delete(2) # => <book category='children'> ... </> + # elements.size # => 3 + # elements[2] # => <book category='web'> ... </> + # elements.delete(50) # => nil + # + # With element argument +element+ given, + # removes that child element: + # + # d = REXML::Document.new(xml_string) + # elements = d.root.elements + # ele_1, ele_2, ele_3, ele_4 = *elements + # elements.size # => 4 + # elements[2] # => <book category='children'> ... </> + # elements.delete(ele_2) # => <book category='children'> ... </> + # elements.size # => 3 + # elements[2] # => <book category='web'> ... </> + # elements.delete(ele_2) # => nil + # + # With string argument +xpath+ given, + # removes the first element found via that xpath: + # + # d = REXML::Document.new(xml_string) + # elements = d.root.elements + # elements.delete('//book') # => <book category='cooking'> ... </> + # elements.delete('//book [@category="children"]') # => <book category='children'> ... </> + # elements.delete('//nosuch') # => nil + # def delete element if element.kind_of? Element @element.delete element @@ -1025,12 +1181,22 @@ def delete element end end - # Removes multiple elements. Filters for Element children, regardless of - # XPath matching. - # xpath:: all elements matching this String path are removed. - # Returns:: an Array of Elements that have been removed - # doc = Document.new '<a><c/><c/><c/><c/></a>' - # deleted = doc.elements.delete_all 'a/c' #-> [<c/>, <c/>, <c/>, <c/>] + # :call-seq: + # delete_all(xpath) + # + # Removes all elements found via the given +xpath+; + # returns the array of removed elements, if any, else +nil+. + # + # d = REXML::Document.new(xml_string) + # elements = d.root.elements + # elements.size # => 4 + # deleted_elements = elements.delete_all('//book [@category="children"]') + # deleted_elements # => [<book category='children'> ... </>] + # deleted_elements = elements.delete_all('//book') + # deleted_elements.size # => 3 + # elements.size # => 0 + # elements.delete_all('//book') # => [] + # def delete_all( xpath ) rv = [] XPath::each( @element, xpath) {|element| From 3ed5d3988b0607873b8051e72a71862d0375dbf9 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Yahoo.com> Date: Wed, 10 Feb 2021 15:01:47 -0600 Subject: [PATCH 32/56] Adding method Elements#parent (#52) --- lib/rexml/element.rb | 25 ++++++++++++++++++------- test/test_elements.rb | 5 +++++ 2 files changed, 23 insertions(+), 7 deletions(-) diff --git a/lib/rexml/element.rb b/lib/rexml/element.rb index 67f89134..67249c27 100644 --- a/lib/rexml/element.rb +++ b/lib/rexml/element.rb @@ -956,24 +956,35 @@ def each_with_something( test, max=0, name=nil ) class Elements include Enumerable # :call-seq: - # new(base_element) -> new_elements_object + # new(parent) -> new_elements_object # - # Returns a new \Elements object with the given +base_element+. - # Does _not_ assign <tt>base_element.elements = self</tt>: + # Returns a new \Elements object with the given +parent+. + # Does _not_ assign <tt>parent.elements = self</tt>: # # d = REXML::Document.new(xml_string) # eles = REXML::Elements.new(d.root) # eles # => #<REXML::Elements @element=<bookstore> ... </>> # eles == d.root.elements # => false # - # To retrieve the given +base_element+: - # - # eles['.'] # => <bookstore> ... </> - # def initialize parent @element = parent end + # :call-seq: + # parent + # + # Returns the parent element cited in creating the \Elements object. + # This element is also the default starting point for searching + # in the \Elements object. + # + # d = REXML::Document.new(xml_string) + # elements = REXML::Elements.new(d.root) + # elements.parent == d.root # => true + # + def parent + @element + end + # :call-seq: # elements[index] -> element or nil # elements[xpath] -> element or nil diff --git a/test/test_elements.rb b/test/test_elements.rb index 33e83e12..c0f1b220 100644 --- a/test/test_elements.rb +++ b/test/test_elements.rb @@ -113,5 +113,10 @@ def test_inject } assert_equal 6, r end + + def test_parent + doc = Document.new( "<a><b id='1'/><b id='2'/></a>" ) + assert_equal('a', doc.root.elements.parent.name) + end end end From e92db831dd43ee3208d96a94ad02a2bf83eff233 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Yahoo.com> Date: Thu, 11 Feb 2021 15:25:46 -0600 Subject: [PATCH 33/56] Enhanced RDoc for Elements (#53) --- lib/rexml/element.rb | 252 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 215 insertions(+), 37 deletions(-) diff --git a/lib/rexml/element.rb b/lib/rexml/element.rb index 67249c27..0fe950e8 100644 --- a/lib/rexml/element.rb +++ b/lib/rexml/element.rb @@ -1201,10 +1201,11 @@ def delete element # d = REXML::Document.new(xml_string) # elements = d.root.elements # elements.size # => 4 - # deleted_elements = elements.delete_all('//book [@category="children"]') - # deleted_elements # => [<book category='children'> ... </>] + # deleted_elements = elements.delete_all('//book [@category="web"]') + # deleted_elements.size # => 2 + # elements.size # => 2 # deleted_elements = elements.delete_all('//book') - # deleted_elements.size # => 3 + # deleted_elements.size # => 2 # elements.size # => 0 # elements.delete_all('//book') # => [] # @@ -1220,15 +1221,68 @@ def delete_all( xpath ) return rv end - # Adds an element - # element:: - # if supplied, is either an Element, String, or - # Source (see Element.initialize). If not supplied or nil, a - # new, default Element will be constructed - # Returns:: the added Element - # a = Element.new('a') - # a.elements.add(Element.new('b')) #-> <a><b/></a> - # a.elements.add('c') #-> <a><b/><c/></a> + # :call-seq: + # add -> new_element + # add(name) -> new_element + # add(element) -> element + # + # Adds an element; returns the element added. + # + # With no argument, creates and adds a new element. + # The new element has: + # + # - No name. + # - \Parent from the \Elements object. + # - Context from the that parent. + # + # Example: + # + # d = REXML::Document.new(xml_string) + # elements = d.root.elements + # parent = elements.parent # => <bookstore> ... </> + # parent.context = {raw: :all} + # elements.size # => 4 + # new_element = elements.add # => </> + # elements.size # => 5 + # new_element.name # => nil + # new_element.parent # => <bookstore> ... </> + # new_element.context # => {:raw=>:all} + # + # With string argument +name+, creates and adds a new element. + # The new element has: + # + # - Name +name+. + # - \Parent from the \Elements object. + # - Context from the that parent. + # + # Example: + # + # d = REXML::Document.new(xml_string) + # elements = d.root.elements + # parent = elements.parent # => <bookstore> ... </> + # parent.context = {raw: :all} + # elements.size # => 4 + # new_element = elements.add('foo') # => <foo/> + # elements.size # => 5 + # new_element.name # => "foo" + # new_element.parent # => <bookstore> ... </> + # new_element.context # => {:raw=>:all} + # + # With argument +element+, + # creates and adds a clone of the given +element+. + # The new element has name, parent, and context from the given +element+. + # + # d = REXML::Document.new(xml_string) + # elements = d.root.elements + # elements.size # => 4 + # e0 = REXML::Element.new('foo') + # e1 = REXML::Element.new('bar', e0, {raw: :all}) + # element = elements.add(e1) # => <bar/> + # elements.size # => 5 + # element.name # => "bar" + # element.parent # => <bookstore> ... </> + # element.context # => {:raw=>:all} + # def add element=nil if element.nil? Element.new("", self, @element.context) @@ -1243,24 +1297,55 @@ def add element=nil alias :<< :add - # Iterates through all of the child Elements, optionally filtering - # them by a given XPath - # xpath:: - # optional. If supplied, this is a String XPath, and is used to - # filter the children, so that only matching children are yielded. Note - # that XPaths are automatically filtered for Elements, so that - # non-Element children will not be yielded - # doc = Document.new '<a><b/><c/><d/>sean<b/><c/><d/></a>' - # doc.root.elements.each {|e|p e} #-> Yields b, c, d, b, c, d elements - # doc.root.elements.each('b') {|e|p e} #-> Yields b, b elements - # doc.root.elements.each('child::node()') {|e|p e} - # #-> Yields <b/>, <c/>, <d/>, <b/>, <c/>, <d/> - # XPath.each(doc.root, 'child::node()', &block) - # #-> Yields <b/>, <c/>, <d/>, sean, <b/>, <c/>, <d/> + # :call-seq: + # each(xpath = nil) {|element| ... } -> self + # + # Iterates over the elements. + # + # With no argument, calls the block with each element: + # + # d = REXML::Document.new(xml_string) + # elements = d.root.elements + # elements.each {|element| p element } + # + # Output: + # + # <book category='cooking'> ... </> + # <book category='children'> ... </> + # <book category='web'> ... </> + # <book category='web' cover='paperback'> ... </> + # + # With argument +xpath+, calls the block with each element + # that matches the given +xpath+: + # + # elements.each('//book [@category="web"]') {|element| p element } + # + # Output: + # + # <book category='web'> ... </> + # <book category='web' cover='paperback'> ... </> + # def each( xpath=nil ) XPath::each( @element, xpath ) {|e| yield e if e.kind_of? Element } end + # :call-seq: + # collect(xpath = nil) {|element| ... } -> array + # + # Iterates over the elements; returns the array of block return values. + # + # With no argument, iterates over all elements: + # + # d = REXML::Document.new(xml_string) + # elements = d.root.elements + # elements.collect {|element| element.size } # => [9, 9, 17, 9] + # + # With argument +xpath+, iterates over elements that match + # the given +xpath+: + # + # xpath = '//book [@category="web"]' + # elements.collect(xpath) {|element| element.size } # => [17, 9] + # def collect( xpath=nil ) collection = [] XPath::each( @element, xpath ) {|e| @@ -1269,6 +1354,83 @@ def collect( xpath=nil ) collection end + # :call-seq: + # inject(xpath = nil, initial = nil) -> object + # + # Calls the block with elements; returns the last block return value. + # + # With no argument, iterates over the elements, calling the block + # <tt>elements.size - 1</tt> times. + # + # - The first call passes the first and second elements. + # - The second call passes the first block return value and the third element. + # - The third call passes the second block return value and the fourth element. + # - And so on. + # + # In this example, the block returns the passed element, + # which is then the object argument to the next call: + # + # d = REXML::Document.new(xml_string) + # elements = d.root.elements + # elements.inject do |object, element| + # p [elements.index(object), elements.index(element)] + # element + # end + # + # Output: + # + # [1, 2] + # [2, 3] + # [3, 4] + # + # With the single argument +xpath+, calls the block only with + # elements matching that xpath: + # + # elements.inject('//book [@category="web"]') do |object, element| + # p [elements.index(object), elements.index(element)] + # element + # end + # + # Output: + # + # [3, 4] + # + # With argument +xpath+ given as +nil+ + # and argument +initial+ also given, + # calls the block once for each element. + # + # - The first call passes the +initial+ and the first element. + # - The second call passes the first block return value and the second element. + # - The third call passes the second block return value and the third element. + # - And so on. + # + # In this example, the first object index is <tt>-1</tt> + # + # elements.inject(nil, 'Initial') do |object, element| + # p [elements.index(object), elements.index(element)] + # element + # end + # + # Output: + # + # [-1, 1] + # [1, 2] + # [2, 3] + # [3, 4] + # + # In this form the passed object can be used as an accumulator: + # + # elements.inject(nil, 0) do |total, element| + # total += element.size + # end # => 44 + # + # With both arguments +xpath+ and +initial+ are given, + # calls the block only with elements matching that xpath: + # + # elements.inject('//book [@category="web"]', 0) do |total, element| + # total += element.size + # end # => 26 + # def inject( xpath=nil, initial=nil ) first = true XPath::each( @element, xpath ) {|e| @@ -1284,23 +1446,39 @@ def inject( xpath=nil, initial=nil ) initial end - # Returns the number of +Element+ children of the parent object. - # doc = Document.new '<a>sean<b/>elliott<b/>russell<b/></a>' - # doc.root.size #-> 6, 3 element and 3 text nodes - # doc.root.elements.size #-> 3 + # :call-seq: + # size -> integer + # + # Returns the count of \Element children: + # + # d = REXML::Document.new '<a>sean<b/>elliott<b/>russell<b/></a>' + # d.root.elements.size # => 3 # Three elements. + # d.root.size # => 6 # Three elements plus three text nodes.. + # def size count = 0 @element.each {|child| count+=1 if child.kind_of? Element } count end - # Returns an Array of Element children. An XPath may be supplied to - # filter the children. Only Element children are returned, even if the - # supplied XPath matches non-Element children. - # doc = Document.new '<a>sean<b/>elliott<c/></a>' - # doc.root.elements.to_a #-> [ <b/>, <c/> ] - # doc.root.elements.to_a("child::node()") #-> [ <b/>, <c/> ] - # XPath.match(doc.root, "child::node()") #-> [ sean, <b/>, elliott, <c/> ] + # :call-seq: + # to_a(xpath = nil) -> array_of_elements + # + # Returns an array of element children (not including non-element children). + # + # With no argument, returns an array of all element children: + # + # d = REXML::Document.new '<a>sean<b/>elliott<c/></a>' + # elements = d.root.elements + # elements.to_a # => [<b/>, <c/>] # Omits non-element children. + # children = d.root.children + # children # => ["sean", <b/>, "elliott", <c/>] # Includes non-element children. + # + # With argument +xpath+, returns an array of element children + # that match the xpath: + # + # elements.to_a('//c') # => [<c/>] + # def to_a( xpath=nil ) rv = XPath.match( @element, xpath ) return rv.find_all{|e| e.kind_of? Element} if xpath From 92ea3306469396df4328ffc0728d265ccd04f851 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Yahoo.com> Date: Fri, 12 Feb 2021 16:09:56 -0600 Subject: [PATCH 34/56] Enhanced RDoc for Attributes (#54) --- lib/rexml/element.rb | 323 +++++++++++++++++++++++++++++++++---------- 1 file changed, 251 insertions(+), 72 deletions(-) diff --git a/lib/rexml/element.rb b/lib/rexml/element.rb index 0fe950e8..4aac09ff 100644 --- a/lib/rexml/element.rb +++ b/lib/rexml/element.rb @@ -1500,36 +1500,89 @@ def literalize name # A class that defines the set of Attributes of an Element and provides # operations for accessing elements in that set. class Attributes < Hash - # Constructor - # element:: the Element of which this is an Attribute + + # :call-seq: + # new(element) + # + # Creates and returns a new \REXML::Attributes object. + # The element given by argument +element+ is stored, + # but its own attributes are not modified: + # + # ele = REXML::Element.new('foo') + # attrs = REXML::Attributes.new(ele) + # attrs.object_id == ele.attributes.object_id # => false + # + # Other instance methods in class \REXML::Attributes may refer to: + # + # - +element.document+. + # - +element.prefix+. + # - +element.expanded_name+. + # def initialize element @element = element end - # Fetches an attribute value. If you want to get the Attribute itself, - # use get_attribute() - # name:: an XPath attribute name. Namespaces are relevant here. - # Returns:: - # the String value of the matching attribute, or +nil+ if no - # matching attribute was found. This is the unnormalized value - # (with entities expanded). + # :call-seq: + # [name] -> attribute_value or nil + # + # Returns the value for the attribute given by +name+, + # if it exists; otherwise +nil+. + # The value returned is the unnormalized attribute value, + # with entities expanded: + # + # xml_string = <<-EOT + # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> + # <ele foo:att='1' bar:att='2' att='<'/> + # </root> + # EOT + # d = REXML::Document.new(xml_string) + # ele = d.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> + # ele.attributes['att'] # => "<" + # ele.attributes['bar:att'] # => "2" + # ele.attributes['nosuch'] # => nil + # + # Related: get_attribute (returns an \Attribute object). # - # doc = Document.new "<a foo:att='1' bar:att='2' att='<'/>" - # doc.root.attributes['att'] #-> '<' - # doc.root.attributes['bar:att'] #-> '2' def [](name) attr = get_attribute(name) return attr.value unless attr.nil? return nil end + # :call-seq: + # to_a -> array_of_attribute_objects + # + # Returns an array of \REXML::Attribute objects representing + # the attributes: + # + # xml_string = <<-EOT + # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> + # <ele foo:att='1' bar:att='2' att='<'/> + # </root> + # EOT + # d = REXML::Document.new(xml_string) + # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> + # attrs = ele.attributes.to_a # => [foo:att='1', bar:att='2', att='<'] + # attrs.first.class # => REXML::Attribute + # def to_a enum_for(:each_attribute).to_a end - # Returns the number of attributes the owning Element contains. - # doc = Document "<a x='1' y='2' foo:x='3'/>" - # doc.root.attributes.length #-> 3 + # :call-seq: + # length + # + # Returns the count of attributes: + # + # xml_string = <<-EOT + # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> + # <ele foo:att='1' bar:att='2' att='<'/> + # </root> + # EOT + # d = REXML::Document.new(xml_string) + # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> + # ele.attributes.length # => 3 + # def length c = 0 each_attribute { c+=1 } @@ -1537,13 +1590,28 @@ def length end alias :size :length - # Iterates over the attributes of an Element. Yields actual Attribute - # nodes, not String values. + # :call-seq: + # each_attribute {|attr| ... } + # + # Calls the given block with each \REXML::Attribute object: + # + # xml_string = <<-EOT + # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> + # <ele foo:att='1' bar:att='2' att='<'/> + # </root> + # EOT + # d = REXML::Document.new(xml_string) + # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> + # ele.attributes.each_attribute do |attr| + # p [attr.class, attr] + # end + # + # Output: + # + # [REXML::Attribute, foo:att='1'] + # [REXML::Attribute, bar:att='2'] + # [REXML::Attribute, att='<'] # - # doc = Document.new '<a x="1" y="2"/>' - # doc.root.attributes.each_attribute {|attr| - # p attr.expanded_name+" => "+attr.value - # } def each_attribute # :yields: attribute return to_enum(__method__) unless block_given? each_value do |val| @@ -1555,11 +1623,28 @@ def each_attribute # :yields: attribute end end - # Iterates over each attribute of an Element, yielding the expanded name - # and value as a pair of Strings. + # :call-seq: + # each {|expanded_name, value| ... } + # + # Calls the given block with each expanded-name/value pair: + # + # xml_string = <<-EOT + # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> + # <ele foo:att='1' bar:att='2' att='<'/> + # </root> + # EOT + # d = REXML::Document.new(xml_string) + # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> + # ele.attributes.each do |expanded_name, value| + # p [expanded_name, value] + # end + # + # Output: + # + # ["foo:att", "1"] + # ["bar:att", "2"] + # ["att", "<"] # - # doc = Document.new '<a x="1" y="2"/>' - # doc.root.attributes.each {|name, value| p name+" => "+value } def each return to_enum(__method__) unless block_given? each_attribute do |attr| @@ -1567,15 +1652,25 @@ def each end end - # Fetches an attribute - # name:: - # the name by which to search for the attribute. Can be a - # <tt>prefix:name</tt> namespace name. - # Returns:: The first matching attribute, or nil if there was none. This - # value is an Attribute node, not the String value of the attribute. - # doc = Document.new '<a x:foo="1" foo="2" bar="3"/>' - # doc.root.attributes.get_attribute("foo").value #-> "2" - # doc.root.attributes.get_attribute("x:foo").value #-> "1" + # :call-seq: + # get_attribute(name) -> attribute_object or nil + # + # Returns the \REXML::Attribute object for the given +name+: + # + # xml_string = <<-EOT + # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> + # <ele foo:att='1' bar:att='2' att='<'/> + # </root> + # EOT + # d = REXML::Document.new(xml_string) + # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> + # attrs = ele.attributes + # attrs.get_attribute('foo:att') # => foo:att='1' + # attrs.get_attribute('foo:att').class # => REXML::Attribute + # attrs.get_attribute('bar:att') # => bar:att='2' + # attrs.get_attribute('att') # => att='<' + # attrs.get_attribute('nosuch') # => nil + # def get_attribute( name ) attr = fetch( name, nil ) if attr.nil? @@ -1609,18 +1704,29 @@ def get_attribute( name ) return attr end - # Sets an attribute, overwriting any existing attribute value by the - # same name. Namespace is significant. - # name:: the name of the attribute - # value:: - # (optional) If supplied, the value of the attribute. If - # nil, any existing matching attribute is deleted. - # Returns:: - # Owning element - # doc = Document.new "<a x:foo='1' foo='3'/>" - # doc.root.attributes['y:foo'] = '2' - # doc.root.attributes['foo'] = '4' - # doc.root.attributes['x:foo'] = nil + # :call-seq: + # [name] = value -> value + # + # When +value+ is non-+nil+, + # assigns that to the attribute for the given +name+, + # overwriting the previous value if it exists: + # + # xml_string = <<-EOT + # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> + # <ele foo:att='1' bar:att='2' att='<'/> + # </root> + # EOT + # d = REXML::Document.new(xml_string) + # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> + # attrs = ele.attributes + # attrs['foo:att'] = '2' # => "2" + # attrs['baz:att'] = '3' # => "3" + # + # When +value+ is +nil+, deletes the attribute if it exists: + # + # attrs['baz:att'] = nil + # attrs.include?('baz:att') # => false + # def []=( name, value ) if value.nil? # Delete the named attribute attr = get_attribute(name) @@ -1662,12 +1768,17 @@ def []=( name, value ) return @element end - # Returns an array of Strings containing all of the prefixes declared - # by this set of # attributes. The array does not include the default + # :call-seq: + # prefixes -> array_of_prefix_strings + # + # Returns an array of prefix strings in the attributes. + # The array does not include the default # namespace declaration, if one exists. - # doc = Document.new("<a xmlns='foo' xmlns:x='bar' xmlns:y='twee' "+ - # "z='glorp' p:k='gru'/>") - # prefixes = doc.root.attributes.prefixes #-> ['x', 'y'] + # + # xml_string = '<a xmlns="foo" xmlns:x="bar" xmlns:y="twee" z="glorp"/>' + # d = REXML::Document.new(xml_string) + # d.root.attributes.prefixes # => ["x", "y"] + # def prefixes ns = [] each_attribute do |attribute| @@ -1684,6 +1795,15 @@ def prefixes ns end + # :call-seq: + # namespaces + # + # Returns a hash of name/value pairs for the namespaces: + # + # xml_string = '<a xmlns="foo" xmlns:x="bar" xmlns:y="twee" z="glorp"/>' + # d = REXML::Document.new(xml_string) + # d.root.attributes.namespaces # => {"xmlns"=>"foo", "x"=>"bar", "y"=>"twee"} + # def namespaces namespaces = {} each_attribute do |attribute| @@ -1700,16 +1820,34 @@ def namespaces namespaces end - # Removes an attribute - # attribute:: - # either a String, which is the name of the attribute to remove -- - # namespaces are significant here -- or the attribute to remove. - # Returns:: the owning element - # doc = Document.new "<a y:foo='0' x:foo='1' foo='3' z:foo='4'/>" - # doc.root.attributes.delete 'foo' #-> <a y:foo='0' x:foo='1' z:foo='4'/>" - # doc.root.attributes.delete 'x:foo' #-> <a y:foo='0' z:foo='4'/>" - # attr = doc.root.attributes.get_attribute('y:foo') - # doc.root.attributes.delete attr #-> <a z:foo='4'/>" + # :call-seq: + # delete(name) -> element + # delete(attribute) -> element + # + # Removes a specified attribute if it exists; + # returns the attributes' element. + # + # When string argument +name+ is given, + # removes the attribute of that name if it exists: + # + # xml_string = <<-EOT + # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> + # <ele foo:att='1' bar:att='2' att='<'/> + # </root> + # EOT + # d = REXML::Document.new(xml_string) + # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> + # attrs = ele.attributes + # attrs.delete('foo:att') # => <ele bar:att='2' att='<'/> + # attrs.delete('foo:att') # => <ele bar:att='2' att='<'/> + # + # When attribute argument +attribute+ is given, + # removes that attribute if it exists: + # + # attr = REXML::Attribute.new('bar:att', '2') + # attrs.delete(attr) # => <ele att='<'/> # => <ele att='<'/> + # attrs.delete(attr) # => <ele att='<'/> # => <ele/> + # def delete( attribute ) name = nil prefix = nil @@ -1737,19 +1875,48 @@ def delete( attribute ) @element end - # Adds an attribute, overriding any existing attribute by the - # same name. Namespaces are significant. - # attribute:: An Attribute + # :call-seq: + # add(attribute) -> attribute + # + # Adds attribute +attribute+, replacing the previous + # attribute of the same name if it exists; + # returns +attribute+: + # + # xml_string = <<-EOT + # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> + # <ele foo:att='1' bar:att='2' att='<'/> + # </root> + # EOT + # d = REXML::Document.new(xml_string) + # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> + # attrs = ele.attributes + # attrs # => {"att"=>{"foo"=>foo:att='1', "bar"=>bar:att='2', ""=>att='<'}} + # attrs.add(REXML::Attribute.new('foo:att', '2')) # => foo:att='2' + # attrs.add(REXML::Attribute.new('baz', '3')) # => baz='3' + # attrs.include?('baz') # => true + # def add( attribute ) self[attribute.name] = attribute end alias :<< :add - # Deletes all attributes matching a name. Namespaces are significant. - # name:: - # A String; all attributes that match this path will be removed - # Returns:: an Array of the Attributes that were removed + # :call-seq: + # delete_all(name) -> array_of_removed_attributes + # + # Removes all attributes matching the given +name+; + # returns an array of the removed attributes: + # + # xml_string = <<-EOT + # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> + # <ele foo:att='1' bar:att='2' att='<'/> + # </root> + # EOT + # d = REXML::Document.new(xml_string) + # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> + # attrs = ele.attributes + # attrs.delete_all('att') # => [att='<'] + # def delete_all( name ) rv = [] each_attribute { |attribute| @@ -1759,11 +1926,23 @@ def delete_all( name ) return rv end - # The +get_attribute_ns+ method retrieves a method by its namespace - # and name. Thus it is possible to reliably identify an attribute - # even if an XML processor has changed the prefix. + # :call-seq: + # get_attribute_ns(namespace, name) + # + # Returns the \REXML::Attribute object among the attributes + # that matches the given +namespace+ and +name+: + # + # xml_string = <<-EOT + # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> + # <ele foo:att='1' bar:att='2' att='<'/> + # </root> + # EOT + # d = REXML::Document.new(xml_string) + # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> + # attrs = ele.attributes + # attrs.get_attribute_ns('http://foo', 'att') # => foo:att='1' + # attrs.get_attribute_ns('http://foo', 'nosuch') # => nil # - # Method contributed by Henrik Martensson def get_attribute_ns(namespace, name) result = nil each_attribute() { |attribute| From b858bcad2c318a9001cceae805ce1f758582ec71 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Yahoo.com> Date: Sat, 13 Feb 2021 16:39:04 -0600 Subject: [PATCH 35/56] Enhanced RDoc for Element (#55) --- lib/rexml/element.rb | 316 +++++++++++++++++++++++++++++++------------ 1 file changed, 229 insertions(+), 87 deletions(-) diff --git a/lib/rexml/element.rb b/lib/rexml/element.rb index 4aac09ff..02f73e0b 100644 --- a/lib/rexml/element.rb +++ b/lib/rexml/element.rb @@ -436,20 +436,40 @@ def delete_namespace namespace="xmlns" # Elements # ################################################# - # Adds a child to this element, optionally setting attributes in - # the element. - # element:: - # optional. If Element, the element is added. - # Otherwise, a new Element is constructed with the argument (see - # Element.initialize). - # attrs:: - # If supplied, must be a Hash containing String name,value - # pairs, which will be used to set the attributes of the new Element. - # Returns:: the Element that was added - # el = doc.add_element 'my-tag' - # el = doc.add_element 'my-tag', {'attr1'=>'val1', 'attr2'=>'val2'} - # el = Element.new 'my-tag' - # doc.add_element el + # :call-seq: + # add_element(name, attributes = nil) -> new_element + # add_element(element, attributes = nil) -> element + # + # Adds a child element, optionally setting attributes + # on the added element; returns the added element. + # + # With string argument +name+, creates a new element with that name + # and adds the new element as a child: + # + # e0 = REXML::Element.new('foo') + # e0.add_element('bar') + # e0[0] # => <bar/> + # + # + # With argument +name+ and hash argument +attributes+, + # sets attributes on the new element: + # + # e0.add_element('baz', {'bat' => '0', 'bam' => '1'}) + # e0[1] # => <baz bat='0' bam='1'/> + # + # With element argument +element+, adds that element as a child: + # + # e0 = REXML::Element.new('foo') + # e1 = REXML::Element.new('bar') + # e0.add_element(e1) + # e0[0] # => <bar/> + # + # With argument +element+ and hash argument +attributes+, + # sets attributes on the added element: + # + # e0.add_element(e1, {'bat' => '0', 'bam' => '1'}) + # e0[1] # => <bar bat='0' bam='1'/> + # def add_element element, attrs=nil raise "First argument must be either an element name, or an Element object" if element.nil? el = @elements.add(element) @@ -459,52 +479,112 @@ def add_element element, attrs=nil el end + # :call-seq: + # delete_element(index) -> removed_element or nil + # delete_element(element) -> removed_element or nil + # delete_element(xpath) -> removed_element or nil + # # Deletes a child element. - # element:: - # Must be an +Element+, +String+, or +Integer+. If Element, - # the element is removed. If String, the element is found (via XPath) - # and removed. <em>This means that any parent can remove any - # descendant.<em> If Integer, the Element indexed by that number will be - # removed. - # Returns:: the element that was removed. - # doc.delete_element "/a/b/c[@id='4']" - # doc.delete_element doc.elements["//k"] - # doc.delete_element 1 + # + # When 1-based integer argument +index+ is given, + # removes and returns the child element at that offset if it exists; + # indexing does not include text nodes; + # returns +nil+ if the element does not exist: + # + # d = REXML::Document.new '<a><b/>text<c/></a>' + # a = d.root # => <a> ... </> + # a.delete_element(1) # => <b/> + # a.delete_element(1) # => <c/> + # a.delete_element(1) # => nil + # + # When element argument +element+ is given, + # removes and returns that child element if it exists, + # otherwise returns +nil+: + # + # d = REXML::Document.new '<a><b/>text<c/></a>' + # a = d.root # => <a> ... </> + # c = a[2] # => <c/> + # a.delete_element(c) # => <c/> + # a.delete_element(c) # => nil + # + # When xpath argument +xpath+ is given, + # removes and returns the element at xpath if it exists, + # otherwise returns +nil+: + # + # d = REXML::Document.new '<a><b/>text<c/></a>' + # a = d.root # => <a> ... </> + # a.delete_element('//c') # => <c/> + # a.delete_element('//c') # => nil + # def delete_element element @elements.delete element end - # Evaluates to +true+ if this element has at least one child Element - # doc = Document.new "<a><b/><c>Text</c></a>" - # doc.root.has_elements # -> true - # doc.elements["/a/b"].has_elements # -> false - # doc.elements["/a/c"].has_elements # -> false + # :call-seq: + # has_elements? + # + # Returns +true+ if the element has one or more element children, + # +false+ otherwise: + # + # d = REXML::Document.new '<a><b/>text<c/></a>' + # a = d.root # => <a> ... </> + # a.has_elements? # => true + # b = a[0] # => <b/> + # b.has_elements? # => false + # def has_elements? !@elements.empty? end - # Iterates through the child elements, yielding for each Element that - # has a particular attribute set. - # key:: - # the name of the attribute to search for - # value:: - # the value of the attribute - # max:: - # (optional) causes this method to return after yielding - # for this number of matching children - # name:: - # (optional) if supplied, this is an XPath that filters - # the children to check. - # - # doc = Document.new "<a><b @id='1'/><c @id='2'/><d @id='1'/><e/></a>" - # # Yields b, c, d - # doc.root.each_element_with_attribute( 'id' ) {|e| p e} - # # Yields b, d - # doc.root.each_element_with_attribute( 'id', '1' ) {|e| p e} - # # Yields b - # doc.root.each_element_with_attribute( 'id', '1', 1 ) {|e| p e} - # # Yields d - # doc.root.each_element_with_attribute( 'id', '1', 0, 'd' ) {|e| p e} + # :call-seq: + # each_element_with_attribute(attr_name, value = nil, max = 0, xpath = nil) {|e| ... } + # + # Calls the given block with each child element that meets given criteria. + # + # When only string argument +attr_name+ is given, + # calls the block with each child element that has that attribute: + # + # d = REXML::Document.new '<a><b id="1"/><c id="2"/><d id="1"/><e/></a>' + # a = d.root + # a.each_element_with_attribute('id') {|e| p e } + # + # Output: + # + # <b id='1'/> + # <c id='2'/> + # <d id='1'/> + # + # With argument +attr_name+ and string argument +value+ given, + # calls the block with each child element that has that attribute + # with that value: + # + # a.each_element_with_attribute('id', '1') {|e| p e } + # + # Output: + # + # <b id='1'/> + # <d id='1'/> + # + # With arguments +attr_name+, +value+, and integer argument +max+ given, + # calls the block with at most +max+ child elements: + # + # a.each_element_with_attribute('id', '1', 1) {|e| p e } + # + # Output: + # + # <b id='1'/> + # + # With all arguments given, including +xpath+, + # calls the block with only those child elements + # that meet the first three criteria, + # and also match the given +xpath+: + # + # a.each_element_with_attribute('id', '1', 2, '//d') {|e| p e } + # + # Output: + # + # <d id='1'/> + # def each_element_with_attribute( key, value=nil, max=0, name=nil, &block ) # :yields: Element each_with_something( proc {|child| if value.nil? @@ -515,27 +595,53 @@ def each_element_with_attribute( key, value=nil, max=0, name=nil, &block ) # :yi }, max, name, &block ) end - # Iterates through the children, yielding for each Element that - # has a particular text set. - # text:: - # the text to search for. If nil, or not supplied, will iterate - # over all +Element+ children that contain at least one +Text+ node. - # max:: - # (optional) causes this method to return after yielding - # for this number of matching children - # name:: - # (optional) if supplied, this is an XPath that filters - # the children to check. - # - # doc = Document.new '<a><b>b</b><c>b</c><d>d</d><e/></a>' - # # Yields b, c, d - # doc.each_element_with_text {|e|p e} - # # Yields b, c - # doc.each_element_with_text('b'){|e|p e} - # # Yields b - # doc.each_element_with_text('b', 1){|e|p e} - # # Yields d - # doc.each_element_with_text(nil, 0, 'd'){|e|p e} + # :call-seq: + # each_element_with_text(text = nil, max = 0, xpath = nil) {|e| ... } + # + # Calls the given block with each child element that meets given criteria. + # + # With no arguments, calls the block with each child element that has text: + # + # d = REXML::Document.new '<a><b>b</b><c>b</c><d>d</d><e/></a>' + # a = d.root + # a.each_element_with_text {|e| p e } + # + # Output: + # + # <b> ... </> + # <c> ... </> + # <d> ... </> + # + # With the single string argument +text+, + # calls the block with each element that has exactly that text: + # + # a.each_element_with_text('b') {|e| p e } + # + # Output: + # + # <b> ... </> + # <c> ... </> + # + # With argument +text+ and integer argument +max+, + # calls the block with at most +max+ elements: + # + # a.each_element_with_text('b', 1) {|e| p e } + # + # Output: + # + # <b> ... </> + # + # With all arguments given, including +xpath+, + # calls the block with only those child elements + # that meet the first two criteria, + # and also match the given +xpath+: + # + # a.each_element_with_text('b', 2, '//c') {|e| p e } + # + # Output: + # + # <c> ... </> + # def each_element_with_text( text=nil, max=0, name=nil, &block ) # :yields: Element each_with_something( proc {|child| if text.nil? @@ -546,35 +652,71 @@ def each_element_with_text( text=nil, max=0, name=nil, &block ) # :yields: Eleme }, max, name, &block ) end - # Synonym for Element.elements.each + # :call-seq: + # each_element {|e| ... } + # + # Calls the given block with each child element: + # + # d = REXML::Document.new '<a><b>b</b><c>b</c><d>d</d><e/></a>' + # a = d.root + # a.each_element {|e| p e } + # + # Output: + # + # <b> ... </> + # <c> ... </> + # <d> ... </> + # <e/> + # def each_element( xpath=nil, &block ) # :yields: Element @elements.each( xpath, &block ) end - # Synonym for Element.to_a - # This is a little slower than calling elements.each directly. - # xpath:: any XPath by which to search for elements in the tree - # Returns:: an array of Elements that match the supplied path + # :call-seq: + # get_elements(xpath) + # + # Returns an array of the elements that match the given +xpath+: + # + # xml_string = <<-EOT + # <root> + # <a level='1'> + # <a level='2'/> + # </a> + # </root> + # EOT + # d = REXML::Document.new(xml_string) + # d.root.get_elements('//a') # => [<a level='1'> ... </>, <a level='2'/>] + # def get_elements( xpath ) @elements.to_a( xpath ) end - # Returns the next sibling that is an element, or nil if there is - # no Element sibling after this one - # doc = Document.new '<a><b/>text<c/></a>' - # doc.root.elements['b'].next_element #-> <c/> - # doc.root.elements['c'].next_element #-> nil + # :call-seq: + # next_element + # + # Returns the next sibling that is an element if it exists, + # +niL+ otherwise: + # + # d = REXML::Document.new '<a><b/>text<c/></a>' + # d.root.elements['b'].next_element #-> <c/> + # d.root.elements['c'].next_element #-> nil + # def next_element element = next_sibling element = element.next_sibling until element.nil? or element.kind_of? Element return element end - # Returns the previous sibling that is an element, or nil if there is - # no Element sibling prior to this one - # doc = Document.new '<a><b/>text<c/></a>' - # doc.root.elements['c'].previous_element #-> <b/> - # doc.root.elements['b'].previous_element #-> nil + # :call-seq: + # previous_element + # + # Returns the previous sibling that is an element if it exists, + # +niL+ otherwise: + # + # d = REXML::Document.new '<a><b/>text<c/></a>' + # d.root.elements['c'].previous_element #-> <b/> + # d.root.elements['b'].previous_element #-> nil + # def previous_element element = previous_sibling element = element.previous_sibling until element.nil? or element.kind_of? Element From db36d5e06652819f6f725ecfc35a47b64f63cffc Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Yahoo.com> Date: Sun, 14 Feb 2021 15:06:30 -0600 Subject: [PATCH 36/56] Enhanced RDoc for Element (#57) --- lib/rexml/element.rb | 191 ++++++++++++++++++++++++++++++++----------- 1 file changed, 143 insertions(+), 48 deletions(-) diff --git a/lib/rexml/element.rb b/lib/rexml/element.rb index 02f73e0b..38761586 100644 --- a/lib/rexml/element.rb +++ b/lib/rexml/element.rb @@ -728,36 +728,69 @@ def previous_element # Text # ################################################# - # Evaluates to +true+ if this element has at least one Text child + # :call-seq: + # has_text? -> true or false + # + # Returns +true if the element has one or more text noded, + # +false+ otherwise: + # + # d = REXML::Document.new '<a><b/>text<c/></a>' + # a = d.root + # a.has_text? # => true + # b = a[0] + # b.has_text? # => false + # def has_text? not text().nil? end - # A convenience method which returns the String value of the _first_ - # child text element, if one exists, and +nil+ otherwise. + # :call-seq: + # text(xpath = nil) -> text_string or nil + # + # Returns the text string from the first text node child + # in a specified element, if it exists, # +nil+ otherwise. + # + # With no argument, returns the text from the first text node in +self+: + # + # d = REXML::Document.new "<p>some text <b>this is bold!</b> more text</p>" + # d.root.text.class # => String + # d.root.text # => "some text " # - # <em>Note that an element may have multiple Text elements, perhaps - # separated by other children</em>. Be aware that this method only returns - # the first Text node. + # With argument +xpath+, returns text from the the first text node + # in the element that matches +xpath+: # - # This method returns the +value+ of the first text child node, which - # ignores the +raw+ setting, so always returns normalized text. See - # the Text::value documentation. + # d.root.text(1) # => "this is bold!" + # + # Note that an element may have multiple text nodes, + # possibly separated by other non-text children, as above. + # Even so, the returned value is the string text from the first such node. + # + # Note also that the text note is retrieved by method get_text, + # and so is always normalized text. # - # doc = Document.new "<p>some text <b>this is bold!</b> more text</p>" - # # The element 'p' has two text elements, "some text " and " more text". - # doc.root.text #-> "some text " def text( path = nil ) rv = get_text(path) return rv.value unless rv.nil? nil end - # Returns the first child Text node, if any, or +nil+ otherwise. - # This method returns the actual +Text+ node, rather than the String content. - # doc = Document.new "<p>some text <b>this is bold!</b> more text</p>" - # # The element 'p' has two text elements, "some text " and " more text". - # doc.root.get_text.value #-> "some text " + # :call-seq: + # get_text(xpath = nil) -> text_node or nil + # + # Returns the first text node child in a specified element, if it exists, + # +nil+ otherwise. + # + # With no argument, returns the first text node from +self+: + # + # d = REXML::Document.new "<p>some text <b>this is bold!</b> more text</p>" + # d.root.get_text.class # => REXML::Text + # d.root.get_text # => "some text " + # + # With argument +xpath+, returns the first text node from the element + # that matches +xpath+: + # + # d.root.get_text(1) # => "this is bold!" + # def get_text path = nil rv = nil if path @@ -769,26 +802,31 @@ def get_text path = nil return rv end - # Sets the first Text child of this object. See text() for a - # discussion about Text children. - # - # If a Text child already exists, the child is replaced by this - # content. This means that Text content can be deleted by calling - # this method with a nil argument. In this case, the next Text - # child becomes the first Text child. In no case is the order of - # any siblings disturbed. - # text:: - # If a String, a new Text child is created and added to - # this Element as the first Text child. If Text, the text is set - # as the first Child element. If nil, then any existing first Text - # child is removed. - # Returns:: this Element. - # doc = Document.new '<a><b/></a>' - # doc.root.text = 'Sean' #-> '<a><b/>Sean</a>' - # doc.root.text = 'Elliott' #-> '<a><b/>Elliott</a>' - # doc.root.add_element 'c' #-> '<a><b/>Elliott<c/></a>' - # doc.root.text = 'Russell' #-> '<a><b/>Russell<c/></a>' - # doc.root.text = nil #-> '<a><b/><c/></a>' + # :call-seq: + # text = string -> string + # text = nil -> nil + # + # Adds, replaces, or removes the first text node child in the element. + # + # With string argument +string+, + # creates a new \REXML::Text node containing that string, + # honoring the current settings for whitespace and row, + # then places the node as the first text child in the element; + # returns +string+. + # + # If the element has no text child, the text node is added: + # + # d = REXML::Document.new '<a><b/></a>' + # d.root.text = 'foo' #-> '<a><b/>foo</a>' + # + # If the element has a text child, it is replaced: + # + # d.root.text = 'bar' #-> '<a><b/>bar</a>' + # + # With argument +nil+, removes the first text child: + # + # d.root.text = nil #-> '<a><b/><c/></a>' + # def text=( text ) if text.kind_of? String text = Text.new( text, whitespace(), nil, raw() ) @@ -808,17 +846,45 @@ def text=( text ) return self end - # A helper method to add a Text child. Actual Text instances can - # be added with regular Parent methods, such as add() and <<() - # text:: - # if a String, a new Text instance is created and added - # to the parent. If Text, the object is added directly. - # Returns:: this Element - # e = Element.new('a') #-> <e/> - # e.add_text 'foo' #-> <e>foo</e> - # e.add_text Text.new(' bar') #-> <e>foo bar</e> - # Note that at the end of this example, the branch has <b>3</b> nodes; the 'e' - # element and <b>2</b> Text node children. + # :call-seq: + # add_text(string) -> nil + # add_text(text_node) -> self + # + # Adds text to the element. + # + # When string argument +string+ is given, returns +nil+. + # + # If the element has no child text node, + # creates a \REXML::Text object using the string, + # honoring the current settings for whitespace and raw, + # then adds that node to the element: + # + # d = REXML::Document.new('<a><b/></a>') + # a = d.root + # a.add_text('foo') + # a.to_a # => [<b/>, "foo"] + # + # If the element has child text nodes, + # appends the string to the _last_ text node: + # + # d = REXML::Document.new('<a>foo<b/>bar</a>') + # a = d.root + # a.add_text('baz') + # a.to_a # => ["foo", <b/>, "barbaz"] + # a.add_text('baz') + # a.to_a # => ["foo", <b/>, "barbazbaz"] + # + # When text node argument +text_node+ is given, + # appends the node as the last text node in the element; + # returns +self+: + # + # d = REXML::Document.new('<a>foo<b/>bar</a>') + # a = d.root + # a.add_text(REXML::Text.new('baz')) + # a.to_a # => ["foo", <b/>, "bar", "baz"] + # a.add_text(REXML::Text.new('baz')) + # a.to_a # => ["foo", <b/>, "bar", "baz", "baz"] + # def add_text( text ) if text.kind_of? String if @children[-1].kind_of? Text @@ -831,10 +897,39 @@ def add_text( text ) return self end + # :call-seq: + # node_type -> :element + # + # Returns symbol <tt>:element</tt>: + # + # d = REXML::Document.new('<a/>') + # a = d.root # => <a/> + # a.node_type # => :element + # def node_type :element end + # :call-seq: + # xpath -> string_xpath + # + # Returns the string xpath to the element + # relative to the most distant parent: + # + # d = REXML::Document.new('<a><b><c/></b></a>') + # a = d.root # => <a> ... </> + # b = a[0] # => <b> ... </> + # c = b[0] # => <c/> + # d.xpath # => "" + # a.xpath # => "/a" + # b.xpath # => "/a/b" + # c.xpath # => "/a/b/c" + # + # If there is no parent, returns the expanded name of the element: + # + # e = REXML::Element.new('foo') + # e.xpath # => "foo" + # def xpath path_elements = [] cur = self From fd0ced0a2dfaab70ebb32a95cc7d222ff955117c Mon Sep 17 00:00:00 2001 From: Sutou Kouhei <kou@clear-code.com> Date: Tue, 23 Feb 2021 15:50:51 +0900 Subject: [PATCH 37/56] REXML::DocType: fix a bug that #clone doesn't copy external ID info --- lib/rexml/doctype.rb | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/rexml/doctype.rb b/lib/rexml/doctype.rb index 757b6396..d020f31d 100644 --- a/lib/rexml/doctype.rb +++ b/lib/rexml/doctype.rb @@ -50,6 +50,8 @@ def initialize( first, parent=nil ) super( parent ) @name = first.name @external_id = first.external_id + @long_name = first.instance_variable_get(:@long_name) + @uri = first.instance_variable_get(:@uri) elsif first.kind_of? Array super( parent ) @name = first[0] From 935584ecadafbfac34f783c585352b46c9f1f4bb Mon Sep 17 00:00:00 2001 From: Sutou Kouhei <kou@clear-code.com> Date: Tue, 23 Feb 2021 15:52:20 +0900 Subject: [PATCH 38/56] test: use setup not initialize --- test/test_martin_fowler.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/test/test_martin_fowler.rb b/test/test_martin_fowler.rb index 3d27c7a0..ce27d725 100644 --- a/test/test_martin_fowler.rb +++ b/test/test_martin_fowler.rb @@ -16,12 +16,12 @@ class OrderTesterMF < Test::Unit::TestCase </paper> END - def initialize n + def setup @doc = REXML::Document.new(DOC) @figs = REXML::XPath.match(@doc,'//figure') @names = @figs.collect {|f| f.attributes['src']} - super end + def test_fig1 assert_equal 'fig1', @figs[0].attributes['src'] end From ab6845b871cb2ee6cd2add6c70c8eb51cacd34eb Mon Sep 17 00:00:00 2001 From: Sutou Kouhei <kou@clear-code.com> Date: Tue, 23 Feb 2021 15:53:27 +0900 Subject: [PATCH 39/56] test: fix a bug that XML path not content is parsed --- test/test_light.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/test/test_light.rb b/test/test_light.rb index 3a10fb2c..54b2c52e 100644 --- a/test/test_light.rb +++ b/test/test_light.rb @@ -9,10 +9,10 @@ class LightTester < Test::Unit::TestCase include REXML::Light def test_parse_large - xml_string = fixture_path("documentation.xml") + xml_string = File.read(fixture_path("documentation.xml")) parser = REXML::Parsers::LightParser.new(xml_string) tag, content = parser.parse - assert_equal([:document, :text], [tag, content.first]) + assert_equal([:document, :xmldecl], [tag, content.first]) end # FIXME INCOMPLETE From f7721dc5109efcb1f5d31f7712a81591f0d24729 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei <kou@clear-code.com> Date: Tue, 23 Feb 2021 15:54:35 +0900 Subject: [PATCH 40/56] test: remove invalid XML "<!DOCTYPE PUBLIC" must have system literal. --- test/test_doctype.rb | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/test/test_doctype.rb b/test/test_doctype.rb index aa656c51..a00c5d00 100644 --- a/test/test_doctype.rb +++ b/test/test_doctype.rb @@ -16,12 +16,6 @@ def setup @doc_type_system = REXML::Document.new(xml_system).doctype @pubid = "TEST_ID" - xml_public = <<-XML - <!DOCTYPE root PUBLIC "#{@pubid}"> - <root/> - XML - @doc_type_public = REXML::Document.new(xml_public).doctype - xml_public_system = <<-XML <!DOCTYPE root PUBLIC "#{@pubid}" "#{@sysid}"> <root/> @@ -33,11 +27,9 @@ def test_public assert_equal([ nil, @pubid, - @pubid, ], [ @doc_type_system.public, - @doc_type_public.public, @doc_type_public_system.public, ]) end @@ -56,12 +48,10 @@ def test_to_s_apostrophe def test_system assert_equal([ @sysid, - nil, @sysid, ], [ @doc_type_system.system, - @doc_type_public.system, @doc_type_public_system.system, ]) end From e86516510fd7474db7c80d0ec72cb54bb6c38ea3 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei <kou@clear-code.com> Date: Tue, 23 Feb 2021 15:56:12 +0900 Subject: [PATCH 41/56] test: fix invalid XML DOCTYPE needs SYSTEM before system literal. --- test/test_core.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/test_core.rb b/test/test_core.rb index 544c137a..fd3af8c2 100644 --- a/test/test_core.rb +++ b/test/test_core.rb @@ -1041,7 +1041,7 @@ def test_write_doctype document.write(s) ## XML Doctype - str = '<!DOCTYPE foo "bar">' + str = '<!DOCTYPE foo SYSTEM "bar">' source = REXML::Source.new(str) doctype = REXML::DocType.new(source) document.add(doctype) From 58f22026438cbbf765ce87d3511b47c2d06d793f Mon Sep 17 00:00:00 2001 From: Sutou Kouhei <kou@clear-code.com> Date: Tue, 23 Feb 2021 15:57:28 +0900 Subject: [PATCH 42/56] test: fix invalid XML XML must have a root element. --- test/test_contrib.rb | 1 + 1 file changed, 1 insertion(+) diff --git a/test/test_contrib.rb b/test/test_contrib.rb index ee5be2f6..f3ad0b6c 100644 --- a/test/test_contrib.rb +++ b/test/test_contrib.rb @@ -70,6 +70,7 @@ def test_bad_doctype_Tobias > ] > + <svg/> EOF doc = REXML::Document.new source doc.write(out="") From e545aa3ea3ce62a8c1394734dd3a07c69cfa11bf Mon Sep 17 00:00:00 2001 From: Sutou Kouhei <kou@clear-code.com> Date: Tue, 23 Feb 2021 16:07:40 +0900 Subject: [PATCH 43/56] REXML::DocType: remove needless quote strip Because parser already strips quotes. --- lib/rexml/doctype.rb | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/lib/rexml/doctype.rb b/lib/rexml/doctype.rb index d020f31d..dcfa0cfc 100644 --- a/lib/rexml/doctype.rb +++ b/lib/rexml/doctype.rb @@ -161,7 +161,7 @@ def public when "SYSTEM" nil when "PUBLIC" - strip_quotes(@long_name) + @long_name end end @@ -171,9 +171,9 @@ def public def system case @external_id when "SYSTEM" - strip_quotes(@long_name) + @long_name when "PUBLIC" - @uri.kind_of?(String) ? strip_quotes(@uri) : nil + @uri.kind_of?(String) ? @uri : nil end end @@ -195,15 +195,6 @@ def notation(name) notation_decl.name == name } end - - private - - # Method contributed by Henrik Martensson - def strip_quotes(quoted_string) - quoted_string =~ /^[\'\"].*[\'\"]$/ ? - quoted_string[1, quoted_string.length-2] : - quoted_string - end end # We don't really handle any of these since we're not a validating From e23a00b5d5267dfb25086b069271a81d38b63783 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Yahoo.com> Date: Mon, 1 Mar 2021 15:47:59 -0600 Subject: [PATCH 44/56] Enhanced RDoc for Element (#61) --- lib/rexml/element.rb | 248 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 196 insertions(+), 52 deletions(-) diff --git a/lib/rexml/element.rb b/lib/rexml/element.rb index 38761586..c406f7a6 100644 --- a/lib/rexml/element.rb +++ b/lib/rexml/element.rb @@ -945,19 +945,45 @@ def xpath # Attributes # ################################################# - # Fetches an attribute value or a child. + # :call-seq: + # [index] -> object + # [attr_name] -> attr_value + # [attr_sym] -> attr_value + # + # With integer argument +index+ given, + # returns the child at offset +index+, or +nil+ if none: + # + # d = REXML::Document.new '><root><a/>text<b/>more<c/></root>' + # root = d.root + # (0..root.size).each do |index| + # node = root[index] + # p "#{index}: #{node} (#{node.class})" + # end + # + # Output: + # + # "0: <a/> (REXML::Element)" + # "1: text (REXML::Text)" + # "2: <b/> (REXML::Element)" + # "3: more (REXML::Text)" + # "4: <c/> (REXML::Element)" + # "5: (NilClass)" + # + # With string argument +attr_name+ given, + # returns the string value for the given attribute name if it exists, + # otherwise +nil+: + # + # d = REXML::Document.new('<root attr="value"></root>') + # root = d.root + # root['attr'] # => "value" + # root['nosuch'] # => nil # - # If String or Symbol is specified, it's treated as attribute - # name. Attribute value as String or +nil+ is returned. This case - # is shortcut of +attributes[name]+. + # With symbol argument +attr_sym+ given, + # returns <tt>[attr_sym.to_s]</tt>: # - # If Integer is specified, it's treated as the index of - # child. It returns Nth child. + # root[:attr] # => "value" + # root[:nosuch] # => nil # - # doc = REXML::Document.new("<a attr='1'><b/><c/></a>") - # doc.root["attr"] # => "1" - # doc.root.attributes["attr"] # => "1" - # doc.root[1] # => <c/> def [](name_or_index) case name_or_index when String @@ -969,6 +995,36 @@ def [](name_or_index) end end + + # :call-seq: + # attribute(name, namespace = nil) + # + # Returns the string value for the given attribute name. + # + # With only argument +name+ given, + # returns the value of the named attribute if it exists, otherwise +nil+: + # + # xml_string = <<-EOT + # <root xmlns="ns0"> + # <a xmlns="ns1" attr="value"></a> + # <b xmlns="ns2" attr="value"></b> + # <c attr="value"/> + # </root> + # EOT + # d = REXML::Document.new(xml_string) + # root = d.root + # a = root[1] # => <a xmlns='ns1' attr='value'/> + # a.attribute('attr') # => attr='value' + # a.attribute('nope') # => nil + # + # With arguments +name+ and +namespace+ given, + # returns the value of the named attribute if it exists, otherwise +nil+: + # + # xml_string = "<root xmlns:a='a' a:x='a:x' x='x'/>" + # document = REXML::Document.new(xml_string) + # document.root.attribute("x") # => x='x' + # document.root.attribute("x", "a") # => a:x='a:x' + # def attribute( name, namespace=nil ) prefix = nil if namespaces.respond_to? :key @@ -992,29 +1048,46 @@ def attribute( name, namespace=nil ) end - # Evaluates to +true+ if this element has any attributes set, false - # otherwise. + # :call-seq: + # has_attributes? -> true or false + # + # Returns +true+ if the element has attributes, +false+ otherwise: + # + # d = REXML::Document.new('<root><a attr="val"/><b/></root>') + # a, b = *d.root + # a.has_attributes? # => true + # b.has_attributes? # => false + # def has_attributes? return !@attributes.empty? end + # :call-seq: + # add_attribute(name, value) -> value + # add_attribute(attribute) -> attribute + # # Adds an attribute to this element, overwriting any existing attribute # by the same name. - # key:: - # can be either an Attribute or a String. If an Attribute, - # the attribute is added to the list of Element attributes. If String, - # the argument is used as the name of the new attribute, and the value - # parameter must be supplied. - # value:: - # Required if +key+ is a String, and ignored if the first argument is - # an Attribute. This is a String, and is used as the value - # of the new Attribute. This should be the unnormalized value of the - # attribute (without entities). - # Returns:: the Attribute added - # e = Element.new 'e' - # e.add_attribute( 'a', 'b' ) #-> <e a='b'/> - # e.add_attribute( 'x:a', 'c' ) #-> <e a='b' x:a='c'/> - # e.add_attribute Attribute.new('b', 'd') #-> <e a='b' x:a='c' b='d'/> + # + # With string argument +name+ and object +value+ are given, + # adds the attribute created with that name and value: + # + # e = REXML::Element.new + # e.add_attribute('attr', 'value') # => "value" + # e['attr'] # => "value" + # e.add_attribute('attr', 'VALUE') # => "VALUE" + # e['attr'] # => "VALUE" + # + # With only attribute object +attribute+ given, + # adds the given attribute: + # + # a = REXML::Attribute.new('attr', 'value') + # e.add_attribute(a) # => attr='value' + # e['attr'] # => "value" + # a = REXML::Attribute.new('attr', 'VALUE') + # e.add_attribute(a) # => attr='VALUE' + # e['attr'] # => "VALUE" + # def add_attribute( key, value=nil ) if key.kind_of? Attribute @attributes << key @@ -1023,10 +1096,29 @@ def add_attribute( key, value=nil ) end end - # Add multiple attributes to this element. - # hash:: is either a hash, or array of arrays - # el.add_attributes( {"name1"=>"value1", "name2"=>"value2"} ) - # el.add_attributes( [ ["name1","value1"], ["name2"=>"value2"] ] ) + # :call-seq: + # add_attributes(hash) -> hash + # add_attributes(array) + # + # Adds zero or more attributes to the element; + # returns the argument. + # + # If hash argument +hash+ is given, + # each key must be a string; + # adds each attribute created with the key/value pair: + # + # e = REXML::Element.new + # h = {'foo' => 'bar', 'baz' => 'bat'} + # e.add_attributes(h) + # + # If argument +array+ is given, + # each array member must be a 2-element array <tt>[name, value]; + # each name must be a string: + # + # e = REXML::Element.new + # a = [['foo' => 'bar'], ['baz' => 'bat']] + # e.add_attributes(a) + # def add_attributes hash if hash.kind_of? Hash hash.each_pair {|key, value| @attributes[key] = value } @@ -1035,19 +1127,17 @@ def add_attributes hash end end - # Removes an attribute - # key:: - # either an Attribute or a String. In either case, the - # attribute is found by matching the attribute name to the argument, - # and then removed. If no attribute is found, no action is taken. - # Returns:: - # the attribute removed, or nil if this Element did not contain - # a matching attribute - # e = Element.new('E') - # e.add_attribute( 'name', 'Sean' ) #-> <E name='Sean'/> - # r = e.add_attribute( 'sur:name', 'Russell' ) #-> <E name='Sean' sur:name='Russell'/> - # e.delete_attribute( 'name' ) #-> <E sur:name='Russell'/> - # e.delete_attribute( r ) #-> <E/> + # :call-seq: + # delete_attribute(name) -> removed_attribute or nil + # + # Removes a named attribute if it exists; + # returns the removed attribute if found, otherwise +nil+: + # + # e = REXML::Element.new('foo') + # e.add_attribute('bar', 'baz') + # e.delete_attribute('bar') # => <bar/> + # e.delete_attribute('bar') # => nil + # def delete_attribute(key) attr = @attributes.get_attribute(key) attr.remove unless attr.nil? @@ -1057,26 +1147,80 @@ def delete_attribute(key) # Other Utilities # ################################################# - # Get an array of all CData children. - # IMMUTABLE + # :call-seq: + # cdatas -> array_of_cdata_children + # + # Returns a frozen array of the REXML::CData children of the element: + # + # xml_string = <<-EOT + # <root> + # <![CDATA[foo]]> + # <![CDATA[bar]]> + # </root> + # EOT + # d = REXML::Document.new(xml_string) + # cds = d.root.cdatas # => ["foo", "bar"] + # cds.frozen? # => true + # cds.map {|cd| cd.class } # => [REXML::CData, REXML::CData] + # def cdatas find_all { |child| child.kind_of? CData }.freeze end - # Get an array of all Comment children. - # IMMUTABLE + # :call-seq: + # comments -> array_of_comment_children + # + # Returns a frozen array of the REXML::Comment children of the element: + # + # xml_string = <<-EOT + # <root> + # <!--foo--> + # <!--bar--> + # </root> + # EOT + # d = REXML::Document.new(xml_string) + # cs = d.root.comments + # cs.frozen? # => true + # cs.map {|c| c.class } # => [REXML::Comment, REXML::Comment] + # cs.map {|c| c.to_s } # => ["foo", "bar"] + # def comments find_all { |child| child.kind_of? Comment }.freeze end - # Get an array of all Instruction children. - # IMMUTABLE + # :call-seq: + # instructions -> array_of_instruction_children + # + # Returns a frozen array of the REXML::Instruction children of the element: + # + # xml_string = <<-EOT + # <root> + # <?target0 foo?> + # <?target1 bar?> + # </root> + # EOT + # d = REXML::Document.new(xml_string) + # is = d.root.instructions + # is.frozen? # => true + # is.map {|i| i.class } # => [REXML::Instruction, REXML::Instruction] + # is.map {|i| i.to_s } # => ["<?target0 foo?>", "<?target1 bar?>"] + # def instructions find_all { |child| child.kind_of? Instruction }.freeze end - # Get an array of all Text children. - # IMMUTABLE + # :call-seq: + # texts -> array_of_text_children + # + # Returns a frozen array of the REXML::Text children of the element: + # + # xml_string = '<root><a/>text<b/>more<c/></root>' + # d = REXML::Document.new(xml_string) + # ts = d.root.texts + # ts.frozen? # => true + # ts.map {|t| t.class } # => [REXML::Text, REXML::Text] + # ts.map {|t| t.to_s } # => ["text", "more"] + # def texts find_all { |child| child.kind_of? Text }.freeze end From 77be80e438ef0668f95db941d82026109cb7d8ca Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Yahoo.com> Date: Mon, 1 Mar 2021 23:04:05 -0600 Subject: [PATCH 45/56] Enhanced RDoc for Element (#62) --- lib/rexml/element.rb | 255 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 252 insertions(+), 3 deletions(-) diff --git a/lib/rexml/element.rb b/lib/rexml/element.rb index c406f7a6..39e6ebcb 100644 --- a/lib/rexml/element.rb +++ b/lib/rexml/element.rb @@ -15,9 +15,258 @@ module REXML # context node and convert it back when we write it. @@namespaces = {} - # Represents a tagged XML element. Elements are characterized by - # having children, attributes, and names, and can themselves be - # children. + # An \REXML::Element object represents an XML element. + # + # An element: + # + # - Has a name (string). + # - May have a parent (another element). + # - Has zero or more children + # (other elements, text, CDATA, processing instructions, and comments). + # - Has zero or more siblings + # (other elements, text, CDATA, processing instructions, and comments). + # - Has zero or more named attributes. + # + # === Name + # + # An element has a name, which is initially set when the element is created: + # + # e = REXML::Element.new('foo') + # e.name # => "foo" + # + # The name may be changed: + # + # e.name = 'bar' + # e.name # => "bar" + # + # + # === \Parent + # + # An element may have a parent. + # + # Its parent may be assigned explicitly when the element is created: + # + # e0 = REXML::Element.new('foo') + # e1 = REXML::Element.new('bar', e0) + # e1.parent # => <foo> ... </> + # + # Note: the representation of an element always shows the element's name. + # If the element has children, the representation indicates that + # by including an ellipsis (<tt>...</tt>). + # + # The parent may be assigned explicitly at any time: + # + # e2 = REXML::Element.new('baz') + # e1.parent = e2 + # e1.parent # => <baz/> + # + # When an element is added as a child, its parent is set automatically: + # + # e1.add_element(e0) + # e0.parent # => <bar> ... </> + # + # For an element that has no parent, method +parent+ returns +nil+. + # + # === Children + # + # An element has zero or more children. + # The children are an ordered collection + # of all objects whose parent is the element itself. + # + # The children may include any combination of elements, text, comments, + # processing instructions, and CDATA. + # (This example keeps things clean by controlling whitespace + # via a +context+ setting.) + # + # xml_string = <<-EOT + # <root> + # <ele_0/> + # text 0 + # <!--comment 0--> + # <?target_0 pi_0?> + # <![CDATA[cdata 0]]> + # <ele_1/> + # text 1 + # <!--comment 1--> + # <?target_0 pi_1?> + # <![CDATA[cdata 1]]> + # </root> + # EOT + # context = {ignore_whitespace_nodes: :all, compress_whitespace: :all} + # d = REXML::Document.new(xml_string, context) + # root = d.root + # root.children.size # => 10 + # root.each {|child| p "#{child.class}: #{child}" } + # + # Output: + # + # "REXML::Element: <ele_0/>" + # "REXML::Text: \n text 0\n " + # "REXML::Comment: comment 0" + # "REXML::Instruction: <?target_0 pi_0?>" + # "REXML::CData: cdata 0" + # "REXML::Element: <ele_1/>" + # "REXML::Text: \n text 1\n " + # "REXML::Comment: comment 1" + # "REXML::Instruction: <?target_0 pi_1?>" + # "REXML::CData: cdata 1" + # + # A child may be added using inherited methods + # Parent#insert_before or Parent#insert_after: + # + # xml_string = '<root><a/><c/><d/></root>' + # d = REXML::Document.new(xml_string) + # root = d.root + # c = d.root[1] # => <c/> + # root.insert_before(c, REXML::Element.new('b')) + # root.to_a # => [<a/>, <b/>, <c/>, <d/>] + # + # A child may be replaced using Parent#replace_child: + # + # root.replace_child(c, REXML::Element.new('x')) + # root.to_a # => [<a/>, <b/>, <x/>, <d/>] + # + # A child may be removed using Parent#delete: + # + # x = root[2] # => <x/> + # root.delete(x) + # root.to_a # => [<a/>, <b/>, <d/>] + # + # === Siblings + # + # An element has zero or more siblings, + # which are the other children of the element's parent. + # + # In the example above, element +ele_1+ is between a CDATA sibling + # and a text sibling: + # + # ele_1 = root[5] # => <ele_1/> + # ele_1.previous_sibling # => "cdata 0" + # ele_1.next_sibling # => "\n text 1\n " + # + # === \Attributes + # + # An element has zero or more named attributes. + # + # A new element has no attributes: + # + # e = REXML::Element.new('foo') + # e.attributes # => {} + # + # Attributes may be added: + # + # e.add_attribute('bar', 'baz') + # e.add_attribute('bat', 'bam') + # e.attributes.size # => 2 + # e['bar'] # => "baz" + # e['bat'] # => "bam" + # + # An existing attribute may be modified: + # + # e.add_attribute('bar', 'bad') + # e.attributes.size # => 2 + # e['bar'] # => "bad" + # + # An existing attribute may be deleted: + # + # e.delete_attribute('bar') + # e.attributes.size # => 1 + # e['bar'] # => nil + # + # == What's Here + # + # To begin with, what's elsewhere? + # + # \Class \REXML::Element inherits from its ancestor classes: + # + # - REXML::Child + # - REXML::Parent + # + # \REXML::Element itself and its ancestors also include modules: + # + # - {Enumerable}[https://docs.ruby-lang.org/en/master/Enumerable.html] + # - REXML::Namespace + # - REXML::Node + # - REXML::XMLTokens + # + # === Methods for Creating an \Element + # + # ::new:: Returns a new empty element. + # #clone:: Returns a clone of another element. + # + # === Methods for Attributes + # + # {[attribute_name]}[#method-i-5B-5D]:: Returns an attribute value. + # #add_attribute:: Adds a new attribute. + # #add_attributes:: Adds multiple new attributes. + # #attribute:: Returns the attribute value for a given name and optional namespace. + # #delete_attribute:: Removes an attribute. + # + # === Methods for Children + # + # {[index]}[#method-i-5B-5D]:: Returns the child at the given offset. + # #add_element:: Adds an element as the last child. + # #delete_element:: Deletes a child element. + # #each_element:: Calls the given block with each child element. + # #each_element_with_attribute:: Calls the given block with each child element + # that meets given criteria, + # which can include the attribute name. + # #each_element_with_text:: Calls the given block with each child element + # that meets given criteria, + # which can include text. + # #get_elements:: Returns an array of element children that match a given xpath. + # + # === Methods for \Text Children + # + # #add_text:: Adds a text node to the element. + # #get_text:: Returns a text node that meets specified criteria. + # #text:: Returns the text string from the first node that meets specified criteria. + # #texts:: Returns an array of the text children of the element. + # #text=:: Adds, removes, or replaces the first text child of the element + # + # === Methods for Other Children + # + # #cdatas:: Returns an array of the cdata children of the element. + # #comments:: Returns an array of the comment children of the element. + # #instructions:: Returns an array of the instruction children of the element. + # + # === Methods for Namespaces + # + # #add_namespace:: Adds a namespace to the element. + # #delete_namespace:: Removes a namespace from the element. + # #namespace:: Returns the string namespace URI for the element. + # #namespaces:: Returns a hash of all defined namespaces in the element. + # #prefixes:: Returns an array of the string prefixes (names) + # of all defined namespaces in the element + # + # === Methods for Querying + # + # #document:: Returns the document, if any, that the element belongs to. + # #root:: Returns the most distant element (not document) ancestor of the element. + # #root_node:: Returns the most distant ancestor of the element. + # #xpath:: Returns the string xpath to the element + # relative to the most distant parent + # #has_attributes?:: Returns whether the element has attributes. + # #has_elements?:: Returns whether the element has elements. + # #has_text?:: Returns whether the element has text. + # #next_element:: Returns the next sibling that is an element. + # #previous_element:: Returns the previous sibling that is an element. + # #raw:: Returns whether raw mode is set for the element. + # #whitespace:: Returns whether whitespace is respected for the element. + # #ignore_whitespace_nodes:: Returns whether whitespace nodes + # are to be ignored for the element. + # #node_type:: Returns symbol <tt>:element</tt>. + # + # === One More Method + # + # #inspect:: Returns a string representation of the element. + # + # === Accessors + # + # #elements:: Returns the REXML::Elements object for the element. + # #attributes:: Returns the REXML::Attributes object for the element. + # #context:: Returns or sets the context hash for the element. + # class Element < Parent include Namespace From 83bd4dce4226544f85b56bbe7fbd2f8d7da84188 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Yahoo.com> Date: Mon, 8 Mar 2021 17:48:52 -0600 Subject: [PATCH 46/56] Task-oriented documentation (#64) --- Rakefile | 2 + doc/rexml/tasks/rdoc/child.rdoc | 87 ++++ doc/rexml/tasks/rdoc/document.rdoc | 276 ++++++++++++ doc/rexml/tasks/rdoc/element.rdoc | 602 +++++++++++++++++++++++++ doc/rexml/tasks/rdoc/node.rdoc | 97 ++++ doc/rexml/tasks/rdoc/parent.rdoc | 267 +++++++++++ doc/rexml/tasks/tocs/child_toc.rdoc | 12 + doc/rexml/tasks/tocs/document_toc.rdoc | 30 ++ doc/rexml/tasks/tocs/element_toc.rdoc | 55 +++ doc/rexml/tasks/tocs/master_toc.rdoc | 135 ++++++ doc/rexml/tasks/tocs/node_toc.rdoc | 16 + doc/rexml/tasks/tocs/parent_toc.rdoc | 25 + rexml.gemspec | 7 + tasks/tocs.rake | 95 ++++ 14 files changed, 1706 insertions(+) create mode 100644 doc/rexml/tasks/rdoc/child.rdoc create mode 100644 doc/rexml/tasks/rdoc/document.rdoc create mode 100644 doc/rexml/tasks/rdoc/element.rdoc create mode 100644 doc/rexml/tasks/rdoc/node.rdoc create mode 100644 doc/rexml/tasks/rdoc/parent.rdoc create mode 100644 doc/rexml/tasks/tocs/child_toc.rdoc create mode 100644 doc/rexml/tasks/tocs/document_toc.rdoc create mode 100644 doc/rexml/tasks/tocs/element_toc.rdoc create mode 100644 doc/rexml/tasks/tocs/master_toc.rdoc create mode 100644 doc/rexml/tasks/tocs/node_toc.rdoc create mode 100644 doc/rexml/tasks/tocs/parent_toc.rdoc create mode 100644 tasks/tocs.rake diff --git a/Rakefile b/Rakefile index e0485b20..7143e754 100644 --- a/Rakefile +++ b/Rakefile @@ -26,3 +26,5 @@ RDoc::Task.new do |rdoc| rdoc.rdoc_files.include(*spec.source_paths) rdoc.rdoc_files.include(*spec.extra_rdoc_files) end + +load "#{__dir__}/tasks/tocs.rake" diff --git a/doc/rexml/tasks/rdoc/child.rdoc b/doc/rexml/tasks/rdoc/child.rdoc new file mode 100644 index 00000000..89536381 --- /dev/null +++ b/doc/rexml/tasks/rdoc/child.rdoc @@ -0,0 +1,87 @@ +== Class Child + +Class Child includes module Node; +see {Tasks for Node}[node_rdoc.html]. + +:include: ../tocs/child_toc.rdoc + +=== Relationships + +==== Task: Set the Parent + +Use method {Child#parent=}[../../../../REXML/Parent.html#method-i-parent-3D] +to set the parent: + + e0 = REXML::Element.new('foo') + e1 = REXML::Element.new('bar') + e1.parent # => nil + e1.parent = e0 + e1.parent # => <foo/> + +==== Task: Insert Previous Sibling + +Use method {Child#previous_sibling=}[../../../../REXML/Parent.html#method-i-previous_sibling-3D] +to insert a previous sibling: + + xml_string = '<root><a/><c/></root>' + d = REXML::Document.new(xml_string) + d.root.to_a # => [<a/>, <c/>] + c = d.root[1] # => <c/> + b = REXML::Element.new('b') + c.previous_sibling = b + d.root.to_a # => [<a/>, <b/>, <c/>] + +==== Task: Insert Next Sibling + +Use method {Child#next_sibling=}[../../../../REXML/Parent.html#method-i-next-sibling-3D] +to insert a previous sibling: + + xml_string = '<root><a/><c/></root>' + d = REXML::Document.new(xml_string) + d.root.to_a # => [<a/>, <c/>] + a = d.root[0] # => <a/> + b = REXML::Element.new('b') + a.next_sibling = b + d.root.to_a # => [<a/>, <b/>, <c/>] + +=== Removal or Replacement + +==== Task: Remove Child from Parent + +Use method {Child#remove}[../../../../REXML/Parent.html#method-i-remove] +to remove a child from its parent; returns the removed child: + + xml_string = '<root><a/><b/><c/></root>' + d = REXML::Document.new(xml_string) + d.root.to_a # => [<a/>, <b/>, <c/>] + b = d.root[1] # => <b/> + b.remove # => <b/> + d.root.to_a # => [<a/>, <c/>] + +==== Task: Replace Child + +Use method {Child#replace_with}[../../../../REXML/Parent.html#method-i-replace] +to replace a child; +returns the replaced child: + + xml_string = '<root><a/><b/><c/></root>' + d = REXML::Document.new(xml_string) + d.root.to_a # => [<a/>, <b/>, <c/>] + b = d.root[1] # => <b/> + d = REXML::Element.new('d') + b.replace_with(d) # => <b/> + d.root.to_a # => [<a/>, <d/>, <c/>] + +=== Document + +==== Task: Get the Document + +Use method {Child#document}[../../../../REXML/Parent.html#method-i-document] +to get the document for the child: + + xml_string = '<root><a/><b/><c/></root>' + d = REXML::Document.new(xml_string) + d.root.to_a # => [<a/>, <b/>, <c/>] + b = d.root[1] # => <b/> + b.document == d # => true + REXML::Child.new.document # => nil diff --git a/doc/rexml/tasks/rdoc/document.rdoc b/doc/rexml/tasks/rdoc/document.rdoc new file mode 100644 index 00000000..96d03351 --- /dev/null +++ b/doc/rexml/tasks/rdoc/document.rdoc @@ -0,0 +1,276 @@ +== Class Document + +Class Document has methods from its superclasses and included modules; +see: + +- {Tasks for Element}[element_rdoc.html]. +- {Tasks for Parent}[parent_rdoc.html]. +- {Tasks for Child}[child_rdoc.html]. +- {Tasks for Node}[node_rdoc.html]. +- {Module Enumerable}[https://docs.ruby-lang.org/en/master/Enumerable.html]. + +:include: ../tocs/document_toc.rdoc + +=== New Document + +==== Task: Create an Empty Document + +Use method {Document::new}[../../../../REXML/Document.html#method-c-new] +to create an empty document. + + d = REXML::Document.new + +==== Task: Parse a \String into a New Document + +Use method {Document::new}[../../../../REXML/Document.html#method-c-new] +to parse an XML string into a new document: + + xml_string = '<root><a/>text<b/>more<c/></root>' + d = REXML::Document.new(xml_string) + d.root # => <root> ... </> + +==== Task: Parse an \IO Stream into a New Document + +Use method {Document::new}[../../../../REXML/Document.html#method-c-new] +to parse an XML \IO stream into a new document: + + xml_string = '<root><a/>text<b/>more<c/></root>' + File.write('t.xml', xml_string) + d = File.open('t.xml', 'r') do |file| + REXML::Document.new(file) + end + d.root # => <root> ... </> + +==== Task: Create a Document from an Existing Document + +Use method {Document::new}[../../../../REXML/Document.html#method-c-new] +to create a document from an existing document. +The context and attributes are copied to the new document, +but not the children: + + xml_string = '<root><a/>text<b/>more<c/></root>' + d = REXML::Document.new(xml_string) + d.children # => [<root> ... </>] + d.context = {raw: :all, compress_whitespace: :all} + d.add_attributes({'bar' => 0, 'baz' => 1}) + d1 = REXML::Document.new(d) + d1.context # => {:raw=>:all, :compress_whitespace=>:all} + d1.attributes # => {"bar"=>bar='0', "baz"=>baz='1'} + d1.children # => [] + +==== Task: Clone a Document + +Use method {Document#clone}[../../../../REXML/Document.html#method-i-clone] +to clone a document. +The context and attributes are copied to the new document, +but not the children: + + xml_string = '<root><a/>text<b/>more<c/></root>' + d = REXML::Document.new(xml_string) + d.children # => [<root> ... </>] + d.context = {raw: :all, compress_whitespace: :all} + d.add_attributes({'bar' => 0, 'baz' => 1}) + d1 = d.clone # => < bar='0' baz='1'/> + d1.context # => {:raw=>:all, :compress_whitespace=>:all} + d1.attributes # => {"bar"=>bar='0', "baz"=>baz='1'} + d1.children # => [] + +=== Document Type + +==== Task: Get the Document Type + +Use method {Document#doctype}[../../../../REXML/Document.html#method-i-doctype] +to get the document type: + + d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">') + d.doctype.class # => REXML::DocType + d = REXML::Document.new('') + d.doctype.class # => nil + +==== Task: Set the Document Type + +Use method {document#add}[../../../../REXML/Document.html#method-i-add] +to add or replace the document type: + + d = REXML::Document.new('') + d.doctype.class # => nil + d.add(REXML::DocType.new('foo')) + d.doctype.class # => REXML::DocType + +=== XML Declaration + +==== Task: Get the XML Declaration + +Use method {document#xml_decl}[../../../../REXML/Document.html#method-i-xml_decl] +to get the XML declaration: + + d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">') + d.xml_decl.class # => REXML::XMLDecl + d.xml_decl # => <?xml ... ?> + d = REXML::Document.new('') + d.xml_decl.class # => REXML::XMLDecl + d.xml_decl # => <?xml ... ?> + +==== Task: Set the XML Declaration + +Use method {document#add}[../../../../REXML/Document.html#method-i-add] +to replace the XML declaration: + + d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">') + d.add(REXML::XMLDecl.new) + +=== Children + +==== Task: Add an Element Child + +Use method +{document#add_element}[../../../../REXML/Document.html#method-i-add_element] +to add an element to the document: + + d = REXML::Document.new('') + d.add_element(REXML::Element.new('root')) + d.children # => [<root/>] + +==== Task: Add a Non-Element Child + +Use method +{document#add}[../../../../REXML/Document.html#method-i-add] +to add a non-element to the document: + + xml_string = '<root><a/>text<b/>more<c/></root>' + d = REXML::Document.new(xml_string) + d.add(REXML::Text.new('foo')) + d.children # => [<root> ... </>, "foo"] + +=== Writing + +==== Task: Write to $stdout + +Use method +{document#write}[../../../../REXML/Document.html#method-i-write] +to write the document to <tt>$stdout</tt>: + + xml_string = '<root><a/>text<b/>more<c/></root>' + d = REXML::Document.new(xml_string) + d.write + +Output: + + <root><a/>text<b/>more<c/></root> + +==== Task: Write to IO Stream + +Use method +{document#write}[../../../../REXML/Document.html#method-i-write] +to write the document to <tt>$stdout</tt>: + + xml_string = '<root><a/>text<b/>more<c/></root>' + d = REXML::Document.new(xml_string) + File.open('t.xml', 'w') do |file| + d.write(file) + end + p File.read('t.xml') + +Output: + + "<root><a/>text<b/>more<c/></root>" + +==== Task: Write with No Indentation + +Use method +{document#write}[../../../../REXML/Document.html#method-i-write] +to write the document with no indentation: + + xml_string = '<root><a><b><c></c></b></a></root>' + d = REXML::Document.new(xml_string) + d.write({indent: 0}) + +Output: + + <root> + <a> + <b> + <c/> + </b> + </a> + </root> + +==== Task: Write with Specified Indentation + +Use method +{document#write}[../../../../REXML/Document.html#method-i-write] +to write the document with a specified indentation: + + xml_string = '<root><a><b><c></c></b></a></root>' + d = REXML::Document.new(xml_string) + d.write({indent: 2}) + +Output: + + <root> + <a> + <b> + <c/> + </b> + </a> + </root> + +=== Querying + +==== Task: Get the Document + +Use method +{document#document}[../../../../REXML/Document.html#method-i-document] +to get the document (+self+); overrides <tt>Element#document</tt>: + + xml_string = '<root><a><b><c></c></b></a></root>' + d = REXML::Document.new(xml_string) + d.document == d # => true + +==== Task: Get the Encoding + +Use method +{document#document}[../../../../REXML/Document.html#method-i-document] +to get the document (+self+); overrides <tt>Element#document</tt>: + + xml_string = '<root><a><b><c></c></b></a></root>' + d = REXML::Document.new(xml_string) + d.encoding # => "UTF-8" + +==== Task: Get the Node Type + +Use method +{document#node_type}[../../../../REXML/Document.html#method-i-node_type] +to get the node type (+:document+); overrides <tt>Element#node_type</tt>: + + xml_string = '<root><a><b><c></c></b></a></root>' + d = REXML::Document.new(xml_string) + d.node_type # => :document + +==== Task: Get the Root Element + +Use method +{document#root}[../../../../REXML/Document.html#method-i-root] +to get the root element: + + xml_string = '<root><a><b><c></c></b></a></root>' + d = REXML::Document.new(xml_string) + d.root # => <root> ... </> + +==== Task: Determine Whether Stand-Alone + +Use method +{document#stand_alone?}[../../../../REXML/Document.html#method-i-stand_alone-3F] +to get the stand-alone value: + + d = REXML::Document.new('<?xml standalone="yes"?>') + d.stand_alone? # => "yes" + +==== Task: Get the Version + +Use method +{document#version}[../../../../REXML/Document.html#method-i-version] +to get the version: + + d = REXML::Document.new('<?xml version="2.0" encoding="UTF-8"?>') + d.version # => "2.0" diff --git a/doc/rexml/tasks/rdoc/element.rdoc b/doc/rexml/tasks/rdoc/element.rdoc new file mode 100644 index 00000000..f229275f --- /dev/null +++ b/doc/rexml/tasks/rdoc/element.rdoc @@ -0,0 +1,602 @@ +== Class Element + +Class Element has methods from its superclasses and included modules; +see: + +- {Tasks for Parent}[parent_rdoc.html]. +- {Tasks for Child}[child_rdoc.html]. +- {Tasks for Node}[node_rdoc.html]. +- {Module Enumerable}[https://docs.ruby-lang.org/en/master/Enumerable.html]. + +:include: ../tocs/element_toc.rdoc + +=== New Element + +==== Task: Create a Default Element + +Use method +{Element::new}[../../../../REXML/Element.html#method-c-new] +with no arguments to create a default element: + + e = REXML::Element.new + e.name # => "UNDEFINED" + e.parent # => nil + e.context # => nil + +==== Task: Create a Named Element + +Use method +{Element::new}[../../../../REXML/Element.html#method-c-new] +with a string name argument +to create a named element: + + e = REXML::Element.new('foo') + e.name # => "foo" + e.parent # => nil + e.context # => nil + +==== Task: Create an Element with Name and Parent + +Use method +{Element::new}[../../../../REXML/Element.html#method-c-new] +with name and parent arguments +to create an element with name and parent: + + p = REXML::Parent.new + e = REXML::Element.new('foo', p) + e.name # => "foo" + e.parent # => #<REXML::Parent @parent=nil, @children=[<foo/>]> + e.context # => nil + +==== Task: Create an Element with Name, Parent, and Context + +Use method +{Element::new}[../../../../REXML/Element.html#method-c-new] +with name, parent, and context arguments +to create an element with name, parent, and context: + + p = REXML::Parent.new + e = REXML::Element.new('foo', p, {compress_whitespace: :all}) + e.name # => "foo" + e.parent # => #<REXML::Parent @parent=nil, @children=[<foo/>]> + e.context # => {:compress_whitespace=>:all} + +==== Task: Create a Shallow Clone + +Use method +{Element#clone}[../../../../REXML/Element.html#method-i-clone] +to create a shallow clone of an element, +copying only the name, attributes, and context: + + e0 = REXML::Element.new('foo', nil, {compress_whitespace: :all}) + e0.add_attribute(REXML::Attribute.new('bar', 'baz')) + e0.context = {compress_whitespace: :all} + e1 = e0.clone # => <foo bar='baz'/> + e1.name # => "foo" + e1.context # => {:compress_whitespace=>:all} + +=== Attributes + +==== Task: Create and Add an Attribute + +Use method +{Element#add_attribute}[../../../../REXML/Element.html#method-i-add_attribute] +to create and add an attribute: + + e = REXML::Element.new + e.add_attribute('attr', 'value') # => "value" + e['attr'] # => "value" + e.add_attribute('attr', 'VALUE') # => "VALUE" + e['attr'] # => "VALUE" + +==== Task: Add an Existing Attribute + +Use method +{Element#add_attribute}[../../../../REXML/Element.html#method-i-add_attribute] +to add an existing attribute: + + e = REXML::Element.new + a = REXML::Attribute.new('attr', 'value') + e.add_attribute(a) + e['attr'] # => "value" + a = REXML::Attribute.new('attr', 'VALUE') + e.add_attribute(a) + e['attr'] # => "VALUE" + +==== Task: Add Multiple Attributes from a Hash + +Use method +{Element#add_attributes}[../../../../REXML/Element.html#method-i-add_attributes] +to add multiple attributes from a hash: + + e = REXML::Element.new + h = {'foo' => 0, 'bar' => 1} + e.add_attributes(h) + e['foo'] # => "0" + e['bar'] # => "1" + +==== Task: Add Multiple Attributes from an Array + +Use method +{Element#add_attributes}[../../../../REXML/Element.html#method-i-add_attributes] +to add multiple attributes from an array: + + e = REXML::Element.new + a = [['foo', 0], ['bar', 1]] + e.add_attributes(a) + e['foo'] # => "0" + e['bar'] # => "1" + +==== Task: Retrieve the Value for an Attribute Name + +Use method +{Element#[]}[../../../../REXML/Element.html#method-i-5B-5D] +to retrieve the value for an attribute name: + + e = REXML::Element.new + e.add_attribute('attr', 'value') # => "value" + e['attr'] # => "value" + +==== Task: Retrieve the Attribute Value for a Name and Namespace + +Use method +{Element#attribute}[../../../../REXML/Element.html#method-i-attribute] +to retrieve the value for an attribute name: + + xml_string = "<root xmlns:a='a' a:x='a:x' x='x'/>" + d = REXML::Document.new(xml_string) + e = d.root + e.attribute("x") # => x='x' + e.attribute("x", "a") # => a:x='a:x' + +==== Task: Delete an Attribute + +Use method +{Element#delete_attribute}[../../../../REXML/Element.html#method-i-delete_attribute] +to remove an attribute: + + e = REXML::Element.new('foo') + e.add_attribute('bar', 'baz') + e.delete_attribute('bar') + e.delete_attribute('bar') + e['bar'] # => nil + +==== Task: Determine Whether the Element Has Attributes + +Use method +{Element#has_attributes?}[../../../../REXML/Element.html#method-i-has_attributes-3F] +to determine whether the element has attributes: + + e = REXML::Element.new('foo') + e.has_attributes? # => false + e.add_attribute('bar', 'baz') + e.has_attributes? # => true + +=== Children + +<em>Element Children</em> + +==== Task: Create and Add an Element + +Use method +{Element#add_element}[../../../../REXML/Element.html#method-i-add_element] +to create a new element and add it to this element: + + e0 = REXML::Element.new('foo') + e0.add_element('bar') + e0.children # => [<bar/>] + +==== Task: Add an Existing Element + +Use method +{Element#add_element}[../../../../REXML/Element.html#method-i-add_element] +to add an element to this element: + + e0 = REXML::Element.new('foo') + e1 = REXML::Element.new('bar') + e0.add_element(e1) + e0.children # => [<bar/>] + +==== Task: Create and Add an Element with Attributes + +Use method +{Element#add_element}[../../../../REXML/Element.html#method-i-add_element] +to create a new element with attributes, and add it to this element: + + e0 = REXML::Element.new('foo') + e0.add_element('bar', {'name' => 'value'}) + e0.children # => [<bar name='value'/>] + +==== Task: Add an Existing Element with Added Attributes + +Use method +{Element#add_element}[../../../../REXML/Element.html#method-i-add_element] +to add an element to this element: + + e0 = REXML::Element.new('foo') + e1 = REXML::Element.new('bar') + e0.add_element(e1, {'name' => 'value'}) + e0.children # => [<bar name='value'/>] + +==== Task: Delete a Specified Element + +Use method +{Element#delete_element}[../../../../REXML/Element.html#method-i-delete_element] +to remove a specified element from this element: + + e0 = REXML::Element.new('foo') + e1 = REXML::Element.new('bar') + e0.add_element(e1) + e0.children # => [<bar/>] + e0.delete_element(e1) + e0.children # => [] + +==== Task: Delete an Element by Index + +Use method +{Element#delete_element}[../../../../REXML/Element.html#method-i-delete_element] +to remove an element from this element by index: + + e0 = REXML::Element.new('foo') + e1 = REXML::Element.new('bar') + e0.add_element(e1) + e0.children # => [<bar/>] + e0.delete_element(1) + e0.children # => [] + +==== Task: Delete an Element by XPath + +Use method +{Element#delete_element}[../../../../REXML/Element.html#method-i-delete_element] +to remove an element from this element by XPath: + + e0 = REXML::Element.new('foo') + e1 = REXML::Element.new('bar') + e0.add_element(e1) + e0.children # => [<bar/>] + e0.delete_element('//bar/') + e0.children # => [] + +==== Task: Determine Whether Element Children + +Use method +{Element#has_elements?}[../../../../REXML/Element.html#method-i-has_elements-3F] +to determine whether the element has element children: + + e0 = REXML::Element.new('foo') + e0.has_elements? # => false + e0.add_element(REXML::Element.new('bar')) + e0.has_elements? # => true + +==== Task: Get Element Descendants by XPath + +Use method +{Element#get_elements}[../../../../REXML/Element.html#method-i-get_elements] +to fetch all element descendant children by XPath: + + xml_string = <<-EOT + <root> + <a level='1'> + <a level='2'/> + </a> + </root> + EOT + d = REXML::Document.new(xml_string) + d.root.get_elements('//a') # => [<a level='1'> ... </>, <a level='2'/>] + +==== Task: Get Next Element Sibling + +Use method +{Element#next_element}[../../../../REXML/Element.html#method-i-next_element] +to retrieve the next element sibling: + + d = REXML::Document.new '<a><b/>text<c/></a>' + d.root.elements['b'].next_element #-> <c/> + d.root.elements['c'].next_element #-> nil + +==== Task: Get Previous Element Sibling + +Use method +{Element#previous_element}[../../../../REXML/Element.html#method-i-previous_element] +to retrieve the previous element sibling: + + d = REXML::Document.new '<a><b/>text<c/></a>' + d.root.elements['c'].previous_element #-> <b/> + d.root.elements['b'].previous_element #-> nil + +<em>Text Children</em> + +==== Task: Add a Text Node + +Use method +{Element#add_text}[../../../../REXML/Element.html#method-i-add_text] +to add a text node to the element: + + d = REXML::Document.new('<a>foo<b/>bar</a>') + e = d.root + e.add_text(REXML::Text.new('baz')) + e.to_a # => ["foo", <b/>, "bar", "baz"] + e.add_text(REXML::Text.new('baz')) + e.to_a # => ["foo", <b/>, "bar", "baz", "baz"] + +==== Task: Replace the First Text Node + +Use method +{Element#text=}[../../../../REXML/Element.html#method-i-text-3D] +to replace the first text node in the element: + + d = REXML::Document.new('<root><a/>text<b/>more<c/></root>') + e = d.root + e.to_a # => [<a/>, "text", <b/>, "more", <c/>] + e.text = 'oops' + e.to_a # => [<a/>, "oops", <b/>, "more", <c/>] + +==== Task: Remove the First Text Node + +Use method +{Element#text=}[../../../../REXML/Element.html#method-i-text-3D] +to remove the first text node in the element: + + d = REXML::Document.new('<root><a/>text<b/>more<c/></root>') + e = d.root + e.to_a # => [<a/>, "text", <b/>, "more", <c/>] + e.text = nil + e.to_a # => [<a/>, <b/>, "more", <c/>] + +==== Task: Retrieve the First Text Node + +Use method +{Element#get_text}[../../../../REXML/Element.html#method-i-get_text] +to retrieve the first text node in the element: + + d = REXML::Document.new('<root><a/>text<b/>more<c/></root>') + e = d.root + e.to_a # => [<a/>, "text", <b/>, "more", <c/>] + e.get_text # => "text" + +==== Task: Retrieve a Specific Text Node + +Use method +{Element#get_text}[../../../../REXML/Element.html#method-i-get_text] +to retrieve the first text node in a specified element: + + d = REXML::Document.new "<root>some text <b>this is bold!</b> more text</root>" + e = d.root + e.get_text('//root') # => "some text " + e.get_text('//b') # => "this is bold!" + +==== Task: Determine Whether the Element has Text Nodes + +Use method +{Element#has_text?}[../../../../REXML/Element.html#method-i-has_text-3F] +to determine whethe the element has text: + + e = REXML::Element.new('foo') + e.has_text? # => false + e.add_text('bar') + e.has_text? # => true + +<em>Other Children</em> + +==== Task: Get the Child at a Given Index + +Use method +{Element#[]}[../../../../REXML/Element.html#method-i-5B-5D] +to retrieve the child at a given index: + + d = REXML::Document.new '><root><a/>text<b/>more<c/></root>' + e = d.root + e[0] # => <a/> + e[1] # => "text" + e[2] # => <b/> + +==== Task: Get All CDATA Children + +Use method +{Element#cdatas}[../../../../REXML/Element.html#method-i-cdatas] +to retrieve all CDATA children: + + xml_string = <<-EOT + <root> + <![CDATA[foo]]> + <![CDATA[bar]]> + </root> + EOT + d = REXML::Document.new(xml_string) + d.root.cdatas # => ["foo", "bar"] + +==== Task: Get All Comment Children + +Use method +{Element#comments}[../../../../REXML/Element.html#method-i-comments] +to retrieve all comment children: + + xml_string = <<-EOT + <root> + <!--foo--> + <!--bar--> + </root> + EOT + d = REXML::Document.new(xml_string) + d.root.comments.map {|comment| comment.to_s } # => ["foo", "bar"] + +==== Task: Get All Processing Instruction Children + +Use method +{Element#instructions}[../../../../REXML/Element.html#method-i-instructions] +to retrieve all processing instruction children: + + xml_string = <<-EOT + <root> + <?target0 foo?> + <?target1 bar?> + </root> + EOT + d = REXML::Document.new(xml_string) + instructions = d.root.instructions.map {|instruction| instruction.to_s } + instructions # => ["<?target0 foo?>", "<?target1 bar?>"] + +==== Task: Get All Text Children + +Use method +{Element#texts}[../../../../REXML/Element.html#method-i-texts] +to retrieve all text children: + + xml_string = '<root><a/>text<b/>more<c/></root>' + d = REXML::Document.new(xml_string) + d.root.texts # => ["text", "more"] + +=== Namespaces + +==== Task: Add a Namespace + +Use method +{Element#add_namespace}[../../../../REXML/Element.html#method-i-add_namespace] +to add a namespace to the element: + + e = REXML::Element.new('foo') + e.add_namespace('bar') + e.namespaces # => {"xmlns"=>"bar"} + +==== Task: Delete the Default Namespace + +Use method +{Element#delete_namespace}[../../../../REXML/Element.html#method-i-delete_namespace] +to remove the default namespace from the element: + + d = REXML::Document.new "<a xmlns:foo='bar' xmlns='twiddle'/>" + d.to_s # => "<a xmlns:foo='bar' xmlns='twiddle'/>" + d.root.delete_namespace # => <a xmlns:foo='bar'/> + d.to_s # => "<a xmlns:foo='bar'/>" + +==== Task: Delete a Specific Namespace + +Use method +{Element#delete_namespace}[../../../../REXML/Element.html#method-i-delete_namespace] +to remove a specific namespace from the element: + + d = REXML::Document.new "<a xmlns:foo='bar' xmlns='twiddle'/>" + d.to_s # => "<a xmlns:foo='bar' xmlns='twiddle'/>" + d.root.delete_namespace # => <a xmlns:foo='bar'/> + d.to_s # => "<a xmlns:foo='bar'/>" + d.root.delete_namespace('foo') + d.to_s # => "<a/>" + +==== Task: Get a Namespace URI + +Use method +{Element#namespace}[../../../../REXML/Element.html#method-i-namespace] +to retrieve a speficic namespace URI for the element: + + xml_string = <<-EOT + <root> + <a xmlns='1' xmlns:y='2'> + <b/> + <c xmlns:z='3'/> + </a> + </root> + EOT + d = REXML::Document.new(xml_string) + b = d.elements['//b'] + b.namespace # => "1" + b.namespace('y') # => "2" + +==== Task: Retrieve Namespaces + +Use method +{Element#namespaces}[../../../../REXML/Element.html#method-i-namespaces] +to retrieve all namespaces for the element: + + xml_string = '<a xmlns="foo" xmlns:x="bar" xmlns:y="twee" z="glorp"/>' + d = REXML::Document.new(xml_string) + d.root.attributes.namespaces # => {"xmlns"=>"foo", "x"=>"bar", "y"=>"twee"} + +==== Task: Retrieve Namespace Prefixes + +Use method +{Element#prefixes}[../../../../REXML/Element.html#method-i-prefixes] +to retrieve all prefixes (namespace names) for the element: + + xml_string = <<-EOT + <root> + <a xmlns:x='1' xmlns:y='2'> + <b/> + <c xmlns:z='3'/> + </a> + </root> + EOT + d = REXML::Document.new(xml_string, {compress_whitespace: :all}) + d.elements['//a'].prefixes # => ["x", "y"] + d.elements['//b'].prefixes # => ["x", "y"] + d.elements['//c'].prefixes # => ["x", "y", "z"] + +=== Iteration + +==== Task: Iterate Over Elements + +Use method +{Element#each_element}[../../../../REXML/Element.html#method-i-each_element] +to iterate over element children: + + d = REXML::Document.new '<a><b>b</b><c>b</c><d>d</d><e/></a>' + d.root.each_element {|e| p e } + +Output: + + <b> ... </> + <c> ... </> + <d> ... </> + <e/> + +==== Task: Iterate Over Elements Having a Specified Attribute + +Use method +{Element#each_element_with_attribute}[../../../../REXML/Element.html#method-i-each_element_with_attribute] +to iterate over element children that have a specified attribute: + + d = REXML::Document.new '<a><b id="1"/><c id="2"/><d id="1"/><e/></a>' + a = d.root + a.each_element_with_attribute('id') {|e| p e } + +Output: + + <b id='1'/> + <c id='2'/> + <d id='1'/> + +==== Task: Iterate Over Elements Having a Specified Attribute and Value + +Use method +{Element#each_element_with_attribute}[../../../../REXML/Element.html#method-i-each_element_with_attribute] +to iterate over element children that have a specified attribute and value: + + d = REXML::Document.new '<a><b id="1"/><c id="2"/><d id="1"/><e/></a>' + a = d.root + a.each_element_with_attribute('id', '1') {|e| p e } + +Output: + + <b id='1'/> + <d id='1'/> + +==== Task: Iterate Over Elements Having Specified Text + +Use method +{Element#each_element_with_text}[../../../../REXML/Element.html#method-i-each_element_with_text] +to iterate over element children that have specified text: + + +=== Context + +#whitespace +#ignore_whitespace_nodes +#raw + +=== Other Getters + +#document +#root +#root_node +#node_type +#xpath +#inspect diff --git a/doc/rexml/tasks/rdoc/node.rdoc b/doc/rexml/tasks/rdoc/node.rdoc new file mode 100644 index 00000000..d5d2e12a --- /dev/null +++ b/doc/rexml/tasks/rdoc/node.rdoc @@ -0,0 +1,97 @@ +== Module Node + +:include: ../tocs/node_toc.rdoc + +=== Siblings + +==== Task: Find Previous Sibling + +Use method +{Node.previous_sibling_node}[../../../../REXML/Node.html#method-i-previous_sibling] +to retrieve the previous sibling: + + d = REXML::Document.new('<root><a/><b/><c/></root>') + b = d.root[1] # => <b/> + b.previous_sibling_node # => <a/> + +==== Task: Find Next Sibling + +Use method +{Node.next_sibling_node}[../../../../REXML/Node.html#method-i-next_sibling] +to retrieve the next sibling: + + d = REXML::Document.new('<root><a/><b/><c/></root>') + b = d.root[1] # => <b/> + b.next_sibling_node # => <c/> + +=== Position + +==== Task: Find Own Index Among Siblings + +Use method +{Node.index_in_parent}[../../../../REXML/Node.html#method-i-index_in_parent] +to retrieve the 1-based index of this node among its siblings: + + d = REXML::Document.new('<root><a/><b/><c/></root>') + b = d.root[1] # => <b/> + b.index_in_parent # => 2 + +=== Recursive Traversal + +==== Task: Traverse Each Recursively + +Use method +{Node.each_recursive}[../../../../REXML/Node.html#method-i-each_recursive] +to traverse a tree of nodes recursively: + + xml_string = '<root><a><b><c></c></b><b><c></c></b></a></root>' + d = REXML::Document.new(xml_string) + d.root.each_recursive {|node| p node } + +Output: + + <a> ... </> + <b> ... </> + <c/> + <b> ... </> + <c/> + +=== Recursive Search + +==== Task: Traverse Each Recursively + +Use method +{Node.find_first_recursive}[../../../../REXML/Node.html#method-i-find_first_recursive] +to search a tree of nodes recursively: + + xml_string = '<root><a><b><c></c></b><b><c></c></b></a></root>' + d = REXML::Document.new(xml_string) + d.root.find_first_recursive {|node| node.name == 'c' } # => <c/> + +=== Representation + +==== Task: Represent a String + +Use method {Node.to_s}[../../../../REXML/Node.html#method-i-to_s] +to represent the node as a string: + + xml_string = '<root><a><b><c></c></b><b><c></c></b></a></root>' + d = REXML::Document.new(xml_string) + d.root.to_s # => "<root><a><b><c/></b><b><c/></b></a></root>" + +=== Parent? + +==== Task: Determine Whether the Node is a Parent + +Use method {Node.parent?}[../../../../REXML/Node.html#method-i-parent-3F] +to determine whether the node is a parent; +class Text derives from Node: + + d = REXML::Document.new('<root><a/>text<b/>more<c/></root>') + t = d.root[1] # => "text" + t.parent? # => false + +Class Parent also derives from Node, but overrides this method: + + p = REXML::Parent.new + p.parent? # => true diff --git a/doc/rexml/tasks/rdoc/parent.rdoc b/doc/rexml/tasks/rdoc/parent.rdoc new file mode 100644 index 00000000..54f1dbe3 --- /dev/null +++ b/doc/rexml/tasks/rdoc/parent.rdoc @@ -0,0 +1,267 @@ +== Class Parent + +Class Parent has methods from its superclasses and included modules; +see: + +- {Tasks for Child}[child_rdoc.html]. +- {Tasks for Node}[node_rdoc.html]. +- {Module Enumerable}[https://docs.ruby-lang.org/en/master/Enumerable.html]. + +:include: ../tocs/parent_toc.rdoc + +=== Queries + +==== Task: Get the Count of Children + +Use method {Parent#size}[../../../../REXML/Parent.html#method-i-size] +(or its alias +length+) to get the count of the parent's children: + + p = REXML::Parent.new + p.size # => 0 + xml_string = '<root><a/><b/><c/></root>' + d = REXML::Document.new(xml_string) + d.root.size # => 3 + +==== Task: Get the Child at a Given Index + +Use method {Parent#[]}[../../../../REXML/Parent.html#method-i-5B-5D] +to get the child at a given index: + + xml_string = '<root><a/><b/><c/></root>' + d = REXML::Document.new(xml_string) + d.root[1] # => <b/> + d.root[-1] # => <c/> + d.root[50] # => nil + +==== Task: Get the Index of a Given Child + +Use method {Parent#index}[../../../../REXML/Parent.html#method-i-index] +to get the index (0-based offset) of a child: + + d = REXML::Document.new('<root></root>') + root = d.root + e0 = REXML::Element.new('foo') + e1 = REXML::Element.new('bar') + root.add(e0) # => <foo/> + root.add(e1) # => <bar/> + root.add(e0) # => <foo/> + root.add(e1) # => <bar/> + root.index(e0) # => 0 + root.index(e1) # => 1 + +==== Task: Get the Children + +Use method {Parent#children}[../../../../REXML/Parent.html#method-i-children] +(or its alias +to_a+) to get the parent's children: + + xml_string = '<root><a/><b/><c/></root>' + d = REXML::Document.new(xml_string) + d.root.children # => [<a/>, <b/>, <c/>] + +==== Task: Determine Whether the Node is a Parent + +Use method {Parent#parent?}[../../../../REXML/Parent.html#method-i-parent-3F] +to determine whether the node is a parent; +class Text derives from Node: + + d = REXML::Document.new('<root><a/>text<b/>more<c/></root>') + t = d.root[1] # => "text" + t.parent? # => false + +Class Parent also derives from Node, but overrides this method: + + p = REXML::Parent.new + p.parent? # => true + +=== Additions + +==== Task: Add a Child at the Beginning + +Use method {Parent#unshift}[../../../../REXML/Parent.html#method-i-unshift] +to add a child as at the beginning of the children: + + xml_string = '<root><a/><b/><c/></root>' + d = REXML::Document.new(xml_string) + d.root.children # => [<a/>, <b/>, <c/>] + d.root.unshift REXML::Element.new('d') + d.root.children # => [<d/>, <a/>, <b/>, <c/>] + +==== Task: Add a Child at the End + +Use method {Parent#<<}[../../../../REXML/Parent.html#method-i-3C-3C] +(or an alias +push+ or +add+) to add a child as at the end of the children: + + xml_string = '<root><a/><b/><c/></root>' + d = REXML::Document.new(xml_string) + d.root.children # => [<a/>, <b/>, <c/>] + d.root << REXML::Element.new('d') + d.root.children # => [<a/>, <b/>, <c/>, <d/>] + +==== Task: Replace a Child with Another Child + +Use method {Parent#replace}[../../../../REXML/Parent.html#method-i-replace] + + xml_string = '<root><a/><b/><c/></root>' + d = REXML::Document.new(xml_string) + d.root.children # => [<a/>, <b/>, <c/>] + b = d.root[1] # => <b/> + d.replace_child(b, REXML::Element.new('d')) + d.root.children # => [<a/>, <c/>] + +==== Task: Replace Multiple Children with Another Child + +Use method {Parent#[]=}[../../../../REXML/Parent.html#method-i-parent-5B-5D-3D] +to replace multiple consecutive children with another child: + + xml_string = '<root><a/><b/><c/><d/></root>' + d = REXML::Document.new(xml_string) + d.root.children # => [<a/>, <b/>, <c/>, <d/>] + d.root[1, 2] = REXML::Element.new('x') + d.root.children # => [<a/>, <x/>, <d/>] + d.root[1, 5] = REXML::Element.new('x') + d.root.children # => [<a/>, <x/>] # BUG? + +==== Task: Insert Child Before a Given Child + +Use method {Parent#insert_before}[../../../../REXML/Parent.html#method-i-insert_before] +to insert a child immediately before a given child: + + xml_string = '<root><a/><b/><c/></root>' + d = REXML::Document.new(xml_string) + d.root.children # => [<a/>, <b/>, <c/>] + b = d.root[1] # => <b/> + x = REXML::Element.new('x') + d.root.insert_before(b, x) + d.root.children # => [<a/>, <x/>, <b/>, <c/>] + +==== Task: Insert Child After a Given Child + +Use method {Parent#insert_after}[../../../../REXML/Parent.html#method-i-insert_after] +to insert a child immediately after a given child: + + xml_string = '<root><a/><b/><c/></root>' + d = REXML::Document.new(xml_string) + d.root.children # => [<a/>, <b/>, <c/>] + b = d.root[1] # => <b/> + x = REXML::Element.new('x') + d.root.insert_after(b, x) + d.root.children # => [<a/>, <b/>, <x/>, <c/>] + +=== Deletions + +==== Task: Remove a Given Child + +Use method {Parent#delete}[../../../../REXML/Parent.html#method-i-delete] +to remove all occurrences of a given child: + + d = REXML::Document.new('<root></root>') + a = REXML::Element.new('a') + b = REXML::Element.new('b') + d.root.add(a) + d.root.add(b) + d.root.add(a) + d.root.add(b) + d.root.children # => [<a/>, <b/>, <a/>, <b/>] + d.root.delete(b) + d.root.children # => [<a/>, <a/>] + +==== Task: Remove the Child at a Specified Offset + +Use method {Parent#delete_at}[../../../../REXML/Parent.html#method-i-delete_at] +to remove the child at a specified offset: + + d = REXML::Document.new('<root></root>') + a = REXML::Element.new('a') + b = REXML::Element.new('b') + d.root.add(a) + d.root.add(b) + d.root.add(a) + d.root.add(b) + d.root.children # => [<a/>, <b/>, <a/>, <b/>] + d.root.delete_at(2) + d.root.children # => [<a/>, <b/>, <b/>] + +==== Task: Remove Children That Meet Specified Criteria + +Use method {Parent#delete_if}[../../../../REXML/Parent.html#method-i-delete_if] +to remove children that meet criteria specified in the given block: + + d = REXML::Document.new('<root></root>') + d.root.add(REXML::Element.new('x')) + d.root.add(REXML::Element.new('xx')) + d.root.add(REXML::Element.new('xxx')) + d.root.add(REXML::Element.new('xxxx')) + d.root.children # => [<x/>, <xx/>, <xxx/>, <xxxx/>] + d.root.delete_if {|child| child.name.size.odd? } + d.root.children # => [<xx/>, <xxxx/>] + +=== Iterations + +==== Task: Iterate Over Children + +Use method {Parent#each_child}[../../../../REXML/Parent.html#method-i-each_child] +(or its alias +each+) to iterate over all children: + + xml_string = '<root><a/><b/><c/></root>' + d = REXML::Document.new(xml_string) + d.root.children # => [<a/>, <b/>, <c/>] + d.root.each_child {|child| p child } + +Output: + + <a/> + <b/> + <c/> + +==== Task: Iterate Over Child Indexes + +Use method {Parent#each_index}[../../../../REXML/Parent.html#method-i-each_index] +to iterate over all child indexes: + + xml_string = '<root><a/><b/><c/></root>' + d = REXML::Document.new(xml_string) + d.root.children # => [<a/>, <b/>, <c/>] + d.root.each_index {|child| p child } + +Output: + + 0 + 1 + 2 + +=== Clones + +==== Task: Clone Deeply + +Use method {Parent#deep_clone}[../../../../REXML/Parent.html#method-i-deep_clone] +to clone deeply; that is, to clone every nested node that is a Parent object: + + xml_string = <<-EOT + <?xml version="1.0" encoding="UTF-8"?> + <bookstore> + <book category="cooking"> + <title lang="en">Everyday Italian + Giada De Laurentiis + 2005 + 30.00 + + + Harry Potter + J K. Rowling + 2005 + 29.99 + + + Learning XML + Erik T. Ray + 2003 + 39.95 + + + EOT + d = REXML::Document.new(xml_string) + root = d.root + shallow = root.clone + deep = root.deep_clone + shallow.to_s.size # => 12 + deep.to_s.size # => 590 diff --git a/doc/rexml/tasks/tocs/child_toc.rdoc b/doc/rexml/tasks/tocs/child_toc.rdoc new file mode 100644 index 00000000..a2083a09 --- /dev/null +++ b/doc/rexml/tasks/tocs/child_toc.rdoc @@ -0,0 +1,12 @@ +Tasks on this page: + +- {Relationships}[#label-Relationships] + - {Task: Set the Parent}[#label-Task-3A+Set+the+Parent] + - {Task: Insert Previous Sibling}[#label-Task-3A+Insert+Previous+Sibling] + - {Task: Insert Next Sibling}[#label-Task-3A+Insert+Next+Sibling] +- {Removal or Replacement}[#label-Removal+or+Replacement] + - {Task: Remove Child from Parent}[#label-Task-3A+Remove+Child+from+Parent] + - {Task: Replace Child}[#label-Task-3A+Replace+Child] +- {Document}[#label-Document] + - {Task: Get the Document}[#label-Task-3A+Get+the+Document] + diff --git a/doc/rexml/tasks/tocs/document_toc.rdoc b/doc/rexml/tasks/tocs/document_toc.rdoc new file mode 100644 index 00000000..5db055ff --- /dev/null +++ b/doc/rexml/tasks/tocs/document_toc.rdoc @@ -0,0 +1,30 @@ +Tasks on this page: + +- {New Document}[#label-New+Document] + - {Task: Create an Empty Document}[#label-Task-3A+Create+an+Empty+Document] + - {Task: Parse a String into a New Document}[#label-Task-3A+Parse+a+String+into+a+New+Document] + - {Task: Parse an IO Stream into a New Document}[#label-Task-3A+Parse+an+IO+Stream+into+a+New+Document] + - {Task: Create a Document from an Existing Document}[#label-Task-3A+Create+a+Document+from+an+Existing+Document] + - {Task: Clone a Document}[#label-Task-3A+Clone+a+Document] +- {Document Type}[#label-Document+Type] + - {Task: Get the Document Type}[#label-Task-3A+Get+the+Document+Type] + - {Task: Set the Document Type}[#label-Task-3A+Set+the+Document+Type] +- {XML Declaration}[#label-XML+Declaration] + - {Task: Get the XML Declaration}[#label-Task-3A+Get+the+XML+Declaration] + - {Task: Set the XML Declaration}[#label-Task-3A+Set+the+XML+Declaration] +- {Children}[#label-Children] + - {Task: Add an Element Child}[#label-Task-3A+Add+an+Element+Child] + - {Task: Add a Non-Element Child}[#label-Task-3A+Add+a+Non-Element+Child] +- {Writing}[#label-Writing] + - {Task: Write to $stdout}[#label-Task-3A+Write+to+-24stdout] + - {Task: Write to IO Stream}[#label-Task-3A+Write+to+IO+Stream] + - {Task: Write with No Indentation}[#label-Task-3A+Write+with+No+Indentation] + - {Task: Write with Specified Indentation}[#label-Task-3A+Write+with+Specified+Indentation] +- {Querying}[#label-Querying] + - {Task: Get the Document}[#label-Task-3A+Get+the+Document] + - {Task: Get the Encoding}[#label-Task-3A+Get+the+Encoding] + - {Task: Get the Node Type}[#label-Task-3A+Get+the+Node+Type] + - {Task: Get the Root Element}[#label-Task-3A+Get+the+Root+Element] + - {Task: Determine Whether Stand-Alone}[#label-Task-3A+Determine+Whether+Stand-Alone] + - {Task: Get the Version}[#label-Task-3A+Get+the+Version] + diff --git a/doc/rexml/tasks/tocs/element_toc.rdoc b/doc/rexml/tasks/tocs/element_toc.rdoc new file mode 100644 index 00000000..60a504a5 --- /dev/null +++ b/doc/rexml/tasks/tocs/element_toc.rdoc @@ -0,0 +1,55 @@ +Tasks on this page: + +- {New Element}[#label-New+Element] + - {Task: Create a Default Element}[#label-Task-3A+Create+a+Default+Element] + - {Task: Create a Named Element}[#label-Task-3A+Create+a+Named+Element] + - {Task: Create an Element with Name and Parent}[#label-Task-3A+Create+an+Element+with+Name+and+Parent] + - {Task: Create an Element with Name, Parent, and Context}[#label-Task-3A+Create+an+Element+with+Name-2C+Parent-2C+and+Context] + - {Task: Create a Shallow Clone}[#label-Task-3A+Create+a+Shallow+Clone] +- {Attributes}[#label-Attributes] + - {Task: Create and Add an Attribute}[#label-Task-3A+Create+and+Add+an+Attribute] + - {Task: Add an Existing Attribute}[#label-Task-3A+Add+an+Existing+Attribute] + - {Task: Add Multiple Attributes from a Hash}[#label-Task-3A+Add+Multiple+Attributes+from+a+Hash] + - {Task: Add Multiple Attributes from an Array}[#label-Task-3A+Add+Multiple+Attributes+from+an+Array] + - {Task: Retrieve the Value for an Attribute Name}[#label-Task-3A+Retrieve+the+Value+for+an+Attribute+Name] + - {Task: Retrieve the Attribute Value for a Name and Namespace}[#label-Task-3A+Retrieve+the+Attribute+Value+for+a+Name+and+Namespace] + - {Task: Delete an Attribute}[#label-Task-3A+Delete+an+Attribute] + - {Task: Determine Whether the Element Has Attributes}[#label-Task-3A+Determine+Whether+the+Element+Has+Attributes] +- {Children}[#label-Children] + - {Task: Create and Add an Element}[#label-Task-3A+Create+and+Add+an+Element] + - {Task: Add an Existing Element}[#label-Task-3A+Add+an+Existing+Element] + - {Task: Create and Add an Element with Attributes}[#label-Task-3A+Create+and+Add+an+Element+with+Attributes] + - {Task: Add an Existing Element with Added Attributes}[#label-Task-3A+Add+an+Existing+Element+with+Added+Attributes] + - {Task: Delete a Specified Element}[#label-Task-3A+Delete+a+Specified+Element] + - {Task: Delete an Element by Index}[#label-Task-3A+Delete+an+Element+by+Index] + - {Task: Delete an Element by XPath}[#label-Task-3A+Delete+an+Element+by+XPath] + - {Task: Determine Whether Element Children}[#label-Task-3A+Determine+Whether+Element+Children] + - {Task: Get Element Descendants by XPath}[#label-Task-3A+Get+Element+Descendants+by+XPath] + - {Task: Get Next Element Sibling}[#label-Task-3A+Get+Next+Element+Sibling] + - {Task: Get Previous Element Sibling}[#label-Task-3A+Get+Previous+Element+Sibling] + - {Task: Add a Text Node}[#label-Task-3A+Add+a+Text+Node] + - {Task: Replace the First Text Node}[#label-Task-3A+Replace+the+First+Text+Node] + - {Task: Remove the First Text Node}[#label-Task-3A+Remove+the+First+Text+Node] + - {Task: Retrieve the First Text Node}[#label-Task-3A+Retrieve+the+First+Text+Node] + - {Task: Retrieve a Specific Text Node}[#label-Task-3A+Retrieve+a+Specific+Text+Node] + - {Task: Determine Whether the Element has Text Nodes}[#label-Task-3A+Determine+Whether+the+Element+has+Text+Nodes] + - {Task: Get the Child at a Given Index}[#label-Task-3A+Get+the+Child+at+a+Given+Index] + - {Task: Get All CDATA Children}[#label-Task-3A+Get+All+CDATA+Children] + - {Task: Get All Comment Children}[#label-Task-3A+Get+All+Comment+Children] + - {Task: Get All Processing Instruction Children}[#label-Task-3A+Get+All+Processing+Instruction+Children] + - {Task: Get All Text Children}[#label-Task-3A+Get+All+Text+Children] +- {Namespaces}[#label-Namespaces] + - {Task: Add a Namespace}[#label-Task-3A+Add+a+Namespace] + - {Task: Delete the Default Namespace}[#label-Task-3A+Delete+the+Default+Namespace] + - {Task: Delete a Specific Namespace}[#label-Task-3A+Delete+a+Specific+Namespace] + - {Task: Get a Namespace URI}[#label-Task-3A+Get+a+Namespace+URI] + - {Task: Retrieve Namespaces}[#label-Task-3A+Retrieve+Namespaces] + - {Task: Retrieve Namespace Prefixes}[#label-Task-3A+Retrieve+Namespace+Prefixes] +- {Iteration}[#label-Iteration] + - {Task: Iterate Over Elements}[#label-Task-3A+Iterate+Over+Elements] + - {Task: Iterate Over Elements Having a Specified Attribute}[#label-Task-3A+Iterate+Over+Elements+Having+a+Specified+Attribute] + - {Task: Iterate Over Elements Having a Specified Attribute and Value}[#label-Task-3A+Iterate+Over+Elements+Having+a+Specified+Attribute+and+Value] + - {Task: Iterate Over Elements Having Specified Text}[#label-Task-3A+Iterate+Over+Elements+Having+Specified+Text] +- {Context}[#label-Context] +- {Other Getters}[#label-Other+Getters] + diff --git a/doc/rexml/tasks/tocs/master_toc.rdoc b/doc/rexml/tasks/tocs/master_toc.rdoc new file mode 100644 index 00000000..ccc2f401 --- /dev/null +++ b/doc/rexml/tasks/tocs/master_toc.rdoc @@ -0,0 +1,135 @@ +== Table of Contents + +=== {Child}[../../tasks/rdoc/child_rdoc.html] +- {Relationships}[../../tasks/rdoc/child_rdoc.html#label-Relationships] + - {Task: Set the Parent}[../../tasks/rdoc/child_rdoc.html#label-Task-3A+Set+the+Parent] + - {Task: Insert Previous Sibling}[../../tasks/rdoc/child_rdoc.html#label-Task-3A+Insert+Previous+Sibling] + - {Task: Insert Next Sibling}[../../tasks/rdoc/child_rdoc.html#label-Task-3A+Insert+Next+Sibling] +- {Removal or Replacement}[../../tasks/rdoc/child_rdoc.html#label-Removal+or+Replacement] + - {Task: Remove Child from Parent}[../../tasks/rdoc/child_rdoc.html#label-Task-3A+Remove+Child+from+Parent] + - {Task: Replace Child}[../../tasks/rdoc/child_rdoc.html#label-Task-3A+Replace+Child] +- {Document}[../../tasks/rdoc/child_rdoc.html#label-Document] + - {Task: Get the Document}[../../tasks/rdoc/child_rdoc.html#label-Task-3A+Get+the+Document] + +=== {Document}[../../tasks/rdoc/document_rdoc.html] +- {New Document}[../../tasks/rdoc/document_rdoc.html#label-New+Document] + - {Task: Create an Empty Document}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Create+an+Empty+Document] + - {Task: Parse a String into a New Document}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Parse+a+String+into+a+New+Document] + - {Task: Parse an IO Stream into a New Document}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Parse+an+IO+Stream+into+a+New+Document] + - {Task: Create a Document from an Existing Document}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Create+a+Document+from+an+Existing+Document] + - {Task: Clone a Document}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Clone+a+Document] +- {Document Type}[../../tasks/rdoc/document_rdoc.html#label-Document+Type] + - {Task: Get the Document Type}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Get+the+Document+Type] + - {Task: Set the Document Type}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Set+the+Document+Type] +- {XML Declaration}[../../tasks/rdoc/document_rdoc.html#label-XML+Declaration] + - {Task: Get the XML Declaration}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Get+the+XML+Declaration] + - {Task: Set the XML Declaration}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Set+the+XML+Declaration] +- {Children}[../../tasks/rdoc/document_rdoc.html#label-Children] + - {Task: Add an Element Child}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Add+an+Element+Child] + - {Task: Add a Non-Element Child}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Add+a+Non-Element+Child] +- {Writing}[../../tasks/rdoc/document_rdoc.html#label-Writing] + - {Task: Write to $stdout}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Write+to+-24stdout] + - {Task: Write to IO Stream}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Write+to+IO+Stream] + - {Task: Write with No Indentation}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Write+with+No+Indentation] + - {Task: Write with Specified Indentation}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Write+with+Specified+Indentation] +- {Querying}[../../tasks/rdoc/document_rdoc.html#label-Querying] + - {Task: Get the Document}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Get+the+Document] + - {Task: Get the Encoding}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Get+the+Encoding] + - {Task: Get the Node Type}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Get+the+Node+Type] + - {Task: Get the Root Element}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Get+the+Root+Element] + - {Task: Determine Whether Stand-Alone}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Determine+Whether+Stand-Alone] + - {Task: Get the Version}[../../tasks/rdoc/document_rdoc.html#label-Task-3A+Get+the+Version] + +=== {Element}[../../tasks/rdoc/element_rdoc.html] +- {New Element}[../../tasks/rdoc/element_rdoc.html#label-New+Element] + - {Task: Create a Default Element}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Create+a+Default+Element] + - {Task: Create a Named Element}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Create+a+Named+Element] + - {Task: Create an Element with Name and Parent}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Create+an+Element+with+Name+and+Parent] + - {Task: Create an Element with Name, Parent, and Context}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Create+an+Element+with+Name-2C+Parent-2C+and+Context] + - {Task: Create a Shallow Clone}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Create+a+Shallow+Clone] +- {Attributes}[../../tasks/rdoc/element_rdoc.html#label-Attributes] + - {Task: Create and Add an Attribute}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Create+and+Add+an+Attribute] + - {Task: Add an Existing Attribute}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Add+an+Existing+Attribute] + - {Task: Add Multiple Attributes from a Hash}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Add+Multiple+Attributes+from+a+Hash] + - {Task: Add Multiple Attributes from an Array}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Add+Multiple+Attributes+from+an+Array] + - {Task: Retrieve the Value for an Attribute Name}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Retrieve+the+Value+for+an+Attribute+Name] + - {Task: Retrieve the Attribute Value for a Name and Namespace}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Retrieve+the+Attribute+Value+for+a+Name+and+Namespace] + - {Task: Delete an Attribute}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Delete+an+Attribute] + - {Task: Determine Whether the Element Has Attributes}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Determine+Whether+the+Element+Has+Attributes] +- {Children}[../../tasks/rdoc/element_rdoc.html#label-Children] + - {Task: Create and Add an Element}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Create+and+Add+an+Element] + - {Task: Add an Existing Element}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Add+an+Existing+Element] + - {Task: Create and Add an Element with Attributes}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Create+and+Add+an+Element+with+Attributes] + - {Task: Add an Existing Element with Added Attributes}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Add+an+Existing+Element+with+Added+Attributes] + - {Task: Delete a Specified Element}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Delete+a+Specified+Element] + - {Task: Delete an Element by Index}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Delete+an+Element+by+Index] + - {Task: Delete an Element by XPath}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Delete+an+Element+by+XPath] + - {Task: Determine Whether Element Children}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Determine+Whether+Element+Children] + - {Task: Get Element Descendants by XPath}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Get+Element+Descendants+by+XPath] + - {Task: Get Next Element Sibling}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Get+Next+Element+Sibling] + - {Task: Get Previous Element Sibling}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Get+Previous+Element+Sibling] + - {Task: Add a Text Node}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Add+a+Text+Node] + - {Task: Replace the First Text Node}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Replace+the+First+Text+Node] + - {Task: Remove the First Text Node}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Remove+the+First+Text+Node] + - {Task: Retrieve the First Text Node}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Retrieve+the+First+Text+Node] + - {Task: Retrieve a Specific Text Node}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Retrieve+a+Specific+Text+Node] + - {Task: Determine Whether the Element has Text Nodes}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Determine+Whether+the+Element+has+Text+Nodes] + - {Task: Get the Child at a Given Index}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Get+the+Child+at+a+Given+Index] + - {Task: Get All CDATA Children}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Get+All+CDATA+Children] + - {Task: Get All Comment Children}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Get+All+Comment+Children] + - {Task: Get All Processing Instruction Children}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Get+All+Processing+Instruction+Children] + - {Task: Get All Text Children}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Get+All+Text+Children] +- {Namespaces}[../../tasks/rdoc/element_rdoc.html#label-Namespaces] + - {Task: Add a Namespace}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Add+a+Namespace] + - {Task: Delete the Default Namespace}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Delete+the+Default+Namespace] + - {Task: Delete a Specific Namespace}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Delete+a+Specific+Namespace] + - {Task: Get a Namespace URI}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Get+a+Namespace+URI] + - {Task: Retrieve Namespaces}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Retrieve+Namespaces] + - {Task: Retrieve Namespace Prefixes}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Retrieve+Namespace+Prefixes] +- {Iteration}[../../tasks/rdoc/element_rdoc.html#label-Iteration] + - {Task: Iterate Over Elements}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Iterate+Over+Elements] + - {Task: Iterate Over Elements Having a Specified Attribute}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Iterate+Over+Elements+Having+a+Specified+Attribute] + - {Task: Iterate Over Elements Having a Specified Attribute and Value}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Iterate+Over+Elements+Having+a+Specified+Attribute+and+Value] + - {Task: Iterate Over Elements Having Specified Text}[../../tasks/rdoc/element_rdoc.html#label-Task-3A+Iterate+Over+Elements+Having+Specified+Text] +- {Context}[../../tasks/rdoc/element_rdoc.html#label-Context] +- {Other Getters}[../../tasks/rdoc/element_rdoc.html#label-Other+Getters] + +=== {Node}[../../tasks/rdoc/node_rdoc.html] +- {Siblings}[../../tasks/rdoc/node_rdoc.html#label-Siblings] + - {Task: Find Previous Sibling}[../../tasks/rdoc/node_rdoc.html#label-Task-3A+Find+Previous+Sibling] + - {Task: Find Next Sibling}[../../tasks/rdoc/node_rdoc.html#label-Task-3A+Find+Next+Sibling] +- {Position}[../../tasks/rdoc/node_rdoc.html#label-Position] + - {Task: Find Own Index Among Siblings}[../../tasks/rdoc/node_rdoc.html#label-Task-3A+Find+Own+Index+Among+Siblings] +- {Recursive Traversal}[../../tasks/rdoc/node_rdoc.html#label-Recursive+Traversal] + - {Task: Traverse Each Recursively}[../../tasks/rdoc/node_rdoc.html#label-Task-3A+Traverse+Each+Recursively] +- {Recursive Search}[../../tasks/rdoc/node_rdoc.html#label-Recursive+Search] + - {Task: Traverse Each Recursively}[../../tasks/rdoc/node_rdoc.html#label-Task-3A+Traverse+Each+Recursively] +- {Representation}[../../tasks/rdoc/node_rdoc.html#label-Representation] + - {Task: Represent a String}[../../tasks/rdoc/node_rdoc.html#label-Task-3A+Represent+a+String] +- {Parent?}[../../tasks/rdoc/node_rdoc.html#label-Parent-3F] + - {Task: Determine Whether the Node is a Parent}[../../tasks/rdoc/node_rdoc.html#label-Task-3A+Determine+Whether+the+Node+is+a+Parent] + +=== {Parent}[../../tasks/rdoc/parent_rdoc.html] +- {Queries}[../../tasks/rdoc/parent_rdoc.html#label-Queries] + - {Task: Get the Count of Children}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Get+the+Count+of+Children] + - {Task: Get the Child at a Given Index}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Get+the+Child+at+a+Given+Index] + - {Task: Get the Index of a Given Child}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Get+the+Index+of+a+Given+Child] + - {Task: Get the Children}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Get+the+Children] + - {Task: Determine Whether the Node is a Parent}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Determine+Whether+the+Node+is+a+Parent] +- {Additions}[../../tasks/rdoc/parent_rdoc.html#label-Additions] + - {Task: Add a Child at the Beginning}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Add+a+Child+at+the+Beginning] + - {Task: Add a Child at the End}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Add+a+Child+at+the+End] + - {Task: Replace a Child with Another Child}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Replace+a+Child+with+Another+Child] + - {Task: Replace Multiple Children with Another Child}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Replace+Multiple+Children+with+Another+Child] + - {Task: Insert Child Before a Given Child}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Insert+Child+Before+a+Given+Child] + - {Task: Insert Child After a Given Child}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Insert+Child+After+a+Given+Child] +- {Deletions}[../../tasks/rdoc/parent_rdoc.html#label-Deletions] + - {Task: Remove a Given Child}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Remove+a+Given+Child] + - {Task: Remove the Child at a Specified Offset}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Remove+the+Child+at+a+Specified+Offset] + - {Task: Remove Children That Meet Specified Criteria}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Remove+Children+That+Meet+Specified+Criteria] +- {Iterations}[../../tasks/rdoc/parent_rdoc.html#label-Iterations] + - {Task: Iterate Over Children}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Iterate+Over+Children] + - {Task: Iterate Over Child Indexes}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Iterate+Over+Child+Indexes] +- {Clones}[../../tasks/rdoc/parent_rdoc.html#label-Clones] + - {Task: Clone Deeply}[../../tasks/rdoc/parent_rdoc.html#label-Task-3A+Clone+Deeply] + diff --git a/doc/rexml/tasks/tocs/node_toc.rdoc b/doc/rexml/tasks/tocs/node_toc.rdoc new file mode 100644 index 00000000..d9114faf --- /dev/null +++ b/doc/rexml/tasks/tocs/node_toc.rdoc @@ -0,0 +1,16 @@ +Tasks on this page: + +- {Siblings}[#label-Siblings] + - {Task: Find Previous Sibling}[#label-Task-3A+Find+Previous+Sibling] + - {Task: Find Next Sibling}[#label-Task-3A+Find+Next+Sibling] +- {Position}[#label-Position] + - {Task: Find Own Index Among Siblings}[#label-Task-3A+Find+Own+Index+Among+Siblings] +- {Recursive Traversal}[#label-Recursive+Traversal] + - {Task: Traverse Each Recursively}[#label-Task-3A+Traverse+Each+Recursively] +- {Recursive Search}[#label-Recursive+Search] + - {Task: Traverse Each Recursively}[#label-Task-3A+Traverse+Each+Recursively] +- {Representation}[#label-Representation] + - {Task: Represent a String}[#label-Task-3A+Represent+a+String] +- {Parent?}[#label-Parent-3F] + - {Task: Determine Whether the Node is a Parent}[#label-Task-3A+Determine+Whether+the+Node+is+a+Parent] + diff --git a/doc/rexml/tasks/tocs/parent_toc.rdoc b/doc/rexml/tasks/tocs/parent_toc.rdoc new file mode 100644 index 00000000..68fc0b70 --- /dev/null +++ b/doc/rexml/tasks/tocs/parent_toc.rdoc @@ -0,0 +1,25 @@ +Tasks on this page: + +- {Queries}[#label-Queries] + - {Task: Get the Count of Children}[#label-Task-3A+Get+the+Count+of+Children] + - {Task: Get the Child at a Given Index}[#label-Task-3A+Get+the+Child+at+a+Given+Index] + - {Task: Get the Index of a Given Child}[#label-Task-3A+Get+the+Index+of+a+Given+Child] + - {Task: Get the Children}[#label-Task-3A+Get+the+Children] + - {Task: Determine Whether the Node is a Parent}[#label-Task-3A+Determine+Whether+the+Node+is+a+Parent] +- {Additions}[#label-Additions] + - {Task: Add a Child at the Beginning}[#label-Task-3A+Add+a+Child+at+the+Beginning] + - {Task: Add a Child at the End}[#label-Task-3A+Add+a+Child+at+the+End] + - {Task: Replace a Child with Another Child}[#label-Task-3A+Replace+a+Child+with+Another+Child] + - {Task: Replace Multiple Children with Another Child}[#label-Task-3A+Replace+Multiple+Children+with+Another+Child] + - {Task: Insert Child Before a Given Child}[#label-Task-3A+Insert+Child+Before+a+Given+Child] + - {Task: Insert Child After a Given Child}[#label-Task-3A+Insert+Child+After+a+Given+Child] +- {Deletions}[#label-Deletions] + - {Task: Remove a Given Child}[#label-Task-3A+Remove+a+Given+Child] + - {Task: Remove the Child at a Specified Offset}[#label-Task-3A+Remove+the+Child+at+a+Specified+Offset] + - {Task: Remove Children That Meet Specified Criteria}[#label-Task-3A+Remove+Children+That+Meet+Specified+Criteria] +- {Iterations}[#label-Iterations] + - {Task: Iterate Over Children}[#label-Task-3A+Iterate+Over+Children] + - {Task: Iterate Over Child Indexes}[#label-Task-3A+Iterate+Over+Child+Indexes] +- {Clones}[#label-Clones] + - {Task: Clone Deeply}[#label-Task-3A+Clone+Deeply] + diff --git a/rexml.gemspec b/rexml.gemspec index 660dca27..620a8981 100644 --- a/rexml.gemspec +++ b/rexml.gemspec @@ -42,6 +42,13 @@ Gem::Specification.new do |spec| end end end + tasks_path = "tasks" + tasks_dir = File.join(__dir__, tasks_path) + Dir.chdir(doc_dir) do + Dir.glob("**/*.rake").each do |task_file| + files << "#{tasks_path}/#{task_file}" + end + end spec.files = files spec.rdoc_options.concat(["--main", "README.md"]) spec.extra_rdoc_files = rdoc_files diff --git a/tasks/tocs.rake b/tasks/tocs.rake new file mode 100644 index 00000000..a08f5a9f --- /dev/null +++ b/tasks/tocs.rake @@ -0,0 +1,95 @@ +require "tmpdir" + +class TOCsGenerator + include Rake::DSL + + def generate + doc_tasks_dir = File.join(__dir__, "..", "doc", "rexml", "tasks") + cd(doc_tasks_dir) do + lis_by_name = extract_lis + generate_files(lis_by_name) + end + end + + private + def extract_lis + lis_by_name = {} + Dir.mktmpdir do |tmpdir| + sh("rdoc", "--op", tmpdir, "--force-output", "rdoc") + cd("#{tmpdir}/rdoc") do + Dir.new('.').entries.each do |html_file_path| + next if html_file_path.start_with?('.') + toc_lis = [] + File.open(html_file_path, 'r') do |file| + in_toc = false + file.each_line do |line| + unless in_toc + if line.include?('
    ') + in_toc = true + next + end + end + if in_toc + break if line.include?('
') + toc_lis.push(line.chomp) + end + end + end + key = html_file_path.sub('_rdoc.html', '') + lis_by_name[key] = toc_lis + end + end + end + lis_by_name + end + + def generate_files(lis_by_name) + File.open('tocs/master_toc.rdoc', 'w') do |master_toc_file| + master_toc_file.write("== Table of Contents\n\n") + cd('tocs') do + entries = Dir.entries('.') + entries.delete_if {|entry| entry.start_with?('.') } + entries.delete_if {|entry| entry == 'master_toc.rdoc' } + lis_by_name.keys.sort.each do |name| + lis = lis_by_name[name] + toc_file_name = name + '_toc.rdoc' + entries.delete(toc_file_name) + File.open(toc_file_name, 'w') do |class_file| + class_file.write("Tasks on this page:\n\n") + lis.each_with_index do |li, i| + _, temp = li.split('"', 2) + link, temp = temp.split('">', 2) + text = temp.sub('', '') + indentation = text.start_with?('Task') ? ' ' : '' + toc_entry = "#{indentation}- {#{text}}[#{link}]\n" + if i == 0 + text = text.split(' ')[1] + link = "../../tasks/rdoc/#{text.downcase}_rdoc.html" + master_toc_file.write("=== {#{text}}[#{link}]\n") + next + end + master_link = "../../tasks/rdoc/#{toc_file_name.sub('_toc.rdoc', '_rdoc.html')}#{link}" + master_toc_entry = "#{indentation}- {#{text}}[#{master_link}]\n" + master_toc_file.write(master_toc_entry) + class_file.write(toc_entry) + end + master_toc_file.write("\n") + class_file.write("\n") + end + end + unless entries.empty? + message = "Some entries not updated: #{entries}" + raise message + end + end + end + end +end + +namespace :tocs do + desc "Generate TOCs" + task :generate do + generator = TOCsGenerator.new + generator.generate + end +end From eda1b2007dd8751f381bf741f16c9e33c5d3e52a Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Wed, 10 Mar 2021 15:24:19 -0600 Subject: [PATCH 47/56] Clean up and enhance high-level RDoc (#65) --- README.md | 16 ++-------- doc/rexml/tasks/tocs/master_toc.rdoc | 2 +- lib/rexml/document.rb | 9 ++++++ lib/rexml/element.rb | 9 ++++++ lib/rexml/light/node.rb | 8 ----- lib/rexml/rexml.rb | 47 +++++++++++++++------------- tasks/tocs.rake | 2 +- 7 files changed, 48 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index da38f36f..27da0e49 100644 --- a/README.md +++ b/README.md @@ -4,21 +4,9 @@ REXML was inspired by the Electric XML library for Java, which features an easy- REXML supports both tree and stream document parsing. Stream parsing is faster (about 1.5 times as fast). However, with stream parsing, you don't get access to features such as XPath. -## Installation +## API -Add this line to your application's Gemfile: - -```ruby -gem 'rexml' -``` - -And then execute: - - $ bundle - -Or install it yourself as: - - $ gem install rexml +See the {API documentation}[https://ruby.github.io/rexml/] ## Usage diff --git a/doc/rexml/tasks/tocs/master_toc.rdoc b/doc/rexml/tasks/tocs/master_toc.rdoc index ccc2f401..0214f6b2 100644 --- a/doc/rexml/tasks/tocs/master_toc.rdoc +++ b/doc/rexml/tasks/tocs/master_toc.rdoc @@ -1,4 +1,4 @@ -== Table of Contents +== Tasks === {Child}[../../tasks/rdoc/child_rdoc.html] - {Relationships}[../../tasks/rdoc/child_rdoc.html#label-Relationships] diff --git a/lib/rexml/document.rb b/lib/rexml/document.rb index b8db6ef3..2edeb987 100644 --- a/lib/rexml/document.rb +++ b/lib/rexml/document.rb @@ -23,6 +23,15 @@ module REXML # - A document type. # - Processing instructions. # + # == In a Hurry? + # + # If you're somewhat familiar with XML + # and have a particular task in mind, + # you may want to see the + # {tasks pages}[../doc/rexml/tasks/tocs/master_toc_rdoc.html], + # and in particular, the + # {tasks page for documents}[../doc/rexml/tasks/tocs/document_toc_rdoc.html]. + # class Document < Element # A convenient default XML declaration. Use: # diff --git a/lib/rexml/element.rb b/lib/rexml/element.rb index 39e6ebcb..4c21dbd5 100644 --- a/lib/rexml/element.rb +++ b/lib/rexml/element.rb @@ -27,6 +27,15 @@ module REXML # (other elements, text, CDATA, processing instructions, and comments). # - Has zero or more named attributes. # + # == In a Hurry? + # + # If you're somewhat familiar with XML + # and have a particular task in mind, + # you may want to see the + # {tasks pages}[../doc/rexml/tasks/tocs/master_toc_rdoc.html], + # and in particular, the + # {tasks page for elements}[../doc/rexml/tasks/tocs/element_toc_rdoc.html]. + # # === Name # # An element has a name, which is initially set when the element is created: diff --git a/lib/rexml/light/node.rb b/lib/rexml/light/node.rb index 01177c64..3dab885b 100644 --- a/lib/rexml/light/node.rb +++ b/lib/rexml/light/node.rb @@ -1,14 +1,6 @@ # frozen_string_literal: false require_relative '../xmltokens' -# [ :element, parent, name, attributes, children* ] - # a = Node.new - # a << "B" # => B - # a.b # => B - # a.b[1] # => B - # a.b[1]["x"] = "y" # => B - # a.b[0].c # => B - # a.b.c << "D" # => BD module REXML module Light # Represents a tagged XML element. Elements are characterized by diff --git a/lib/rexml/rexml.rb b/lib/rexml/rexml.rb index fcefbae1..8a01f0e1 100644 --- a/lib/rexml/rexml.rb +++ b/lib/rexml/rexml.rb @@ -1,26 +1,31 @@ # -*- coding: utf-8 -*- # frozen_string_literal: false -# REXML is an XML toolkit for Ruby[http://www.ruby-lang.org], in Ruby. -# -# REXML is a _pure_ Ruby, XML 1.0 conforming, -# non-validating[http://www.w3.org/TR/2004/REC-xml-20040204/#sec-conformance] -# toolkit with an intuitive API. REXML passes 100% of the non-validating Oasis -# tests[http://www.oasis-open.org/committees/xml-conformance/xml-test-suite.shtml], -# and provides tree, stream, SAX2, pull, and lightweight APIs. REXML also -# includes a full XPath[http://www.w3c.org/tr/xpath] 1.0 implementation. Since -# Ruby 1.8, REXML is included in the standard Ruby distribution. -# -# Main page:: http://www.germane-software.com/software/rexml -# Author:: Sean Russell -# Date:: 2008/019 -# Version:: 3.1.7.3 -# -# This API documentation can be downloaded from the REXML home page, or can -# be accessed online[http://www.germane-software.com/software/rexml_doc] -# -# A tutorial is available in the REXML distribution in docs/tutorial.html, -# or can be accessed -# online[http://www.germane-software.com/software/rexml/docs/tutorial.html] +# +# \Module \REXML provides classes and methods for parsing, +# editing, and generating XML. +# +# == Implementation +# +# \REXML: +# - Is pure Ruby. +# - Provides tree, stream, SAX2, pull, and lightweight APIs. +# - Conforms to {XML version 1.0}[https://www.w3.org/TR/REC-xml/]. +# - Fully implements {XPath version 1.0}[http://www.w3c.org/tr/xpath]. +# - Is {non-validating}[https://www.w3.org/TR/xml/]. +# - Passes 100% of the non-validating {Oasis tests}[http://www.oasis-open.org/committees/xml-conformance/xml-test-suite.shtml]. +# +# == In a Hurry? +# +# If you're somewhat familiar with XML +# and have a particular task in mind, +# you may want to see {the tasks pages}[doc/rexml/tasks/tocs/master_toc_rdoc.html]. +# +# == API +# +# Among the most important classes for using \REXML are: +# - REXML::Document. +# - REXML::Element. +# module REXML COPYRIGHT = "Copyright © 2001-2008 Sean Russell " DATE = "2008/019" diff --git a/tasks/tocs.rake b/tasks/tocs.rake index a08f5a9f..0b0e7c7f 100644 --- a/tasks/tocs.rake +++ b/tasks/tocs.rake @@ -45,7 +45,7 @@ class TOCsGenerator def generate_files(lis_by_name) File.open('tocs/master_toc.rdoc', 'w') do |master_toc_file| - master_toc_file.write("== Table of Contents\n\n") + master_toc_file.write("== Tasks\n\n") cd('tocs') do entries = Dir.entries('.') entries.delete_if {|entry| entry.start_with?('.') } From 790dd113ce693ce831cbbc53f2f990a317643f75 Mon Sep 17 00:00:00 2001 From: Hiroshi SHIBATA Date: Mon, 29 Mar 2021 14:21:32 +0900 Subject: [PATCH 48/56] Use ruby/setup-ruby (#66) actions/setup-ruby is deprecated now --- .github/workflows/test.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 1563ed08..65a3bffd 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -63,7 +63,9 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - - uses: actions/setup-ruby@v1 + - uses: ruby/setup-ruby@v1 + with: + ruby-version: 2.7 - name: Install dependencies run: | bundle install From a659c63e37414506dfb0d4655e031bb7a2e73fc8 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Sat, 20 Feb 2021 07:22:57 +0900 Subject: [PATCH 49/56] Fix a bug that invalid notation declaration may be generated HackerOne: HO-1104077 It's caused by quote character. Reported by Juho Nurminen. Thanks!!! --- lib/rexml/doctype.rb | 24 +++++++++-- test/test_doctype.rb | 99 +++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 118 insertions(+), 5 deletions(-) diff --git a/lib/rexml/doctype.rb b/lib/rexml/doctype.rb index dcfa0cfc..3e86cccc 100644 --- a/lib/rexml/doctype.rb +++ b/lib/rexml/doctype.rb @@ -255,13 +255,29 @@ def to_s c = nil c = parent.context if parent if c and c[:prologue_quote] == :apostrophe - quote = "'" + default_quote = "'" else - quote = "\"" + default_quote = "\"" end notation = "" notation end diff --git a/test/test_doctype.rb b/test/test_doctype.rb index a00c5d00..14284c94 100644 --- a/test/test_doctype.rb +++ b/test/test_doctype.rb @@ -89,11 +89,26 @@ def test_to_s decl(@id, nil).to_s) end + def test_to_s_pubid_literal_include_apostrophe + assert_equal("", + decl("#{@id}'", nil).to_s) + end + def test_to_s_with_uri assert_equal("", decl(@id, @uri).to_s) end + def test_to_s_system_literal_include_apostrophe + assert_equal("", + decl(@id, "system'literal").to_s) + end + + def test_to_s_system_literal_include_double_quote + assert_equal("", + decl(@id, "system\"literal").to_s) + end + def test_to_s_apostrophe document = REXML::Document.new(<<-XML) + + XML + # This isn't used for PubidLiteral because PubidChar includes '. + document.context[:prologue_quote] = :apostrophe + notation = document.doctype.notations[0] + assert_equal("", + notation.to_s) + end + + def test_to_s_apostrophe_system_literal_include_apostrophe + document = REXML::Document.new(<<-XML) + + + XML + # This isn't used for SystemLiteral because SystemLiteral includes '. + document.context[:prologue_quote] = :apostrophe + notation = document.doctype.notations[0] + assert_equal("", + notation.to_s) + end + + def test_to_s_apostrophe_system_literal_include_double_quote + document = REXML::Document.new(<<-XML) + + + XML + # This isn't used for SystemLiteral because SystemLiteral includes ". + # But quoted by ' because SystemLiteral includes ". + document.context[:prologue_quote] = :apostrophe + notation = document.doctype.notations[0] + assert_equal("", + notation.to_s) + end + private def decl(id, uri) REXML::NotationDecl.new(@name, "PUBLIC", id, uri) @@ -124,6 +182,16 @@ def test_to_s decl(@id).to_s) end + def test_to_s_include_apostrophe + assert_equal("", + decl("#{@id}'").to_s) + end + + def test_to_s_include_double_quote + assert_equal("", + decl("#{@id}\"").to_s) + end + def test_to_s_apostrophe document = REXML::Document.new(<<-XML) + + XML + # This isn't used for SystemLiteral because SystemLiteral includes '. + document.context[:prologue_quote] = :apostrophe + notation = document.doctype.notations[0] + assert_equal("", + notation.to_s) + end + + def test_to_s_apostrophe_include_double_quote + document = REXML::Document.new(<<-XML) + + + XML + # This isn't used for SystemLiteral because SystemLiteral includes ". + # But quoted by ' because SystemLiteral includes ". + document.context[:prologue_quote] = :apostrophe + notation = document.doctype.notations[0] + assert_equal("", + notation.to_s) + end + private def decl(id) - REXML::NotationDecl.new(@name, "SYSTEM", id, nil) + REXML::NotationDecl.new(@name, "SYSTEM", nil, id) end end end From 2fe62e29094d95921d7e19abbd2e26b23d78dc5b Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Sat, 20 Feb 2021 07:26:19 +0900 Subject: [PATCH 50/56] Fix a bug that invalid notation declaration may be accepted HackerOne: HO-1104077 It's caused by quote character. Reported by Juho Nurminen. Thanks!!! --- lib/rexml/parsers/baseparser.rb | 59 +++++++- test/parse/test_notation_declaration.rb | 181 ++++++++++++++++++++++++ 2 files changed, 234 insertions(+), 6 deletions(-) diff --git a/lib/rexml/parsers/baseparser.rb b/lib/rexml/parsers/baseparser.rb index f76aed07..84fc5ca5 100644 --- a/lib/rexml/parsers/baseparser.rb +++ b/lib/rexml/parsers/baseparser.rb @@ -83,9 +83,6 @@ class BaseParser ATTDEF_RE = /#{ATTDEF}/ ATTLISTDECL_START = /\A\s*/um - NOTATIONDECL_START = /\A\s*/um - SYSTEM = /\A\s*/um TEXT_PATTERN = /\A([^<]*)/um @@ -103,6 +100,10 @@ class BaseParser GEDECL = "" ENTITYDECL = /\s*(?:#{GEDECL})|(?:#{PEDECL})/um + NOTATIONDECL_START = /\A\s*/um + SYSTEM = /\A\s*/um + EREFERENCE = /&(?!#{NAME};)/ DEFAULT_ENTITIES = { @@ -315,12 +316,22 @@ def pull_event md = nil if @source.match( PUBLIC ) md = @source.match( PUBLIC, true ) - vals = [md[1],md[2],md[4],md[6]] + pubid = system = nil + pubid_literal = md[3] + pubid = pubid_literal[1..-2] if pubid_literal # Remove quote + system_literal = md[4] + system = system_literal[1..-2] if system_literal # Remove quote + vals = [md[1], md[2], pubid, system] elsif @source.match( SYSTEM ) md = @source.match( SYSTEM, true ) - vals = [md[1],md[2],nil,md[4]] + system = nil + system_literal = md[3] + system = system_literal[1..-2] if system_literal # Remove quote + vals = [md[1], md[2], nil, system] else - raise REXML::ParseException.new( "error parsing notation: no matching pattern", @source ) + details = notation_decl_invalid_details + message = "Malformed notation declaration: #{details}" + raise REXML::ParseException.new(message, @source) end return [ :notationdecl, *vals ] when DOCTYPE_END @@ -569,6 +580,42 @@ def parse_attributes(prefixes, curr_ns) end return attributes, closed end + + def notation_decl_invalid_details + name = /#{NOTATIONDECL_START}\s+#{NAME}/um + public = /#{name}\s+PUBLIC/um + system = /#{name}\s+SYSTEM/um + if @source.match(/#{NOTATIONDECL_START}\s*>/um) + return "name is missing" + elsif not @source.match(/#{name}[\s>]/um) + return "invalid name" + elsif @source.match(/#{name}\s*>/um) + return "ID type is missing" + elsif not @source.match(/#{name}\s+(?:PUBLIC|SYSTEM)[\s>]/um) + return "invalid ID type" + elsif @source.match(/#{public}/um) + if @source.match(/#{public}\s*>/um) + return "public ID literal is missing" + elsif not @source.match(/#{public}\s+#{PUBIDLITERAL}/um) + return "invalid public ID literal" + elsif @source.match(/#{public}\s+#{PUBIDLITERAL}[^\s>]/um) + return "garbage after public ID literal" + elsif not @source.match(/#{public}\s+#{PUBIDLITERAL}\s+#{SYSTEMLITERAL}/um) + return "invalid system literal" + elsif not @source.match(/#{public}\s+#{PUBIDLITERAL}\s+#{SYSTEMLITERAL}\s*>/um) + return "garbage after system literal" + end + elsif @source.match(/#{system}/um) + if @source.match(/#{system}\s*>/um) + return "system literal is missing" + elsif not @source.match(/#{system}\s+#{SYSTEMLITERAL}/um) + return "invalid system literal" + elsif not @source.match(/#{system}\s+#{SYSTEMLITERAL}\s*>/um) + return "garbage after system literal" + end + end + "end > is missing" + end end end end diff --git a/test/parse/test_notation_declaration.rb b/test/parse/test_notation_declaration.rb index 0d29f0d8..fbd29e2a 100644 --- a/test/parse/test_notation_declaration.rb +++ b/test/parse/test_notation_declaration.rb @@ -23,10 +23,100 @@ def test_name doctype = parse("") assert_equal("name", doctype.notation("name").name) end + + def test_no_name + exception = assert_raise(REXML::ParseException) do + parse(<<-INTERNAL_SUBSET) + + INTERNAL_SUBSET + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Malformed notation declaration: name is missing +Line: 5 +Position: 72 +Last 80 unconsumed characters: + ]> + DETAIL + end + + def test_invalid_name + exception = assert_raise(REXML::ParseException) do + parse(<<-INTERNAL_SUBSET) + + INTERNAL_SUBSET + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Malformed notation declaration: invalid name +Line: 5 +Position: 74 +Last 80 unconsumed characters: + ]> + DETAIL + end + + def test_no_id_type + exception = assert_raise(REXML::ParseException) do + parse(<<-INTERNAL_SUBSET) + + INTERNAL_SUBSET + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Malformed notation declaration: ID type is missing +Line: 5 +Position: 77 +Last 80 unconsumed characters: + ]> + DETAIL + end + + def test_invalid_id_type + exception = assert_raise(REXML::ParseException) do + parse(<<-INTERNAL_SUBSET) + + INTERNAL_SUBSET + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Malformed notation declaration: invalid ID type +Line: 5 +Position: 85 +Last 80 unconsumed characters: + ]> + DETAIL + end end class TestExternalID < self class TestSystem < self + def test_no_literal + exception = assert_raise(REXML::ParseException) do + parse(<<-INTERNAL_SUBSET) + + INTERNAL_SUBSET + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Malformed notation declaration: system literal is missing +Line: 5 +Position: 84 +Last 80 unconsumed characters: + ]> + DETAIL + end + + def test_garbage_after_literal + exception = assert_raise(REXML::ParseException) do + parse(<<-INTERNAL_SUBSET) + + INTERNAL_SUBSET + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Malformed notation declaration: garbage after system literal +Line: 5 +Position: 103 +Last 80 unconsumed characters: + ]> + DETAIL + end + def test_single_quote doctype = parse(<<-INTERNAL_SUBSET) @@ -44,6 +134,21 @@ def test_double_quote class TestPublic < self class TestPublicIDLiteral < self + def test_content_double_quote + exception = assert_raise(REXML::ParseException) do + parse(<<-INTERNAL_SUBSET) + + INTERNAL_SUBSET + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Malformed notation declaration: invalid public ID literal +Line: 5 +Position: 129 +Last 80 unconsumed characters: + ]> + DETAIL + end + def test_single_quote doctype = parse(<<-INTERNAL_SUBSET) @@ -60,6 +165,21 @@ def test_double_quote end class TestSystemLiteral < self + def test_garbage_after_literal + exception = assert_raise(REXML::ParseException) do + parse(<<-INTERNAL_SUBSET) + + INTERNAL_SUBSET + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Malformed notation declaration: garbage after system literal +Line: 5 +Position: 123 +Last 80 unconsumed characters: + ]> + DETAIL + end + def test_single_quote doctype = parse(<<-INTERNAL_SUBSET) @@ -96,5 +216,66 @@ def test_public_system end end end + + class TestPublicID < self + def test_no_literal + exception = assert_raise(REXML::ParseException) do + parse(<<-INTERNAL_SUBSET) + + INTERNAL_SUBSET + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Malformed notation declaration: public ID literal is missing +Line: 5 +Position: 84 +Last 80 unconsumed characters: + ]> + DETAIL + end + + def test_literal_content_double_quote + exception = assert_raise(REXML::ParseException) do + parse(<<-INTERNAL_SUBSET) + + INTERNAL_SUBSET + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Malformed notation declaration: invalid public ID literal +Line: 5 +Position: 128 +Last 80 unconsumed characters: + ]> + DETAIL + end + + def test_garbage_after_literal + exception = assert_raise(REXML::ParseException) do + parse(<<-INTERNAL_SUBSET) + + INTERNAL_SUBSET + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Malformed notation declaration: garbage after public ID literal +Line: 5 +Position: 106 +Last 80 unconsumed characters: + ]> + DETAIL + end + + def test_literal_single_quote + doctype = parse(<<-INTERNAL_SUBSET) + + INTERNAL_SUBSET + assert_equal("public-id-literal", doctype.notation("name").public) + end + + def test_literal_double_quote + doctype = parse(<<-INTERNAL_SUBSET) + + INTERNAL_SUBSET + assert_equal("public-id-literal", doctype.notation("name").public) + end + end end end From 6a250d2cd1194c2be72becbdd9c3e770aa16e752 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Tue, 23 Feb 2021 10:26:52 +0900 Subject: [PATCH 51/56] Fix a bug that invalid element start may be accepted HackerOne: HO-1104077 It's caused by ignoring garbage before "\n/um INSTRUCTION_START = /\A<\?/u INSTRUCTION_PATTERN = /<\?#{NAME}(\s+.*?)?\?>/um - TAG_MATCH = /^<((?>#{QNAME_STR}))/um + TAG_MATCH = /\A<((?>#{QNAME_STR}))/um CLOSE_MATCH = /^\s*<\/(#{QNAME_STR})\s*>/um VERSION = /\bversion\s*=\s*["'](.*?)['"]/um diff --git a/test/parse/test_element.rb b/test/parse/test_element.rb index 7322e0eb..1c4258c7 100644 --- a/test/parse/test_element.rb +++ b/test/parse/test_element.rb @@ -46,6 +46,19 @@ def test_empty_namespace_attribute_name DETAIL end + + def test_garbage_less_than_before_root_element_at_line_start + exception = assert_raise(REXML::ParseException) do + parse("<\n") + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +malformed XML: missing tag start +Line: 2 +Position: 6 +Last 80 unconsumed characters: +< + DETAIL + end end end end From f7bab8937513b1403cea5aff874cbf32fd5e8551 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Tue, 23 Feb 2021 10:29:13 +0900 Subject: [PATCH 52/56] Fix a bug that invalid element end may be accepted HackerOne: HO-1104077 It's caused by ignoring garbage before "\n". Reported by Juho Nurminen. Thanks!!! --- lib/rexml/parsers/baseparser.rb | 2 +- test/parse/test_element.rb | 13 +++++++++++++ 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/lib/rexml/parsers/baseparser.rb b/lib/rexml/parsers/baseparser.rb index afc15db9..ca29b4a9 100644 --- a/lib/rexml/parsers/baseparser.rb +++ b/lib/rexml/parsers/baseparser.rb @@ -62,7 +62,7 @@ class BaseParser INSTRUCTION_START = /\A<\?/u INSTRUCTION_PATTERN = /<\?#{NAME}(\s+.*?)?\?>/um TAG_MATCH = /\A<((?>#{QNAME_STR}))/um - CLOSE_MATCH = /^\s*<\/(#{QNAME_STR})\s*>/um + CLOSE_MATCH = /\A\s*<\/(#{QNAME_STR})\s*>/um VERSION = /\bversion\s*=\s*["'](.*?)['"]/um ENCODING = /\bencoding\s*=\s*["'](.*?)['"]/um diff --git a/test/parse/test_element.rb b/test/parse/test_element.rb index 1c4258c7..9f172a28 100644 --- a/test/parse/test_element.rb +++ b/test/parse/test_element.rb @@ -59,6 +59,19 @@ def test_garbage_less_than_before_root_element_at_line_start < DETAIL end + + def test_garbage_less_than_slash_before_end_tag_at_line_start + exception = assert_raise(REXML::ParseException) do + parse("") + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Missing end tag for 'x' +Line: 2 +Position: 10 +Last 80 unconsumed characters: + + DETAIL + end end end end From f9d88e4948b4a43294c25dc0edb16815bd9d8618 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Tue, 23 Feb 2021 16:11:04 +0900 Subject: [PATCH 53/56] Fix a bug that invalid document declaration may be generated HackerOne: HO-1104077 It's caused by quote character. Reported by Juho Nurminen. Thanks!!! --- lib/rexml/doctype.rb | 85 ++++++++++++++++++++--------------- test/test_doctype.rb | 105 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+), 35 deletions(-) diff --git a/lib/rexml/doctype.rb b/lib/rexml/doctype.rb index 3e86cccc..f3590484 100644 --- a/lib/rexml/doctype.rb +++ b/lib/rexml/doctype.rb @@ -7,6 +7,44 @@ require_relative 'xmltokens' module REXML + class ReferenceWriter + def initialize(id_type, + public_id_literal, + system_literal, + context=nil) + @id_type = id_type + @public_id_literal = public_id_literal + @system_literal = system_literal + if context and context[:prologue_quote] == :apostrophe + @default_quote = "'" + else + @default_quote = "\"" + end + end + + def write(output) + output << " #{@id_type}" + if @public_id_literal + if @public_id_literal.include?("'") + quote = "\"" + else + quote = @default_quote + end + output << " #{quote}#{@public_id_literal}#{quote}" + end + if @system_literal + if @system_literal.include?("'") + quote = "\"" + elsif @system_literal.include?("\"") + quote = "'" + else + quote = @default_quote + end + output << " #{quote}#{@system_literal}#{quote}" + end + end + end + # Represents an XML DOCTYPE declaration; that is, the contents of . DOCTYPES can be used to declare the DTD of a document, as well as # being used to declare entities used in the document. @@ -110,19 +148,17 @@ def clone # Ignored def write( output, indent=0, transitive=false, ie_hack=false ) f = REXML::Formatters::Default.new - c = context - if c and c[:prologue_quote] == :apostrophe - quote = "'" - else - quote = "\"" - end indent( output, indent ) output << START output << ' ' output << @name - output << " #{@external_id}" if @external_id - output << " #{quote}#{@long_name}#{quote}" if @long_name - output << " #{quote}#{@uri}#{quote}" if @uri + if @external_id + reference_writer = ReferenceWriter.new(@external_id, + @long_name, + @uri, + context) + reference_writer.write(output) + end unless @children.empty? output << ' [' @children.each { |child| @@ -252,32 +288,11 @@ def initialize name, middle, pub, sys end def to_s - c = nil - c = parent.context if parent - if c and c[:prologue_quote] == :apostrophe - default_quote = "'" - else - default_quote = "\"" - end - notation = "" notation end diff --git a/test/test_doctype.rb b/test/test_doctype.rb index 14284c94..b20d30ae 100644 --- a/test/test_doctype.rb +++ b/test/test_doctype.rb @@ -77,6 +77,111 @@ def test_notations end end + class TestDocType < Test::Unit::TestCase + class TestExternalID < self + class TestSystem < self + class TestSystemLiteral < self + def test_to_s + doctype = REXML::DocType.new(["root", "SYSTEM", nil, "root.dtd"]) + assert_equal("", + doctype.to_s) + end + + def test_to_s_apostrophe + doctype = REXML::DocType.new(["root", "SYSTEM", nil, "root.dtd"]) + doc = REXML::Document.new + doc << doctype + doctype.parent.context[:prologue_quote] = :apostrophe + assert_equal("", + doctype.to_s) + end + + def test_to_s_single_quote_apostrophe + doctype = REXML::DocType.new(["root", "SYSTEM", nil, "root'.dtd"]) + doc = REXML::Document.new + doc << doctype + # This isn't used. + doctype.parent.context[:prologue_quote] = :apostrophe + assert_equal("", + doctype.to_s) + end + + def test_to_s_double_quote + doctype = REXML::DocType.new(["root", "SYSTEM", nil, "root\".dtd"]) + doc = REXML::Document.new + doc << doctype + # This isn't used. + doctype.parent.context[:prologue_quote] = :apostrophe + assert_equal("", + doctype.to_s) + end + end + end + + class TestPublic < self + class TestPublicIDLiteral < self + def test_to_s + doctype = REXML::DocType.new(["root", "PUBLIC", "pub", "root.dtd"]) + assert_equal("", + doctype.to_s) + end + + def test_to_s_apostrophe + doctype = REXML::DocType.new(["root", "PUBLIC", "pub", "root.dtd"]) + doc = REXML::Document.new + doc << doctype + doctype.parent.context[:prologue_quote] = :apostrophe + assert_equal("", + doctype.to_s) + end + + def test_to_s_apostrophe_include_apostrophe + doctype = REXML::DocType.new(["root", "PUBLIC", "pub'", "root.dtd"]) + doc = REXML::Document.new + doc << doctype + # This isn't used. + doctype.parent.context[:prologue_quote] = :apostrophe + assert_equal("", + doctype.to_s) + end + end + + class TestSystemLiteral < self + def test_to_s + doctype = REXML::DocType.new(["root", "PUBLIC", "pub", "root.dtd"]) + assert_equal("", + doctype.to_s) + end + + def test_to_s_apostrophe + doctype = REXML::DocType.new(["root", "PUBLIC", "pub", "root.dtd"]) + doc = REXML::Document.new + doc << doctype + doctype.parent.context[:prologue_quote] = :apostrophe + assert_equal("", + doctype.to_s) + end + + def test_to_s_apostrophe_include_apostrophe + doctype = REXML::DocType.new(["root", "PUBLIC", "pub", "root'.dtd"]) + doc = REXML::Document.new + doc << doctype + # This isn't used. + doctype.parent.context[:prologue_quote] = :apostrophe + assert_equal("", + doctype.to_s) + end + + def test_to_s_double_quote + doctype = REXML::DocType.new(["root", "PUBLIC", "pub", "root\".dtd"]) + assert_equal("", + doctype.to_s) + end + end + end + end + end + class TestNotationDeclPublic < Test::Unit::TestCase def setup @name = "vrml" From 9b311e59ae05749e082eb6bbefa1cb620d1a786e Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Tue, 23 Feb 2021 16:24:30 +0900 Subject: [PATCH 54/56] Fix a bug that invalid document declaration may be accepted HackerOne: HO-1104077 It's caused by ignoring garbage before "\n/um - DOCTYPE_PATTERN = /\s*)/um ATTRIBUTE_PATTERN = /\s*(#{QNAME_STR})\s*=\s*(["'])(.*?)\4/um COMMENT_START = /\A/um @@ -69,7 +68,6 @@ class BaseParser STANDALONE = /\bstandalone\s*=\s*["'](.*?)['"]/um ENTITY_START = /\A\s*/um SYSTEMENTITY = /\A\s*(%.*?;)\s*$/um @@ -101,8 +99,9 @@ class BaseParser ENTITYDECL = /\s*(?:#{GEDECL})|(?:#{PEDECL})/um NOTATIONDECL_START = /\A\s*/um - SYSTEM = /\A\s*/um + EXTERNAL_ID_PUBLIC = /\A\s*PUBLIC\s+#{PUBIDLITERAL}\s+#{SYSTEMLITERAL}\s*/um + EXTERNAL_ID_SYSTEM = /\A\s*SYSTEM\s+#{SYSTEMLITERAL}\s*/um + PUBLIC_ID = /\A\s*PUBLIC\s+#{PUBIDLITERAL}\s*/um EREFERENCE = /&(?!#{NAME};)/ @@ -225,24 +224,37 @@ def pull_event when INSTRUCTION_START return process_instruction when DOCTYPE_START - md = @source.match( DOCTYPE_PATTERN, true ) + base_error_message = "Malformed DOCTYPE" + @source.match(DOCTYPE_START, true) @nsstack.unshift(curr_ns=Set.new) - identity = md[1] - close = md[2] - identity =~ IDENTITY - name = $1 - raise REXML::ParseException.new("DOCTYPE is missing a name") if name.nil? - pub_sys = $2.nil? ? nil : $2.strip - long_name = $4.nil? ? nil : $4.strip - uri = $6.nil? ? nil : $6.strip - args = [ :start_doctype, name, pub_sys, long_name, uri ] - if close == ">" + name = parse_name(base_error_message) + if @source.match(/\A\s*\[/um, true) + id = [nil, nil, nil] + @document_status = :in_doctype + elsif @source.match(/\A\s*>/um, true) + id = [nil, nil, nil] @document_status = :after_doctype - @source.read if @source.buffer.size<2 - md = @source.match(/^\s*/um, true) - @stack << [ :end_doctype ] else - @document_status = :in_doctype + id = parse_id(base_error_message, + accept_external_id: true, + accept_public_id: false) + if id[0] == "SYSTEM" + # For backward compatibility + id[1], id[2] = id[2], nil + end + if @source.match(/\A\s*\[/um, true) + @document_status = :in_doctype + elsif @source.match(/\A\s*>/um, true) + @document_status = :after_doctype + else + message = "#{base_error_message}: garbage after external ID" + raise REXML::ParseException.new(message, @source) + end + end + args = [:start_doctype, name, *id] + if @document_status == :after_doctype + @source.match(/\A\s*/um, true) + @stack << [ :end_doctype ] end return args when /^\s+/ @@ -313,27 +325,24 @@ def pull_event end return [ :attlistdecl, element, pairs, contents ] when NOTATIONDECL_START - md = nil - if @source.match( PUBLIC ) - md = @source.match( PUBLIC, true ) - pubid = system = nil - pubid_literal = md[3] - pubid = pubid_literal[1..-2] if pubid_literal # Remove quote - system_literal = md[4] - system = system_literal[1..-2] if system_literal # Remove quote - vals = [md[1], md[2], pubid, system] - elsif @source.match( SYSTEM ) - md = @source.match( SYSTEM, true ) - system = nil - system_literal = md[3] - system = system_literal[1..-2] if system_literal # Remove quote - vals = [md[1], md[2], nil, system] - else - details = notation_decl_invalid_details - message = "Malformed notation declaration: #{details}" + base_error_message = "Malformed notation declaration" + unless @source.match(/\A\s*/um) + message = "#{base_error_message}: name is missing" + else + message = "#{base_error_message}: invalid declaration name" + end + raise REXML::ParseException.new(message, @source) + end + name = parse_name(base_error_message) + id = parse_id(base_error_message, + accept_external_id: true, + accept_public_id: true) + unless @source.match(/\A\s*>/um, true) + message = "#{base_error_message}: garbage before end >" raise REXML::ParseException.new(message, @source) end - return [ :notationdecl, *vals ] + return [:notationdecl, name, *id] when DOCTYPE_END @document_status = :after_doctype @source.match( DOCTYPE_END, true ) @@ -488,6 +497,85 @@ def need_source_encoding_update?(xml_declaration_encoding) true end + def parse_name(base_error_message) + md = @source.match(/\A\s*#{NAME}/um, true) + unless md + if @source.match(/\A\s*\S/um) + message = "#{base_error_message}: invalid name" + else + message = "#{base_error_message}: name is missing" + end + raise REXML::ParseException.new(message, @source) + end + md[1] + end + + def parse_id(base_error_message, + accept_external_id:, + accept_public_id:) + if accept_external_id and (md = @source.match(EXTERNAL_ID_PUBLIC, true)) + pubid = system = nil + pubid_literal = md[1] + pubid = pubid_literal[1..-2] if pubid_literal # Remove quote + system_literal = md[2] + system = system_literal[1..-2] if system_literal # Remove quote + ["PUBLIC", pubid, system] + elsif accept_public_id and (md = @source.match(PUBLIC_ID, true)) + pubid = system = nil + pubid_literal = md[1] + pubid = pubid_literal[1..-2] if pubid_literal # Remove quote + ["PUBLIC", pubid, nil] + elsif accept_external_id and (md = @source.match(EXTERNAL_ID_SYSTEM, true)) + system = nil + system_literal = md[1] + system = system_literal[1..-2] if system_literal # Remove quote + ["SYSTEM", nil, system] + else + details = parse_id_invalid_details(accept_external_id: accept_external_id, + accept_public_id: accept_public_id) + message = "#{base_error_message}: #{details}" + raise REXML::ParseException.new(message, @source) + end + end + + def parse_id_invalid_details(accept_external_id:, + accept_public_id:) + public = /\A\s*PUBLIC/um + system = /\A\s*SYSTEM/um + if (accept_external_id or accept_public_id) and @source.match(/#{public}/um) + if @source.match(/#{public}(?:\s+[^'"]|\s*[\[>])/um) + return "public ID literal is missing" + end + unless @source.match(/#{public}\s+#{PUBIDLITERAL}/um) + return "invalid public ID literal" + end + if accept_public_id + if @source.match(/#{public}\s+#{PUBIDLITERAL}\s+[^'"]/um) + return "system ID literal is missing" + end + unless @source.match(/#{public}\s+#{PUBIDLITERAL}\s+#{SYSTEMLITERAL}/um) + return "invalid system literal" + end + "garbage after system literal" + else + "garbage after public ID literal" + end + elsif accept_external_id and @source.match(/#{system}/um) + if @source.match(/#{system}(?:\s+[^'"]|\s*[\[>])/um) + return "system literal is missing" + end + unless @source.match(/#{system}\s+#{SYSTEMLITERAL}/um) + return "invalid system literal" + end + "garbage after system literal" + else + unless @source.match(/\A\s*(?:PUBLIC|SYSTEM)\s/um) + return "invalid ID type" + end + "ID type is missing" + end + end + def process_instruction match_data = @source.match(INSTRUCTION_PATTERN, true) unless match_data @@ -580,42 +668,6 @@ def parse_attributes(prefixes, curr_ns) end return attributes, closed end - - def notation_decl_invalid_details - name = /#{NOTATIONDECL_START}\s+#{NAME}/um - public = /#{name}\s+PUBLIC/um - system = /#{name}\s+SYSTEM/um - if @source.match(/#{NOTATIONDECL_START}\s*>/um) - return "name is missing" - elsif not @source.match(/#{name}[\s>]/um) - return "invalid name" - elsif @source.match(/#{name}\s*>/um) - return "ID type is missing" - elsif not @source.match(/#{name}\s+(?:PUBLIC|SYSTEM)[\s>]/um) - return "invalid ID type" - elsif @source.match(/#{public}/um) - if @source.match(/#{public}\s*>/um) - return "public ID literal is missing" - elsif not @source.match(/#{public}\s+#{PUBIDLITERAL}/um) - return "invalid public ID literal" - elsif @source.match(/#{public}\s+#{PUBIDLITERAL}[^\s>]/um) - return "garbage after public ID literal" - elsif not @source.match(/#{public}\s+#{PUBIDLITERAL}\s+#{SYSTEMLITERAL}/um) - return "invalid system literal" - elsif not @source.match(/#{public}\s+#{PUBIDLITERAL}\s+#{SYSTEMLITERAL}\s*>/um) - return "garbage after system literal" - end - elsif @source.match(/#{system}/um) - if @source.match(/#{system}\s*>/um) - return "system literal is missing" - elsif not @source.match(/#{system}\s+#{SYSTEMLITERAL}/um) - return "invalid system literal" - elsif not @source.match(/#{system}\s+#{SYSTEMLITERAL}\s*>/um) - return "garbage after system literal" - end - end - "end > is missing" - end end end end diff --git a/test/parse/test_document_type_declaration.rb b/test/parse/test_document_type_declaration.rb index 80f70888..55713909 100644 --- a/test/parse/test_document_type_declaration.rb +++ b/test/parse/test_document_type_declaration.rb @@ -5,17 +5,187 @@ module REXMLTests class TestParseDocumentTypeDeclaration < Test::Unit::TestCase private - def xml(internal_subset) - <<-XML - + def parse(doctype) + REXML::Document.new(<<-XML).doctype +#{doctype} XML end - def parse(internal_subset) - REXML::Document.new(xml(internal_subset)).doctype + class TestName < self + def test_valid + doctype = parse(<<-DOCTYPE) + + DOCTYPE + assert_equal("r", doctype.name) + end + + def test_garbage_plus_before_name_at_line_start + exception = assert_raise(REXML::ParseException) do + parse(<<-DOCTYPE) + + DOCTYPE + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Malformed DOCTYPE: invalid name +Line: 5 +Position: 51 +Last 80 unconsumed characters: ++ r SYSTEM "urn:x-rexml:test" [ ]> + DETAIL + end + end + + class TestExternalID < self + class TestSystem < self + def test_left_bracket_in_system_literal + doctype = parse(<<-DOCTYPE) + + DOCTYPE + assert_equal([ + "r", + "SYSTEM", + nil, + "urn:x-rexml:[test", + ], + [ + doctype.name, + doctype.external_id, + doctype.public, + doctype.system, + ]) + end + + def test_greater_than_in_system_literal + doctype = parse(<<-DOCTYPE) +test" [ +]> + DOCTYPE + assert_equal([ + "r", + "SYSTEM", + nil, + "urn:x-rexml:>test", + ], + [ + doctype.name, + doctype.external_id, + doctype.public, + doctype.system, + ]) + end + + def test_no_literal + exception = assert_raise(REXML::ParseException) do + parse(<<-DOCTYPE) + + DOCTYPE + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Malformed DOCTYPE: system literal is missing +Line: 3 +Position: 26 +Last 80 unconsumed characters: + SYSTEM> + DETAIL + end + + def test_garbage_after_literal + exception = assert_raise(REXML::ParseException) do + parse(<<-DOCTYPE) + + DOCTYPE + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Malformed DOCTYPE: garbage after external ID +Line: 3 +Position: 36 +Last 80 unconsumed characters: +x'> + DETAIL + end + + def test_single_quote + doctype = parse(<<-DOCTYPE) + + DOCTYPE + assert_equal("r\".dtd", doctype.system) + end + + def test_double_quote + doctype = parse(<<-DOCTYPE) + + DOCTYPE + assert_equal("r'.dtd", doctype.system) + end + end + + class TestPublic < self + class TestPublicIDLiteral < self + def test_content_double_quote + exception = assert_raise(REXML::ParseException) do + parse(<<-DOCTYPE) + + DOCTYPE + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Malformed DOCTYPE: invalid public ID literal +Line: 3 +Position: 62 +Last 80 unconsumed characters: + PUBLIC 'double quote " is invalid' "r.dtd"> + DETAIL + end + + def test_single_quote + doctype = parse(<<-DOCTYPE) + + DOCTYPE + assert_equal("public-id-literal", doctype.public) + end + + def test_double_quote + doctype = parse(<<-DOCTYPE) + + DOCTYPE + assert_equal("public'-id-literal", doctype.public) + end + end + + class TestSystemLiteral < self + def test_garbage_after_literal + exception = assert_raise(REXML::ParseException) do + parse(<<-DOCTYPE) + + DOCTYPE + end + assert_equal(<<-DETAIL.chomp, exception.to_s) +Malformed DOCTYPE: garbage after external ID +Line: 3 +Position: 65 +Last 80 unconsumed characters: +x'> + DETAIL + end + + def test_single_quote + doctype = parse(<<-DOCTYPE) + + DOCTYPE + assert_equal("system\"-literal", doctype.system) + end + + def test_double_quote + doctype = parse(<<-DOCTYPE) + + DOCTYPE + assert_equal("system'-literal", doctype.system) + end + end + end end class TestMixed < self @@ -45,6 +215,15 @@ def test_notation_attlist assert_equal([REXML::NotationDecl, REXML::AttlistDecl], doctype.children.collect(&:class)) end + + private + def parse(internal_subset) + super(<<-DOCTYPE) + + DOCTYPE + end end end end diff --git a/test/parse/test_notation_declaration.rb b/test/parse/test_notation_declaration.rb index fbd29e2a..19a0536d 100644 --- a/test/parse/test_notation_declaration.rb +++ b/test/parse/test_notation_declaration.rb @@ -50,7 +50,7 @@ def test_invalid_name Line: 5 Position: 74 Last 80 unconsumed characters: - ]> +'> ]> DETAIL end @@ -61,11 +61,11 @@ def test_no_id_type INTERNAL_SUBSET end assert_equal(<<-DETAIL.chomp, exception.to_s) -Malformed notation declaration: ID type is missing +Malformed notation declaration: invalid ID type Line: 5 Position: 77 Last 80 unconsumed characters: - ]> +> ]> DETAIL end @@ -80,7 +80,7 @@ def test_invalid_id_type Line: 5 Position: 85 Last 80 unconsumed characters: - ]> + INVALID> ]> DETAIL end end @@ -98,7 +98,7 @@ def test_no_literal Line: 5 Position: 84 Last 80 unconsumed characters: - ]> + SYSTEM> ]> DETAIL end @@ -109,11 +109,11 @@ def test_garbage_after_literal INTERNAL_SUBSET end assert_equal(<<-DETAIL.chomp, exception.to_s) -Malformed notation declaration: garbage after system literal +Malformed notation declaration: garbage before end > Line: 5 Position: 103 Last 80 unconsumed characters: - ]> +x'> ]> DETAIL end @@ -145,7 +145,7 @@ def test_content_double_quote Line: 5 Position: 129 Last 80 unconsumed characters: - ]> + PUBLIC 'double quote " is invalid' "system-literal"> ]> DETAIL end @@ -172,11 +172,11 @@ def test_garbage_after_literal INTERNAL_SUBSET end assert_equal(<<-DETAIL.chomp, exception.to_s) -Malformed notation declaration: garbage after system literal +Malformed notation declaration: garbage before end > Line: 5 Position: 123 Last 80 unconsumed characters: - ]> +x'> ]> DETAIL end @@ -229,7 +229,7 @@ def test_no_literal Line: 5 Position: 84 Last 80 unconsumed characters: - ]> + PUBLIC> ]> DETAIL end @@ -244,7 +244,7 @@ def test_literal_content_double_quote Line: 5 Position: 128 Last 80 unconsumed characters: - ]> + PUBLIC 'double quote \" is invalid in PubidLiteral'> ]> DETAIL end @@ -255,11 +255,11 @@ def test_garbage_after_literal INTERNAL_SUBSET end assert_equal(<<-DETAIL.chomp, exception.to_s) -Malformed notation declaration: garbage after public ID literal +Malformed notation declaration: garbage before end > Line: 5 Position: 106 Last 80 unconsumed characters: - ]> +x'> ]> DETAIL end From 3c137eb119550874b2b3e27d12b733ca67033377 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Sun, 28 Feb 2021 06:26:40 +0900 Subject: [PATCH 55/56] Fix a parser bug that some data may be ignored before DOCTYPE HackerOne: HO-1104077 For example, "x 0 #STDERR.puts @source.encoding - @source.read if @source.buffer.size<2 #STDERR.puts "BUFFER = #{@source.buffer.inspect}" if @document_status == nil - #@source.consume( /^\s*/um ) - word = @source.match( /^((?:\s+)|(?:<[^>]*>))/um ) + word = @source.match( /\A((?:\s+)|(?:<[^>]*>))/um ) word = word[1] unless word.nil? #STDERR.puts "WORD = #{word.inspect}" case word @@ -257,18 +255,16 @@ def pull_event @stack << [ :end_doctype ] end return args - when /^\s+/ + when /\A\s+/ else @document_status = :after_doctype - @source.read if @source.buffer.size<2 - md = @source.match(/\s*/um, true) if @source.encoding == "UTF-8" @source.buffer.force_encoding(::Encoding::UTF_8) end end end if @document_status == :in_doctype - md = @source.match(/\s*(.*?>)/um) + md = @source.match(/\A\s*(.*?>)/um) case md[1] when SYSTEMENTITY match = @source.match( SYSTEMENTITY, true )[1] @@ -349,7 +345,11 @@ def pull_event return [ :end_doctype ] end end + if @document_status == :after_doctype + @source.match(/\A\s*/um, true) + end begin + @source.read if @source.buffer.size<2 if @source.buffer[0] == ?< if @source.buffer[1] == ?/ @nsstack.shift @@ -392,6 +392,7 @@ def pull_event unless md raise REXML::ParseException.new("malformed XML: missing tag start", @source) end + @document_status = :in_element prefixes = Set.new prefixes << md[2] if md[2] @nsstack.unshift(curr_ns=Set.new) diff --git a/test/parse/test_processing_instruction.rb b/test/parse/test_processing_instruction.rb index a23513fc..f0c0c24e 100644 --- a/test/parse/test_processing_instruction.rb +++ b/test/parse/test_processing_instruction.rb @@ -20,6 +20,25 @@ def test_no_name DETAIL end + + def test_garbage_text + # TODO: This should be parse error. + # Create test/parse/test_document.rb or something and move this to it. + doc = parse(<<-XML) +x?> + + XML + pi = doc.children[1] + assert_equal([ + "x", + "y\n