brakeman 5.0.0 → 5.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGES.md +9 -0
  3. data/README.md +10 -1
  4. data/bundle/load.rb +1 -1
  5. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/LICENSE.txt +0 -0
  6. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/NEWS.md +37 -0
  7. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/README.md +2 -14
  8. data/bundle/ruby/2.7.0/gems/rexml-3.2.5/lib/rexml.rb +3 -0
  9. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/attlistdecl.rb +0 -0
  10. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/attribute.rb +0 -0
  11. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/cdata.rb +0 -0
  12. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/child.rb +0 -0
  13. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/comment.rb +0 -0
  14. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/doctype.rb +55 -31
  15. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/document.rb +194 -34
  16. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/dtd/attlistdecl.rb +0 -0
  17. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/dtd/dtd.rb +0 -0
  18. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/dtd/elementdecl.rb +0 -0
  19. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/dtd/entitydecl.rb +0 -0
  20. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/dtd/notationdecl.rb +0 -0
  21. data/bundle/ruby/2.7.0/gems/rexml-3.2.5/lib/rexml/element.rb +2599 -0
  22. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/encoding.rb +0 -0
  23. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/entity.rb +0 -0
  24. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/formatters/default.rb +0 -0
  25. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/formatters/pretty.rb +0 -0
  26. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/formatters/transitive.rb +0 -0
  27. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/functions.rb +0 -0
  28. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/instruction.rb +0 -0
  29. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/light/node.rb +0 -8
  30. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/namespace.rb +0 -0
  31. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/node.rb +0 -0
  32. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/output.rb +0 -0
  33. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/parent.rb +0 -0
  34. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/parseexception.rb +0 -0
  35. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/parsers/baseparser.rb +139 -39
  36. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/parsers/lightparser.rb +0 -0
  37. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/parsers/pullparser.rb +0 -0
  38. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/parsers/sax2parser.rb +0 -0
  39. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/parsers/streamparser.rb +0 -0
  40. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/parsers/treeparser.rb +0 -0
  41. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/parsers/ultralightparser.rb +0 -0
  42. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/parsers/xpathparser.rb +25 -11
  43. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/quickpath.rb +0 -0
  44. data/bundle/ruby/2.7.0/gems/rexml-3.2.5/lib/rexml/rexml.rb +37 -0
  45. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/sax2listener.rb +0 -0
  46. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/security.rb +0 -0
  47. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/source.rb +0 -0
  48. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/streamlistener.rb +0 -0
  49. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/text.rb +0 -0
  50. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/undefinednamespaceexception.rb +0 -0
  51. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/validation/relaxng.rb +0 -0
  52. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/validation/validation.rb +0 -0
  53. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/validation/validationexception.rb +0 -0
  54. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/xmldecl.rb +0 -0
  55. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/xmltokens.rb +0 -0
  56. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/xpath.rb +0 -0
  57. data/bundle/ruby/2.7.0/gems/{rexml-3.2.4 → rexml-3.2.5}/lib/rexml/xpath_parser.rb +36 -30
  58. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/debugging.md +133 -0
  59. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby20_parser.rb +2550 -2537
  60. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby20_parser.y +9 -1
  61. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby21_parser.rb +2717 -2709
  62. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby21_parser.y +9 -1
  63. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby22_parser.rb +2662 -2637
  64. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby22_parser.y +9 -1
  65. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby23_parser.rb +2585 -2561
  66. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby23_parser.y +9 -1
  67. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby24_parser.rb +2622 -2607
  68. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby24_parser.y +9 -1
  69. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby25_parser.rb +2612 -2598
  70. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby25_parser.y +9 -1
  71. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby26_parser.rb +2610 -2594
  72. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby26_parser.y +10 -1
  73. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby27_parser.rb +3446 -3312
  74. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby27_parser.y +47 -1
  75. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby_lexer.rb +19 -0
  76. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby_lexer.rex +1 -1
  77. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby_lexer.rex.rb +1 -1
  78. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib/ruby_parser.yy +55 -1
  79. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/tools/munge.rb +2 -2
  80. data/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/tools/ripper.rb +1 -1
  81. data/lib/brakeman.rb +11 -4
  82. data/lib/brakeman/checks/check_mass_assignment.rb +4 -6
  83. data/lib/brakeman/parsers/template_parser.rb +24 -0
  84. data/lib/brakeman/processors/alias_processor.rb +21 -10
  85. data/lib/brakeman/processors/base_processor.rb +4 -4
  86. data/lib/brakeman/processors/lib/rails4_config_processor.rb +2 -1
  87. data/lib/brakeman/version.rb +1 -1
  88. metadata +55 -56
  89. data/bundle/ruby/2.7.0/gems/rexml-3.2.4/Gemfile +0 -6
  90. data/bundle/ruby/2.7.0/gems/rexml-3.2.4/lib/rexml/element.rb +0 -1269
  91. data/bundle/ruby/2.7.0/gems/rexml-3.2.4/lib/rexml/rexml.rb +0 -32
  92. data/bundle/ruby/2.7.0/gems/rexml-3.2.4/rexml.gemspec +0 -84
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 1d660b98db2252a6aa69d39bb56c6950aa7d9713f10831807d6ab837df54657d
4
- data.tar.gz: 6999959ba9f8380f36c1d999e04b0d79e48ea9536fd9820485c4960bce769d60
3
+ metadata.gz: 4b7adec7f0012e7c4b5605dc81db6722b1b6c711cafc12ab60ddd8f8c969309e
4
+ data.tar.gz: 602f31369d55351c1ec459de946e555710e85f77578f2711dfb6886bd4781757
5
5
  SHA512:
6
- metadata.gz: b6738f567478a47fd36de992706968c1c42a237dd97d4527434a60fa9ddea5b7a7acb54d8b72e6bc282fd1805126953a358e399a19dab4c0c5e7fd92b4a857ed
7
- data.tar.gz: 43f16437835dabb65a7b73981779460e7648e1fa2ba772320132e7500af55c8861effda46f3b181310bdd753dbf1c59af12b3ecdfed5844505e2cf5cbff866fa
6
+ metadata.gz: 603312f7dafcb44a28d8f1d74c0088d86c3b82263ff413c41a855945dc4421f231548496ae98e99bb080f9cc947a9314f0997a771115e013859364f96763f403
7
+ data.tar.gz: 2fd04bd7ea6e584fe05c60002a369c27945a6fe90c805b20ce15c3290f474437fdf67a2b7e4d59bf373ac7ce3d678d3a0684edc55b211c86a1e7edf4ff40c27d
data/CHANGES.md CHANGED
@@ -1,3 +1,12 @@
1
+ # 5.0.1 - 2021-04-27
2
+
3
+ * Detect `::Rails.application.configure` too
4
+ * Set more line numbers on Sexps
5
+ * Support loading `slim/smart`
6
+ * Don't fail if $HOME/$USER are not defined
7
+ * Always ignore slice/only calls for mass assignment
8
+ * Convert splat array arguments to arguments
9
+
1
10
  # 5.0.0 - 2021-01-26
2
11
 
3
12
  * Ignore `uuid` as a safe attribute
data/README.md CHANGED
@@ -159,7 +159,16 @@ The `-w` switch takes a number from 1 to 3, with 1 being low (all warnings) and
159
159
 
160
160
  # Configuration files
161
161
 
162
- Brakeman options can stored and read from YAML files. To simplify the process of writing a configuration file, the `-C` option will output the currently set options.
162
+ Brakeman options can be stored and read from YAML files.
163
+
164
+ To simplify the process of writing a configuration file, the `-C` option will output the currently set options:
165
+
166
+ ```sh
167
+ $ brakeman -C --skip-files plugins/
168
+ ---
169
+ :skip_files:
170
+ - plugins/
171
+ ```
163
172
 
164
173
  Options passed in on the commandline have priority over configuration files.
165
174
 
data/bundle/load.rb CHANGED
@@ -7,9 +7,9 @@ $:.unshift "#{path}/bundle/ruby/2.7.0/gems/sexp_processor-4.15.2/lib"
7
7
  $:.unshift "#{path}/bundle/ruby/2.7.0/gems/highline-2.0.3/lib"
8
8
  $:.unshift "#{path}/bundle/ruby/2.7.0/gems/ruby2ruby-2.4.4/lib"
9
9
  $:.unshift "#{path}/bundle/ruby/2.7.0/gems/terminal-table-1.8.0/lib"
10
- $:.unshift "#{path}/bundle/ruby/2.7.0/gems/rexml-3.2.4/lib"
11
10
  $:.unshift "#{path}/bundle/ruby/2.7.0/gems/ruby_parser-legacy-1.0.0/lib"
12
11
  $:.unshift "#{path}/bundle/ruby/2.7.0/gems/erubis-2.7.0/lib"
13
12
  $:.unshift "#{path}/bundle/ruby/2.7.0/gems/haml-5.2.1/lib"
13
+ $:.unshift "#{path}/bundle/ruby/2.7.0/gems/rexml-3.2.5/lib"
14
14
  $:.unshift "#{path}/bundle/ruby/2.7.0/gems/ruby_parser-3.15.1/lib"
15
15
  $:.unshift "#{path}/bundle/ruby/2.7.0/gems/safe_yaml-1.0.5/lib"
@@ -1,5 +1,42 @@
1
1
  # News
2
2
 
3
+ ## 3.2.5 - 2021-04-05 {#version-3-2-5}
4
+
5
+ ### Improvements
6
+
7
+ * Add more validations to XPath parser.
8
+
9
+ * `require "rexml/docuemnt"` by default.
10
+ [GitHub#36][Patch by Koichi ITO]
11
+
12
+ * Don't add `#dcloe` method to core classes globally.
13
+ [GitHub#37][Patch by Akira Matsuda]
14
+
15
+ * Add more documentations.
16
+ [Patch by Burdette Lamar]
17
+
18
+ * Added `REXML::Elements#parent`.
19
+ [GitHub#52][Patch by Burdette Lamar]
20
+
21
+ ### Fixes
22
+
23
+ * Fixed a bug that `REXML::DocType#clone` doesn't copy external ID
24
+ information.
25
+
26
+ * Fixed round-trip vulnerability bugs.
27
+ See also: https://www.ruby-lang.org/en/news/2021/04/05/xml-round-trip-vulnerability-in-rexml-cve-2021-28965/
28
+ [HackerOne#1104077][CVE-2021-28965][Reported by Juho Nurminen]
29
+
30
+ ### Thanks
31
+
32
+ * Koichi ITO
33
+
34
+ * Akira Matsuda
35
+
36
+ * Burdette Lamar
37
+
38
+ * Juho Nurminen
39
+
3
40
  ## 3.2.4 - 2020-01-31 {#version-3-2-4}
4
41
 
5
42
  ### Improvements
@@ -4,21 +4,9 @@ REXML was inspired by the Electric XML library for Java, which features an easy-
4
4
 
5
5
  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.
6
6
 
7
- ## Installation
7
+ ## API
8
8
 
9
- Add this line to your application's Gemfile:
10
-
11
- ```ruby
12
- gem 'rexml'
13
- ```
14
-
15
- And then execute:
16
-
17
- $ bundle
18
-
19
- Or install it yourself as:
20
-
21
- $ gem install rexml
9
+ See the {API documentation}[https://ruby.github.io/rexml/]
22
10
 
23
11
  ## Usage
24
12
 
@@ -0,0 +1,3 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "rexml/document"
@@ -7,6 +7,44 @@ require_relative 'attlistdecl'
7
7
  require_relative 'xmltokens'
8
8
 
9
9
  module REXML
10
+ class ReferenceWriter
11
+ def initialize(id_type,
12
+ public_id_literal,
13
+ system_literal,
14
+ context=nil)
15
+ @id_type = id_type
16
+ @public_id_literal = public_id_literal
17
+ @system_literal = system_literal
18
+ if context and context[:prologue_quote] == :apostrophe
19
+ @default_quote = "'"
20
+ else
21
+ @default_quote = "\""
22
+ end
23
+ end
24
+
25
+ def write(output)
26
+ output << " #{@id_type}"
27
+ if @public_id_literal
28
+ if @public_id_literal.include?("'")
29
+ quote = "\""
30
+ else
31
+ quote = @default_quote
32
+ end
33
+ output << " #{quote}#{@public_id_literal}#{quote}"
34
+ end
35
+ if @system_literal
36
+ if @system_literal.include?("'")
37
+ quote = "\""
38
+ elsif @system_literal.include?("\"")
39
+ quote = "'"
40
+ else
41
+ quote = @default_quote
42
+ end
43
+ output << " #{quote}#{@system_literal}#{quote}"
44
+ end
45
+ end
46
+ end
47
+
10
48
  # Represents an XML DOCTYPE declaration; that is, the contents of <!DOCTYPE
11
49
  # ... >. DOCTYPES can be used to declare the DTD of a document, as well as
12
50
  # being used to declare entities used in the document.
@@ -50,6 +88,8 @@ module REXML
50
88
  super( parent )
51
89
  @name = first.name
52
90
  @external_id = first.external_id
91
+ @long_name = first.instance_variable_get(:@long_name)
92
+ @uri = first.instance_variable_get(:@uri)
53
93
  elsif first.kind_of? Array
54
94
  super( parent )
55
95
  @name = first[0]
@@ -108,19 +148,17 @@ module REXML
108
148
  # Ignored
109
149
  def write( output, indent=0, transitive=false, ie_hack=false )
110
150
  f = REXML::Formatters::Default.new
111
- c = context
112
- if c and c[:prologue_quote] == :apostrophe
113
- quote = "'"
114
- else
115
- quote = "\""
116
- end
117
151
  indent( output, indent )
118
152
  output << START
119
153
  output << ' '
120
154
  output << @name
121
- output << " #{@external_id}" if @external_id
122
- output << " #{quote}#{@long_name}#{quote}" if @long_name
123
- output << " #{quote}#{@uri}#{quote}" if @uri
155
+ if @external_id
156
+ reference_writer = ReferenceWriter.new(@external_id,
157
+ @long_name,
158
+ @uri,
159
+ context)
160
+ reference_writer.write(output)
161
+ end
124
162
  unless @children.empty?
125
163
  output << ' ['
126
164
  @children.each { |child|
@@ -159,7 +197,7 @@ module REXML
159
197
  when "SYSTEM"
160
198
  nil
161
199
  when "PUBLIC"
162
- strip_quotes(@long_name)
200
+ @long_name
163
201
  end
164
202
  end
165
203
 
@@ -169,9 +207,9 @@ module REXML
169
207
  def system
170
208
  case @external_id
171
209
  when "SYSTEM"
172
- strip_quotes(@long_name)
210
+ @long_name
173
211
  when "PUBLIC"
174
- @uri.kind_of?(String) ? strip_quotes(@uri) : nil
212
+ @uri.kind_of?(String) ? @uri : nil
175
213
  end
176
214
  end
177
215
 
@@ -193,15 +231,6 @@ module REXML
193
231
  notation_decl.name == name
194
232
  }
195
233
  end
196
-
197
- private
198
-
199
- # Method contributed by Henrik Martensson
200
- def strip_quotes(quoted_string)
201
- quoted_string =~ /^[\'\"].*[\'\"]$/ ?
202
- quoted_string[1, quoted_string.length-2] :
203
- quoted_string
204
- end
205
234
  end
206
235
 
207
236
  # We don't really handle any of these since we're not a validating
@@ -259,16 +288,11 @@ module REXML
259
288
  end
260
289
 
261
290
  def to_s
262
- c = nil
263
- c = parent.context if parent
264
- if c and c[:prologue_quote] == :apostrophe
265
- quote = "'"
266
- else
267
- quote = "\""
268
- end
269
- notation = "<!NOTATION #{@name} #{@middle}"
270
- notation << " #{quote}#{@public}#{quote}" if @public
271
- notation << " #{quote}#{@system}#{quote}" if @system
291
+ context = nil
292
+ context = parent.context if parent
293
+ notation = "<!NOTATION #{@name}"
294
+ reference_writer = ReferenceWriter.new(@middle, @public, @system, context)
295
+ reference_writer.write(notation)
272
296
  notation << ">"
273
297
  notation
274
298
  end
@@ -14,25 +14,81 @@ require_relative "parsers/streamparser"
14
14
  require_relative "parsers/treeparser"
15
15
 
16
16
  module REXML
17
- # Represents a full XML document, including PIs, a doctype, etc. A
18
- # Document has a single child that can be accessed by root().
19
- # Note that if you want to have an XML declaration written for a document
20
- # you create, you must add one; REXML documents do not write a default
21
- # declaration for you. See |DECLARATION| and |write|.
17
+ # Represents an XML document.
18
+ #
19
+ # A document may have:
20
+ #
21
+ # - A single child that may be accessed via method #root.
22
+ # - An XML declaration.
23
+ # - A document type.
24
+ # - Processing instructions.
25
+ #
26
+ # == In a Hurry?
27
+ #
28
+ # If you're somewhat familiar with XML
29
+ # and have a particular task in mind,
30
+ # you may want to see the
31
+ # {tasks pages}[../doc/rexml/tasks/tocs/master_toc_rdoc.html],
32
+ # and in particular, the
33
+ # {tasks page for documents}[../doc/rexml/tasks/tocs/document_toc_rdoc.html].
34
+ #
22
35
  class Document < Element
23
- # A convenient default XML declaration. If you want an XML declaration,
24
- # the easiest way to add one is mydoc << Document::DECLARATION
25
- # +DEPRECATED+
26
- # Use: mydoc << XMLDecl.default
36
+ # A convenient default XML declaration. Use:
37
+ #
38
+ # mydoc << XMLDecl.default
39
+ #
27
40
  DECLARATION = XMLDecl.default
28
41
 
29
- # Constructor
30
- # @param source if supplied, must be a Document, String, or IO.
31
- # Documents have their context and Element attributes cloned.
32
- # Strings are expected to be valid XML documents. IOs are expected
33
- # to be sources of valid XML documents.
34
- # @param context if supplied, contains the context of the document;
35
- # this should be a Hash.
42
+ # :call-seq:
43
+ # new(string = nil, context = {}) -> new_document
44
+ # new(io_stream = nil, context = {}) -> new_document
45
+ # new(document = nil, context = {}) -> new_document
46
+ #
47
+ # Returns a new \REXML::Document object.
48
+ #
49
+ # When no arguments are given,
50
+ # returns an empty document:
51
+ #
52
+ # d = REXML::Document.new
53
+ # d.to_s # => ""
54
+ #
55
+ # When argument +string+ is given, it must be a string
56
+ # containing a valid XML document:
57
+ #
58
+ # xml_string = '<root><foo>Foo</foo><bar>Bar</bar></root>'
59
+ # d = REXML::Document.new(xml_string)
60
+ # d.to_s # => "<root><foo>Foo</foo><bar>Bar</bar></root>"
61
+ #
62
+ # When argument +io_stream+ is given, it must be an \IO object
63
+ # that is opened for reading, and when read must return a valid XML document:
64
+ #
65
+ # File.write('t.xml', xml_string)
66
+ # d = File.open('t.xml', 'r') do |io|
67
+ # REXML::Document.new(io)
68
+ # end
69
+ # d.to_s # => "<root><foo>Foo</foo><bar>Bar</bar></root>"
70
+ #
71
+ # When argument +document+ is given, it must be an existing
72
+ # document object, whose context and attributes (but not chidren)
73
+ # are cloned into the new document:
74
+ #
75
+ # d = REXML::Document.new(xml_string)
76
+ # d.children # => [<root> ... </>]
77
+ # d.context = {raw: :all, compress_whitespace: :all}
78
+ # d.add_attributes({'bar' => 0, 'baz' => 1})
79
+ # d1 = REXML::Document.new(d)
80
+ # d1.children # => []
81
+ # d1.context # => {:raw=>:all, :compress_whitespace=>:all}
82
+ # d1.attributes # => {"bar"=>bar='0', "baz"=>baz='1'}
83
+ #
84
+ # When argument +context+ is given, it must be a hash
85
+ # containing context entries for the document;
86
+ # see {Element Context}[../doc/rexml/context_rdoc.html]:
87
+ #
88
+ # context = {raw: :all, compress_whitespace: :all}
89
+ # d = REXML::Document.new(xml_string, context)
90
+ # d.context # => {:raw=>:all, :compress_whitespace=>:all}
91
+ #
36
92
  def initialize( source = nil, context = {} )
37
93
  @entity_expansion_count = 0
38
94
  super()
@@ -46,26 +102,71 @@ module REXML
46
102
  end
47
103
  end
48
104
 
105
+ # :call-seq:
106
+ # node_type -> :document
107
+ #
108
+ # Returns the symbol +:document+.
109
+ #
49
110
  def node_type
50
111
  :document
51
112
  end
52
113
 
53
- # Should be obvious
114
+ # :call-seq:
115
+ # clone -> new_document
116
+ #
117
+ # Returns the new document resulting from executing
118
+ # <tt>Document.new(self)</tt>. See Document.new.
119
+ #
54
120
  def clone
55
121
  Document.new self
56
122
  end
57
123
 
58
- # According to the XML spec, a root node has no expanded name
124
+ # :call-seq:
125
+ # expanded_name -> empty_string
126
+ #
127
+ # Returns an empty string.
128
+ #
59
129
  def expanded_name
60
130
  ''
61
131
  #d = doc_type
62
132
  #d ? d.name : "UNDEFINED"
63
133
  end
64
-
65
134
  alias :name :expanded_name
66
135
 
67
- # We override this, because XMLDecls and DocTypes must go at the start
68
- # of the document
136
+ # :call-seq:
137
+ # add(xml_decl) -> self
138
+ # add(doc_type) -> self
139
+ # add(object) -> self
140
+ #
141
+ # Adds an object to the document; returns +self+.
142
+ #
143
+ # When argument +xml_decl+ is given,
144
+ # it must be an REXML::XMLDecl object,
145
+ # which becomes the XML declaration for the document,
146
+ # replacing the previous XML declaration if any:
147
+ #
148
+ # d = REXML::Document.new
149
+ # d.xml_decl.to_s # => ""
150
+ # d.add(REXML::XMLDecl.new('2.0'))
151
+ # d.xml_decl.to_s # => "<?xml version='2.0'?>"
152
+ #
153
+ # When argument +doc_type+ is given,
154
+ # it must be an REXML::DocType object,
155
+ # which becomes the document type for the document,
156
+ # replacing the previous document type, if any:
157
+ #
158
+ # d = REXML::Document.new
159
+ # d.doctype.to_s # => ""
160
+ # d.add(REXML::DocType.new('foo'))
161
+ # d.doctype.to_s # => "<!DOCTYPE foo>"
162
+ #
163
+ # When argument +object+ (not an REXML::XMLDecl or REXML::DocType object)
164
+ # is given it is added as the last child:
165
+ #
166
+ # d = REXML::Document.new
167
+ # d.add(REXML::Element.new('foo'))
168
+ # d.to_s # => "<foo/>"
169
+ #
69
170
  def add( child )
70
171
  if child.kind_of? XMLDecl
71
172
  if @children[0].kind_of? XMLDecl
@@ -99,49 +200,108 @@ module REXML
99
200
  end
100
201
  alias :<< :add
101
202
 
203
+ # :call-seq:
204
+ # add_element(name_or_element = nil, attributes = nil) -> new_element
205
+ #
206
+ # Adds an element to the document by calling REXML::Element.add_element:
207
+ #
208
+ # REXML::Element.add_element(name_or_element, attributes)
102
209
  def add_element(arg=nil, arg2=nil)
103
210
  rv = super
104
211
  raise "attempted adding second root element to document" if @elements.size > 1
105
212
  rv
106
213
  end
107
214
 
108
- # @return the root Element of the document, or nil if this document
109
- # has no children.
215
+ # :call-seq:
216
+ # root -> root_element or nil
217
+ #
218
+ # Returns the root element of the document, if it exists, otherwise +nil+:
219
+ #
220
+ # d = REXML::Document.new('<root></root>')
221
+ # d.root # => <root/>
222
+ # d = REXML::Document.new('')
223
+ # d.root # => nil
224
+ #
110
225
  def root
111
226
  elements[1]
112
227
  #self
113
228
  #@children.find { |item| item.kind_of? Element }
114
229
  end
115
230
 
116
- # @return the DocType child of the document, if one exists,
117
- # and nil otherwise.
231
+ # :call-seq:
232
+ # doctype -> doc_type or nil
233
+ #
234
+ # Returns the DocType object for the document, if it exists, otherwise +nil+:
235
+ #
236
+ # d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">')
237
+ # d.doctype.class # => REXML::DocType
238
+ # d = REXML::Document.new('')
239
+ # d.doctype.class # => nil
240
+ #
118
241
  def doctype
119
242
  @children.find { |item| item.kind_of? DocType }
120
243
  end
121
244
 
122
- # @return the XMLDecl of this document; if no XMLDecl has been
123
- # set, the default declaration is returned.
245
+ # :call-seq:
246
+ # xml_decl -> xml_decl
247
+ #
248
+ # Returns the XMLDecl object for the document, if it exists,
249
+ # otherwise the default XMLDecl object:
250
+ #
251
+ # d = REXML::Document.new('<?xml version="1.0" encoding="UTF-8"?>')
252
+ # d.xml_decl.class # => REXML::XMLDecl
253
+ # d.xml_decl.to_s # => "<?xml version='1.0' encoding='UTF-8'?>"
254
+ # d = REXML::Document.new('')
255
+ # d.xml_decl.class # => REXML::XMLDecl
256
+ # d.xml_decl.to_s # => ""
257
+ #
124
258
  def xml_decl
125
259
  rv = @children[0]
126
260
  return rv if rv.kind_of? XMLDecl
127
261
  @children.unshift(XMLDecl.default)[0]
128
262
  end
129
263
 
130
- # @return the XMLDecl version of this document as a String.
131
- # If no XMLDecl has been set, returns the default version.
264
+ # :call-seq:
265
+ # version -> version_string
266
+ #
267
+ # Returns the XMLDecl version of this document as a string,
268
+ # if it has been set, otherwise the default version:
269
+ #
270
+ # d = REXML::Document.new('<?xml version="2.0" encoding="UTF-8"?>')
271
+ # d.version # => "2.0"
272
+ # d = REXML::Document.new('')
273
+ # d.version # => "1.0"
274
+ #
132
275
  def version
133
276
  xml_decl().version
134
277
  end
135
278
 
136
- # @return the XMLDecl encoding of this document as an
137
- # Encoding object.
138
- # If no XMLDecl has been set, returns the default encoding.
279
+ # :call-seq:
280
+ # encoding -> encoding_string
281
+ #
282
+ # Returns the XMLDecl encoding of the document,
283
+ # if it has been set, otherwise the default encoding:
284
+ #
285
+ # d = REXML::Document.new('<?xml version="1.0" encoding="UTF-16"?>')
286
+ # d.encoding # => "UTF-16"
287
+ # d = REXML::Document.new('')
288
+ # d.encoding # => "UTF-8"
289
+ #
139
290
  def encoding
140
291
  xml_decl().encoding
141
292
  end
142
293
 
143
- # @return the XMLDecl standalone value of this document as a String.
144
- # If no XMLDecl has been set, returns the default setting.
294
+ # :call-seq:
295
+ # stand_alone?
296
+ #
297
+ # Returns the XMLDecl standalone value of the document as a string,
298
+ # if it has been set, otherwise the default standalone value:
299
+ #
300
+ # d = REXML::Document.new('<?xml standalone="yes"?>')
301
+ # d.stand_alone? # => "yes"
302
+ # d = REXML::Document.new('')
303
+ # d.stand_alone? # => nil
304
+ #
145
305
  def stand_alone?
146
306
  xml_decl().stand_alone?
147
307
  end