cgi 0.4.2 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2223dc33d62279bcf8cb78f68d8fb46f22c8d9e396243e22d43ded77291dfe5
-  data.tar.gz: 70b263423e005129ac529dd41f59324accedd2cf6fd8c260965286ff0f03a399
+  metadata.gz: 0f7c88bb08e51fd6b7abd1855b87d05c8af6b8f4e89865f0315f512badcddcb9
+  data.tar.gz: fbe294b63d488ae16c123d325b2251a9561da5b474105a0ecbb1ecd880c4cdb6
 SHA512:
-  metadata.gz: 9d63be598547392b545cabca27ed6f6765ffa9d8e778335118fa29592c36d8276cc68af052db7abe8e2373c8818072523df6e6aaf65393d09c7c5d16600af6cd
-  data.tar.gz: 5a27bb456ab0ecee2e504b737f1b7e8f8e2dd3d56f253fd9c08b5ef42fb145dbc1fbb5e3cec9e98866b19d42aa63d58b4b36affa94a25be9e9f46fa2bc03c942
+  metadata.gz: 9d4837752a514f02e88f8f3673fa0b0b9a31195df062d79c9d5b51175288f5053409fc337b1613ad27393b92c4394663d4cfd355d30c555b565f79a9102e2feb
+  data.tar.gz: 0c465bae726d291b6829b6f0bf9f86d05976bf61529dc8190da4fd73022b37924c7901c3b29fb3cddb7760829aa24ac5cd6999c1f1ad9b4ec825fe0afc63ef19

data/README.md

@@ -32,21 +32,19 @@ Or install it yourself as:
 
 ### Get form values
 
+Given a form with the content `field_name=123`:
+
 ```ruby
 require "cgi"
 cgi = CGI.new
-value = cgi['field_name']   # <== value string for 'field_name'
-  # if not 'field_name' included, then return "".
-fields = cgi.keys            # <== array of field names
-
-# returns true if form has 'field_name'
-cgi.has_key?('field_name')
-cgi.has_key?('field_name')
-cgi.include?('field_name')
-```
+value = cgi['field_name'] # => "123"
+cgi['flowerpot'] # => ""
+fields = cgi.keys # => [ "field_name" ]
 
-CAUTION! cgi['field_name'] returned an Array with the old
-cgi.rb(included in Ruby 1.6)
+cgi.has_key?('field_name') # => true
+cgi.include?('field_name') # => true
+cgi.include?('flowerpot') # => false
+```
 
 ### Get form values as hash
 

data/ext/cgi/escape/escape.c

@@ -8,7 +8,7 @@ RUBY_EXTERN const signed char ruby_digit36_to_number_table[];
 #define upper_hexdigits (ruby_hexdigits+16)
 #define char_to_number(c) ruby_digit36_to_number_table[(unsigned char)(c)]
 
-static VALUE rb_cCGI, rb_mUtil, rb_mEscape;
+static VALUE rb_cCGI, rb_mEscape, rb_mEscapeExt;
 static ID id_accept_charset;
 
 #define HTML_ESCAPE_MAX_LEN 6
@@ -45,6 +45,7 @@ escaped_length(VALUE str)
 static VALUE
 optimized_escape_html(VALUE str)
 {
+    VALUE escaped;
     VALUE vbuf;
     char *buf = ALLOCV_N(char, vbuf, escaped_length(str));
     const char *cstr = RSTRING_PTR(str);
@@ -63,7 +64,6 @@ optimized_escape_html(VALUE str)
         }
     }
 
-    VALUE escaped;
     if (RSTRING_LEN(str) < (dest - buf)) {
         escaped = rb_str_new(buf, dest - buf);
         preserve_original_state(str, escaped);
@@ -471,17 +471,17 @@ Init_escape(void)
 void
 InitVM_escape(void)
 {
-    rb_cCGI    = rb_define_class("CGI", rb_cObject);
-    rb_mEscape = rb_define_module_under(rb_cCGI, "Escape");
-    rb_mUtil   = rb_define_module_under(rb_cCGI, "Util");
-    rb_define_method(rb_mEscape, "escapeHTML", cgiesc_escape_html, 1);
-    rb_define_method(rb_mEscape, "unescapeHTML", cgiesc_unescape_html, 1);
-    rb_define_method(rb_mEscape, "escapeURIComponent", cgiesc_escape_uri_component, 1);
-    rb_define_alias(rb_mEscape, "escape_uri_component", "escapeURIComponent");
-    rb_define_method(rb_mEscape, "unescapeURIComponent", cgiesc_unescape_uri_component, -1);
-    rb_define_alias(rb_mEscape, "unescape_uri_component", "unescapeURIComponent");
-    rb_define_method(rb_mEscape, "escape", cgiesc_escape, 1);
-    rb_define_method(rb_mEscape, "unescape", cgiesc_unescape, -1);
-    rb_prepend_module(rb_mUtil, rb_mEscape);
-    rb_extend_object(rb_cCGI, rb_mEscape);
+    rb_cCGI       = rb_define_class("CGI", rb_cObject);
+    rb_mEscapeExt = rb_define_module_under(rb_cCGI, "EscapeExt");
+    rb_mEscape    = rb_define_module_under(rb_cCGI, "Escape");
+    rb_define_method(rb_mEscapeExt, "escapeHTML", cgiesc_escape_html, 1);
+    rb_define_method(rb_mEscapeExt, "unescapeHTML", cgiesc_unescape_html, 1);
+    rb_define_method(rb_mEscapeExt, "escapeURIComponent", cgiesc_escape_uri_component, 1);
+    rb_define_alias(rb_mEscapeExt, "escape_uri_component", "escapeURIComponent");
+    rb_define_method(rb_mEscapeExt, "unescapeURIComponent", cgiesc_unescape_uri_component, -1);
+    rb_define_alias(rb_mEscapeExt, "unescape_uri_component", "unescapeURIComponent");
+    rb_define_method(rb_mEscapeExt, "escape", cgiesc_escape, 1);
+    rb_define_method(rb_mEscapeExt, "unescape", cgiesc_unescape, -1);
+    rb_prepend_module(rb_mEscape, rb_mEscapeExt);
+    rb_extend_object(rb_cCGI, rb_mEscapeExt);
 }

data/lib/cgi/cookie.rb

@@ -40,9 +40,11 @@ class CGI
   class Cookie < Array
     @@accept_charset="UTF-8" unless defined?(@@accept_charset)
 
+    # :stopdoc:
     TOKEN_RE = %r"\A[[!-~]&&[^()<>@,;:\\\"/?=\[\]{}]]+\z"
     PATH_VALUE_RE = %r"\A[[ -~]&&[^;]]*\z"
     DOMAIN_VALUE_RE = %r"\A\.?(?<label>(?!-)[-A-Za-z0-9]+(?<!-))(?:\.\g<label>)*\z"
+    # :startdoc:
 
     # Create a new CGI::Cookie object.
     #

data/lib/cgi/core.rb

@@ -4,12 +4,12 @@
 # generating HTTP responses.
 #++
 class CGI
-  unless const_defined?(:Util)
-    module Util
+  unless const_defined?(:Escape)
+    module Escape
       @@accept_charset = "UTF-8" # :nodoc:
     end
-    include Util
-    extend Util
+    include Escape
+    extend Escape
   end
 
   $CGI_ENV = ENV    # for FCGI support
@@ -384,11 +384,14 @@ class CGI
     stdoutput.print(*options)
   end
 
-  # Parse an HTTP query string into a hash of key=>value pairs.
+  # :call-seq:
+  #    CGI.parse(query_string) -> hash
+  #
+  # Returns a new hash built from name/value pairs in the given +query_string+:
   #
-  #   params = CGI.parse("query_string")
-  #     # {"name1" => ["value1", "value2", ...],
-  #     #  "name2" => ["value1", "value2", ...], ... }
+  #   query = 'foo=0&bar=1&foo=2&bar=3'
+  #   CGI.parse(query)
+  #   # => {"foo" => ["0", "2"], "bar" => ["1", "3"]}
   #
   def self.parse(query)
     params = {}
@@ -629,8 +632,8 @@ class CGI
       string = unless ARGV.empty?
         ARGV.join(' ')
       else
-        if STDIN.tty?
-          STDERR.print(
+        if stdinput.tty?
+          $stderr.print(
             %|(offline mode: enter name=value pairs on standard input)\n|
           )
         end
@@ -778,75 +781,152 @@ class CGI
   #
   @@max_multipart_length= 128 * 1024 * 1024
 
-  # Create a new CGI instance.
-  #
   # :call-seq:
-  #   CGI.new(tag_maker) { block }
-  #   CGI.new(options_hash = {}) { block }
+  #   CGI.new(options = {}) -> new_cgi
+  #   CGI.new(tag_maker) -> new_cgi
+  #   CGI.new(options = {}) {|name, value| ... } -> new_cgi
+  #   CGI.new(tag_maker) {|name, value| ... } -> new_cgi
+  #
+  # Returns a new \CGI object.
+  #
+  # The behavior of this method depends _strongly_ on whether it is called
+  # within a standard \CGI call environment;
+  # that is, whether <tt>ENV['REQUEST_METHOD']</tt> is defined.
+  #
+  # <b>Within a Standard Call Environment</b>
+  #
+  # This section assumes that <tt>ENV['REQUEST_METHOD']</tt> is defined;
+  # for example:
+  #
+  #   ENV['REQUEST_METHOD'] # => "GET"
+  #
+  # With no argument and no block given, returns a new \CGI object with default values:
+  #
+  #   cgi = CGI.new
+  #   puts cgi.pretty_inspect
+  #   #<CGI:0x000002b0ea237bc8
+  #   @accept_charset=#<Encoding:UTF-8>,
+  #   @accept_charset_error_block=nil,
+  #   @cookies={},
+  #   @max_multipart_length=134217728,
+  #   @multipart=false,
+  #   @output_cookies=nil,
+  #   @output_hidden=nil,
+  #   @params={}>
+  #
+  # With hash argument +options+ given and no block given,
+  # returns a new \CGI object with the given options.
+  #
+  # The options may be:
+  #
+  # - <tt>accept_charset: _encoding_</tt>:
+  #   specifies the encoding of the received query string.
+  #
+  #   Value  _encoding_ may be
+  #   an {Encoding object}[https://docs.ruby-lang.org/en/master/encodings_rdoc.html#label-Encoding+Objects]
+  #   or an {encoding name}[https://docs.ruby-lang.org/en/master/encodings_rdoc.html#label-Names+and+Aliases]:
+  #
+  #     CGI.new(accept_charset: 'EUC-JP')
+  #
+  #   If the option is not given,
+  #   the default value is the class default encoding.
+  #
+  #   <em>Note:</em> The <tt>accept_charset</tt> method returns the HTTP Accept-Charset
+  #   header value, not the configured encoding. The configured encoding is used
+  #   internally for query string parsing.
+  #
+  # - <tt>max_multipart_length: _size_</tt>:
+  #   specifies maximum size (in bytes) of multipart data.
+  #
+  #   The _size_ may be:
+  #
+  #   - A positive integer.
+  #
+  #       CGI.new(max_multipart_length: 1024 * 1024)
+  #
+  #
+  #   - A lambda to be evaluated when the request is parsed.
+  #     This is useful when determining whether to accept multipart data
+  #     (e.g. by consulting a registered user's upload allowance).
+  #
+  #       CGI.new(max_multipart_length: -> {check_filesystem})
+  #
+  #   If the option is not given, the default is +134217728+, specifying a maximum size of 128 megabytes.
+#
+#   <em>Note:</em> This option configures internal behavior only.
+#   There is no public method to retrieve this value after initialization.
+  #
+  # - <tt>tag_maker: _html_version_</tt>:
+  #   specifies which version of HTML to use in generating tags.
+  #
+  #   Value _html_version_ may be one of:
+  #
+  #   - <tt>'html3'</tt>: {HTML version 3}[https://en.wikipedia.org/wiki/HTML#HTML_3].
+  #   - <tt>'html4'</tt>: {HTML version 4}[https://en.wikipedia.org/wiki/HTML#HTML_4].
+  #   - <tt>'html4Tr'</tt>: HTML 4.0 Transitional.
+  #   - <tt>'html4Fr'</tt>: HTML 4.0 with Framesets.
+  #   - <tt>'html5'</tt>: {HTML version 5}[https://en.wikipedia.org/wiki/HTML#HTML_5].
   #
+  #   Example:
   #
-  # <tt>tag_maker</tt>::
-  #   This is the same as using the +options_hash+ form with the value <tt>{
-  #   :tag_maker => tag_maker }</tt> Note that it is recommended to use the
-  #   +options_hash+ form, since it also allows you specify the charset you
-  #   will accept.
-  # <tt>options_hash</tt>::
-  #   A Hash that recognizes three options:
+  #     CGI.new(tag_maker: 'html5')
   #
-  #   <tt>:accept_charset</tt>::
-  #     specifies encoding of received query string.  If omitted,
-  #     <tt>@@accept_charset</tt> is used.  If the encoding is not valid, a
-  #     CGI::InvalidEncoding will be raised.
+  #   If the option is not given,
+  #   no HTML generation methods are loaded.
   #
-  #     Example. Suppose <tt>@@accept_charset</tt> is "UTF-8"
+  # With string argument +tag_maker+ given as _tag_maker_ and no block given,
+  # equivalent to <tt>CGI.new(tag_maker: _tag_maker_)</tt>:
   #
-  #     when not specified:
+  #   CGI.new('html5')
   #
-  #         cgi=CGI.new      # @accept_charset # => "UTF-8"
+  # <b>Outside a Standard Call Environment</b>
   #
-  #     when specified as "EUC-JP":
+  # This section assumes that <tt>ENV['REQUEST_METHOD']</tt> is not defined;
+  # for example:
   #
-  #         cgi=CGI.new(:accept_charset => "EUC-JP") # => "EUC-JP"
+  #   ENV['REQUEST_METHOD'] # => nil
   #
-  #   <tt>:tag_maker</tt>::
-  #     String that specifies which version of the HTML generation methods to
-  #     use.  If not specified, no HTML generation methods will be loaded.
+  # In this mode, the method reads its parameters
+  # from the command line or (failing that) from standard input;
+  # returns a new \CGI object.
   #
-  #     The following values are supported:
+  # Otherwise, cookies and other parameters are parsed automatically from the standard CGI locations,
+  # which vary according to the request method.
   #
-  #     "html3":: HTML 3.x
-  #     "html4":: HTML 4.0
-  #     "html4Tr":: HTML 4.0 Transitional
-  #     "html4Fr":: HTML 4.0 with Framesets
-  #     "html5":: HTML 5
+  # <b>Options vs Public Methods</b>
   #
-  #   <tt>:max_multipart_length</tt>::
-  #     Specifies maximum length of multipart data. Can be an Integer scalar or
-  #     a lambda, that will be evaluated when the request is parsed. This
-  #     allows more complex logic to be set when determining whether to accept
-  #     multipart data (e.g. consult a registered users upload allowance)
+  # Some initialization options configure internal behavior only and do not provide
+  # corresponding public getter methods:
   #
-  #     Default is 128 * 1024 * 1024 bytes
+  # - <tt>accept_charset</tt>: Configures internal encoding for parsing.
+  #   The <tt>accept_charset</tt> method returns the HTTP Accept-Charset header.
+  # - <tt>max_multipart_length</tt>: Configures internal multipart size limits.
+  #   No public getter method is available.
+  # - <tt>tag_maker</tt>: Loads HTML generation methods (publicly accessible).
   #
-  #         cgi=CGI.new(:max_multipart_length => 268435456) # simple scalar
+  # <b>Block</b>
   #
-  #         cgi=CGI.new(:max_multipart_length => -> {check_filesystem}) # lambda
+  # If a block is given, its code is stored as a Proc;
+  # whenever CGI::InvalidEncoding would be raised, the proc is called instead.
   #
-  # <tt>block</tt>::
-  #   If provided, the block is called when an invalid encoding is
-  #   encountered. For example:
+  # In this example, the proc simply saves the error:
   #
-  #     encoding_errors={}
-  #     cgi=CGI.new(:accept_charset=>"EUC-JP") do |name,value|
-  #       encoding_errors[name] = value
-  #     end
+  #   encoding_errors={}
+  #   CGI.new(accept_charset: 'EUC-JP') do |name,value|
+  #     encoding_errors[name] = value
+  #   end
+  #   # =>
+  #   #<CGI:0x000002b0ec11bcd8
+  #    @accept_charset="EUC-JP",
+  #    @accept_charset_error_block=#<Proc:0x000002b0ed2ee190 (irb):146>,
+  #    @cookies={},
+  #    @max_multipart_length=134217728,
+  #    @multipart=false,
+  #    @options={accept_charset: "EUC-JP", max_multipart_length: 134217728},
+  #    @output_cookies=nil,
+  #    @output_hidden=nil,
+  #    @params={}>
   #
-  # Finally, if the CGI object is not created in a standard CGI call
-  # environment (that is, it can't locate REQUEST_METHOD in its environment),
-  # then it will run in "offline" mode.  In this mode, it reads its parameters
-  # from the command line or (failing that) from standard input.  Otherwise,
-  # cookies and other parameters are parsed automatically from the standard
-  # CGI locations, which varies according to the REQUEST_METHOD.
   def initialize(options = {}, &block) # :yields: name, value
     @accept_charset_error_block = block_given? ? block : nil
     @options={

data/lib/cgi/escape.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+# :stopdoc
+class CGI
+  module Escape; end
+  include Escape
+  extend Escape
+  module EscapeExt; end # :nodoc:
+end
+# :startdoc:
+
+# Escape/unescape for CGI, HTML, URI.
+module CGI::Escape
+  @@accept_charset = Encoding::UTF_8 unless defined?(@@accept_charset)
+
+  # URL-encode a string into application/x-www-form-urlencoded.
+  # Space characters (+" "+) are encoded with plus signs (+"+"+)
+  #   url_encoded_string = CGI.escape("'Stop!' said Fred")
+  #      # => "%27Stop%21%27+said+Fred"
+  def escape(string)
+    encoding = string.encoding
+    buffer = string.b
+    buffer.gsub!(/([^ a-zA-Z0-9_.\-~]+)/) do |m|
+      '%' + m.unpack('H2' * m.bytesize).join('%').upcase
+    end
+    buffer.tr!(' ', '+')
+    buffer.force_encoding(encoding)
+  end
+
+  # URL-decode an application/x-www-form-urlencoded string with encoding(optional).
+  #   string = CGI.unescape("%27Stop%21%27+said+Fred")
+  #      # => "'Stop!' said Fred"
+  def unescape(string, encoding = @@accept_charset)
+    str = string.tr('+', ' ')
+    str = str.b
+    str.gsub!(/((?:%[0-9a-fA-F]{2})+)/) do |m|
+      [m.delete('%')].pack('H*')
+    end
+    str.force_encoding(encoding)
+    str.valid_encoding? ? str : str.force_encoding(string.encoding)
+  end
+
+  # URL-encode a string following RFC 3986
+  # Space characters (+" "+) are encoded with (+"%20"+)
+  #   url_encoded_string = CGI.escapeURIComponent("'Stop!' said Fred")
+  #      # => "%27Stop%21%27%20said%20Fred"
+  def escapeURIComponent(string)
+    encoding = string.encoding
+    buffer = string.b
+    buffer.gsub!(/([^a-zA-Z0-9_.\-~]+)/) do |m|
+      '%' + m.unpack('H2' * m.bytesize).join('%').upcase
+    end
+    buffer.force_encoding(encoding)
+  end
+  alias escape_uri_component escapeURIComponent
+
+  # URL-decode a string following RFC 3986 with encoding(optional).
+  #   string = CGI.unescapeURIComponent("%27Stop%21%27+said%20Fred")
+  #      # => "'Stop!'+said Fred"
+  def unescapeURIComponent(string, encoding = @@accept_charset)
+    str = string.b
+    str.gsub!(/((?:%[0-9a-fA-F]{2})+)/) do |m|
+      [m.delete('%')].pack('H*')
+    end
+    str.force_encoding(encoding)
+    str.valid_encoding? ? str : str.force_encoding(string.encoding)
+  end
+
+  alias unescape_uri_component unescapeURIComponent
+
+  # The set of special characters and their escaped values
+  TABLE_FOR_ESCAPE_HTML__ = {
+    "'" => ''',
+    '&' => '&',
+    '"' => '"',
+    '<' => '&lt;',
+    '>' => '&gt;',
+  }
+
+  # Escape special characters in HTML, namely '&\"<>
+  #   CGI.escapeHTML('Usage: foo "bar" <baz>')
+  #      # => "Usage: foo &quot;bar&quot; &lt;baz&gt;"
+  def escapeHTML(string)
+    enc = string.encoding
+    unless enc.ascii_compatible?
+      if enc.dummy?
+        origenc = enc
+        enc = Encoding::Converter.asciicompat_encoding(enc)
+        string = enc ? string.encode(enc) : string.b
+      end
+      table = Hash[TABLE_FOR_ESCAPE_HTML__.map {|pair|pair.map {|s|s.encode(enc)}}]
+      string = string.gsub(/#{"['&\"<>]".encode(enc)}/, table)
+      string.encode!(origenc) if origenc
+      string
+    else
+      string = string.b
+      string.gsub!(/['&\"<>]/, TABLE_FOR_ESCAPE_HTML__)
+      string.force_encoding(enc)
+    end
+  end
+
+  # Unescape a string that has been HTML-escaped
+  #   CGI.unescapeHTML("Usage: foo &quot;bar&quot; &lt;baz&gt;")
+  #      # => "Usage: foo \"bar\" <baz>"
+  def unescapeHTML(string)
+    enc = string.encoding
+    unless enc.ascii_compatible?
+      if enc.dummy?
+        origenc = enc
+        enc = Encoding::Converter.asciicompat_encoding(enc)
+        string = enc ? string.encode(enc) : string.b
+      end
+      string = string.gsub(Regexp.new('&(apos|amp|quot|gt|lt|#[0-9]+|#x[0-9A-Fa-f]+);'.encode(enc))) do
+        case $1.encode(Encoding::US_ASCII)
+        when 'apos'                then "'".encode(enc)
+        when 'amp'                 then '&'.encode(enc)
+        when 'quot'                then '"'.encode(enc)
+        when 'gt'                  then '>'.encode(enc)
+        when 'lt'                  then '<'.encode(enc)
+        when /\A#0*(\d+)\z/        then $1.to_i.chr(enc)
+        when /\A#x([0-9a-f]+)\z/i  then $1.hex.chr(enc)
+        end
+      end
+      string.encode!(origenc) if origenc
+      return string
+    end
+    return string unless string.include? '&'
+    charlimit = case enc
+                when Encoding::UTF_8; 0x10ffff
+                when Encoding::ISO_8859_1; 256
+                else 128
+                end
+    string = string.b
+    string.gsub!(/&(apos|amp|quot|gt|lt|\#[0-9]+|\#[xX][0-9A-Fa-f]+);/) do
+      match = $1.dup
+      case match
+      when 'apos'                then "'"
+      when 'amp'                 then '&'
+      when 'quot'                then '"'
+      when 'gt'                  then '>'
+      when 'lt'                  then '<'
+      when /\A#0*(\d+)\z/
+        n = $1.to_i
+        if n < charlimit
+          n.chr(enc)
+        else
+          "&##{$1};"
+        end
+      when /\A#x([0-9a-f]+)\z/i
+        n = $1.hex
+        if n < charlimit
+          n.chr(enc)
+        else
+          "&#x#{$1};"
+        end
+      else
+        "&#{match};"
+      end
+    end
+    string.force_encoding enc
+  end
+
+  # Synonym for CGI.escapeHTML(str)
+  alias escape_html escapeHTML
+  alias h escapeHTML
+
+  # Synonym for CGI.unescapeHTML(str)
+  alias unescape_html unescapeHTML
+
+  # TruffleRuby runs the pure-Ruby variant faster, do not use the C extension there
+  unless RUBY_ENGINE == 'truffleruby'
+    begin
+      require 'cgi/escape.so'
+    rescue LoadError
+    end
+  end
+
+  # Escape only the tags of certain HTML elements in +string+.
+  #
+  # Takes an element or elements or array of elements.  Each element
+  # is specified by the name of the element, without angle brackets.
+  # This matches both the start and the end tag of that element.
+  # The attribute list of the open tag will also be escaped (for
+  # instance, the double-quotes surrounding attribute values).
+  #
+  #   print CGI.escapeElement('<BR><A HREF="url"></A>', "A", "IMG")
+  #     # "<BR>&lt;A HREF=&quot;url&quot;&gt;&lt;/A&gt"
+  #
+  #   print CGI.escapeElement('<BR><A HREF="url"></A>', ["A", "IMG"])
+  #     # "<BR>&lt;A HREF=&quot;url&quot;&gt;&lt;/A&gt"
+  def escapeElement(string, *elements)
+    elements = elements[0] if elements[0].kind_of?(Array)
+    unless elements.empty?
+      string.gsub(/<\/?(?:#{elements.join("|")})\b[^<>]*+>?/im) do
+        CGI.escapeHTML($&)
+      end
+    else
+      string
+    end
+  end
+
+  # Undo escaping such as that done by CGI.escapeElement()
+  #
+  #   print CGI.unescapeElement(
+  #           CGI.escapeHTML('<BR><A HREF="url"></A>'), "A", "IMG")
+  #     # "&lt;BR&gt;<A HREF="url"></A>"
+  #
+  #   print CGI.unescapeElement(
+  #           CGI.escapeHTML('<BR><A HREF="url"></A>'), ["A", "IMG"])
+  #     # "&lt;BR&gt;<A HREF="url"></A>"
+  def unescapeElement(string, *elements)
+    elements = elements[0] if elements[0].kind_of?(Array)
+    unless elements.empty?
+      string.gsub(/&lt;\/?(?:#{elements.join("|")})\b(?>[^&]+|&(?![gl]t;)\w+;)*(?:&gt;)?/im) do
+        unescapeHTML($&)
+      end
+    else
+      string
+    end
+  end
+
+  # Synonym for CGI.escapeElement(str)
+  alias escape_element escapeElement
+
+  # Synonym for CGI.unescapeElement(str)
+  alias unescape_element unescapeElement
+
+end

data/lib/cgi/html.rb

@@ -1006,27 +1006,32 @@ class CGI
 
   end # Html5
 
+  # HTML version 3 generation class.
   class HTML3
     include Html3
     include HtmlExtension
   end
 
+  # HTML version 4 generation class.
   class HTML4
     include Html4
     include HtmlExtension
   end
 
+  # HTML version 4 transitional generation class.
   class HTML4Tr
     include Html4Tr
     include HtmlExtension
   end
 
+  # HTML version 4 with framesets generation class.
   class HTML4Fr
     include Html4Tr
     include Html4Fr
     include HtmlExtension
   end
 
+  # HTML version 5 generation class.
   class HTML5
     include Html5
     include HtmlExtension

data/lib/cgi/session.rb

@@ -214,11 +214,11 @@ class CGI
       dir = option['tmpdir'] || Dir::tmpdir
       prefix = option['prefix']
       suffix = option['suffix']
-      require 'digest/md5'
-      md5 = Digest::MD5.hexdigest(session_id)[0,16]
+      require 'digest'
+      sha256 = Digest::SHA256.hexdigest(session_id)[0,16]
       path = dir+"/"
       path << prefix if prefix
-      path << md5
+      path << sha256
       path << suffix if suffix
       if File::exist? path
         hash = nil

data/lib/cgi/util.rb

@@ -4,220 +4,9 @@ class CGI
   include Util
   extend Util
 end
-module CGI::Util
-  @@accept_charset = Encoding::UTF_8 unless defined?(@@accept_charset)
-
-  # URL-encode a string into application/x-www-form-urlencoded.
-  # Space characters (+" "+) are encoded with plus signs (+"+"+)
-  #   url_encoded_string = CGI.escape("'Stop!' said Fred")
-  #      # => "%27Stop%21%27+said+Fred"
-  def escape(string)
-    encoding = string.encoding
-    buffer = string.b
-    buffer.gsub!(/([^ a-zA-Z0-9_.\-~]+)/) do |m|
-      '%' + m.unpack('H2' * m.bytesize).join('%').upcase
-    end
-    buffer.tr!(' ', '+')
-    buffer.force_encoding(encoding)
-  end
-
-  # URL-decode an application/x-www-form-urlencoded string with encoding(optional).
-  #   string = CGI.unescape("%27Stop%21%27+said+Fred")
-  #      # => "'Stop!' said Fred"
-  def unescape(string, encoding = @@accept_charset)
-    str = string.tr('+', ' ')
-    str = str.b
-    str.gsub!(/((?:%[0-9a-fA-F]{2})+)/) do |m|
-      [m.delete('%')].pack('H*')
-    end
-    str.force_encoding(encoding)
-    str.valid_encoding? ? str : str.force_encoding(string.encoding)
-  end
-
-  # URL-encode a string following RFC 3986
-  # Space characters (+" "+) are encoded with (+"%20"+)
-  #   url_encoded_string = CGI.escapeURIComponent("'Stop!' said Fred")
-  #      # => "%27Stop%21%27%20said%20Fred"
-  def escapeURIComponent(string)
-    encoding = string.encoding
-    buffer = string.b
-    buffer.gsub!(/([^a-zA-Z0-9_.\-~]+)/) do |m|
-      '%' + m.unpack('H2' * m.bytesize).join('%').upcase
-    end
-    buffer.force_encoding(encoding)
-  end
-  alias escape_uri_component escapeURIComponent
-
-  # URL-decode a string following RFC 3986 with encoding(optional).
-  #   string = CGI.unescapeURIComponent("%27Stop%21%27+said%20Fred")
-  #      # => "'Stop!'+said Fred"
-  def unescapeURIComponent(string, encoding = @@accept_charset)
-    str = string.b
-    str.gsub!(/((?:%[0-9a-fA-F]{2})+)/) do |m|
-      [m.delete('%')].pack('H*')
-    end
-    str.force_encoding(encoding)
-    str.valid_encoding? ? str : str.force_encoding(string.encoding)
-  end
-
-  alias unescape_uri_component unescapeURIComponent
-
-  # The set of special characters and their escaped values
-  TABLE_FOR_ESCAPE_HTML__ = {
-    "'" => ''',
-    '&' => '&',
-    '"' => '"',
-    '<' => '&lt;',
-    '>' => '&gt;',
-  }
-
-  # Escape special characters in HTML, namely '&\"<>
-  #   CGI.escapeHTML('Usage: foo "bar" <baz>')
-  #      # => "Usage: foo &quot;bar&quot; &lt;baz&gt;"
-  def escapeHTML(string)
-    enc = string.encoding
-    unless enc.ascii_compatible?
-      if enc.dummy?
-        origenc = enc
-        enc = Encoding::Converter.asciicompat_encoding(enc)
-        string = enc ? string.encode(enc) : string.b
-      end
-      table = Hash[TABLE_FOR_ESCAPE_HTML__.map {|pair|pair.map {|s|s.encode(enc)}}]
-      string = string.gsub(/#{"['&\"<>]".encode(enc)}/, table)
-      string.encode!(origenc) if origenc
-      string
-    else
-      string = string.b
-      string.gsub!(/['&\"<>]/, TABLE_FOR_ESCAPE_HTML__)
-      string.force_encoding(enc)
-    end
-  end
-
-  # TruffleRuby runs the pure-Ruby variant faster, do not use the C extension there
-  unless RUBY_ENGINE == 'truffleruby'
-    begin
-      require 'cgi/escape'
-    rescue LoadError
-    end
-  end
-
-  # Unescape a string that has been HTML-escaped
-  #   CGI.unescapeHTML("Usage: foo &quot;bar&quot; &lt;baz&gt;")
-  #      # => "Usage: foo \"bar\" <baz>"
-  def unescapeHTML(string)
-    enc = string.encoding
-    unless enc.ascii_compatible?
-      if enc.dummy?
-        origenc = enc
-        enc = Encoding::Converter.asciicompat_encoding(enc)
-        string = enc ? string.encode(enc) : string.b
-      end
-      string = string.gsub(Regexp.new('&(apos|amp|quot|gt|lt|#[0-9]+|#x[0-9A-Fa-f]+);'.encode(enc))) do
-        case $1.encode(Encoding::US_ASCII)
-        when 'apos'                then "'".encode(enc)
-        when 'amp'                 then '&'.encode(enc)
-        when 'quot'                then '"'.encode(enc)
-        when 'gt'                  then '>'.encode(enc)
-        when 'lt'                  then '<'.encode(enc)
-        when /\A#0*(\d+)\z/        then $1.to_i.chr(enc)
-        when /\A#x([0-9a-f]+)\z/i  then $1.hex.chr(enc)
-        end
-      end
-      string.encode!(origenc) if origenc
-      return string
-    end
-    return string unless string.include? '&'
-    charlimit = case enc
-                when Encoding::UTF_8; 0x10ffff
-                when Encoding::ISO_8859_1; 256
-                else 128
-                end
-    string = string.b
-    string.gsub!(/&(apos|amp|quot|gt|lt|\#[0-9]+|\#[xX][0-9A-Fa-f]+);/) do
-      match = $1.dup
-      case match
-      when 'apos'                then "'"
-      when 'amp'                 then '&'
-      when 'quot'                then '"'
-      when 'gt'                  then '>'
-      when 'lt'                  then '<'
-      when /\A#0*(\d+)\z/
-        n = $1.to_i
-        if n < charlimit
-          n.chr(enc)
-        else
-          "&##{$1};"
-        end
-      when /\A#x([0-9a-f]+)\z/i
-        n = $1.hex
-        if n < charlimit
-          n.chr(enc)
-        else
-          "&#x#{$1};"
-        end
-      else
-        "&#{match};"
-      end
-    end
-    string.force_encoding enc
-  end
-
-  # Synonym for CGI.escapeHTML(str)
-  alias escape_html escapeHTML
-
-  # Synonym for CGI.unescapeHTML(str)
-  alias unescape_html unescapeHTML
-
-  # Escape only the tags of certain HTML elements in +string+.
-  #
-  # Takes an element or elements or array of elements.  Each element
-  # is specified by the name of the element, without angle brackets.
-  # This matches both the start and the end tag of that element.
-  # The attribute list of the open tag will also be escaped (for
-  # instance, the double-quotes surrounding attribute values).
-  #
-  #   print CGI.escapeElement('<BR><A HREF="url"></A>', "A", "IMG")
-  #     # "<BR>&lt;A HREF=&quot;url&quot;&gt;&lt;/A&gt"
-  #
-  #   print CGI.escapeElement('<BR><A HREF="url"></A>', ["A", "IMG"])
-  #     # "<BR>&lt;A HREF=&quot;url&quot;&gt;&lt;/A&gt"
-  def escapeElement(string, *elements)
-    elements = elements[0] if elements[0].kind_of?(Array)
-    unless elements.empty?
-      string.gsub(/<\/?(?:#{elements.join("|")})\b[^<>]*+>?/im) do
-        CGI.escapeHTML($&)
-      end
-    else
-      string
-    end
-  end
-
-  # Undo escaping such as that done by CGI.escapeElement()
-  #
-  #   print CGI.unescapeElement(
-  #           CGI.escapeHTML('<BR><A HREF="url"></A>'), "A", "IMG")
-  #     # "&lt;BR&gt;<A HREF="url"></A>"
-  #
-  #   print CGI.unescapeElement(
-  #           CGI.escapeHTML('<BR><A HREF="url"></A>'), ["A", "IMG"])
-  #     # "&lt;BR&gt;<A HREF="url"></A>"
-  def unescapeElement(string, *elements)
-    elements = elements[0] if elements[0].kind_of?(Array)
-    unless elements.empty?
-      string.gsub(/&lt;\/?(?:#{elements.join("|")})\b(?>[^&]+|&(?![gl]t;)\w+;)*(?:&gt;)?/im) do
-        unescapeHTML($&)
-      end
-    else
-      string
-    end
-  end
-
-  # Synonym for CGI.escapeElement(str)
-  alias escape_element escapeElement
-
-  # Synonym for CGI.unescapeElement(str)
-  alias unescape_element unescapeElement
 
+# Utility methods for CGI.
+module CGI::Util
   # Format a +Time+ object as a String using the format specified by RFC 1123.
   #
   #   CGI.rfc1123_date(Time.now)
@@ -253,6 +42,7 @@ module CGI::Util
     end
     lines.gsub(/^((?:#{Regexp::quote(shift)})*)__(?=<\/?\w)/, '\1')
   end
-
-  alias h escapeHTML
 end
+
+# For backward compatibility
+require 'cgi/escape' unless defined?(CGI::EscapeExt)

data/lib/cgi.rb

@@ -42,6 +42,17 @@
 #
 # Read on for more details.  Examples are provided at the bottom.
 #
+# == About the Examples
+#
+# Examples on this page assume that \CGI has been required:
+#
+#   require 'cgi'
+#
+# Unless otherwise stated, examples also assume that environment variable 'REQUEST_METHOD' exists
+# (which prevents CGI.new from entering its online mode):
+#
+#   ENV.include?('REQUEST_METHOD') # => true
+#
 # == Queries
 #
 # The CGI class dynamically mixes in parameter and cookie-parsing
@@ -144,62 +155,66 @@
 #
 # === Utility HTML escape and other methods like a function.
 #
-# There are some utility tool defined in cgi/util.rb .
+# There are some utility tools defined in cgi/util.rb and cgi/escape.rb.
+# Escape and unescape methods are defined in cgi/escape.rb.
 # And when include, you can use utility methods like a function.
 #
-# == Examples of use
+# == Examples of Use
 #
-# === Get form values
+# === Form Values
 #
-#   require "cgi"
-#   cgi = CGI.new
-#   value = cgi['field_name']   # <== value string for 'field_name'
-#     # if not 'field_name' included, then return "".
-#   fields = cgi.keys            # <== array of field names
-#
-#   # returns true if form has 'field_name'
-#   cgi.has_key?('field_name')
-#   cgi.has_key?('field_name')
-#   cgi.include?('field_name')
-#
-# CAUTION! <code>cgi['field_name']</code> returned an Array with the old
-# cgi.rb(included in Ruby 1.6)
+# ==== Get Form Values
 #
-# === Get form values as hash
+# You can use method +cgi.params+ to retrieve form values
+# in a {Hash}[https://docs.ruby-lang.org/en/3.4/Hash.html]:
 #
-#   require "cgi"
+#   ENV.update(
+#    'REQUEST_METHOD' => 'GET',
+#    'QUERY_STRING'   => 'a=111&&b=222&c&d='
+#   )
 #   cgi = CGI.new
-#   params = cgi.params
-#
-# cgi.params is a hash.
-#
-#   cgi.params['new_field_name'] = ["value"]  # add new param
-#   cgi.params['field_name'] = ["new_value"]  # change value
-#   cgi.params.delete('field_name')           # delete param
-#   cgi.params.clear                          # delete all params
-#
-#
-# === Save form values to file
-#
-#   require "pstore"
-#   db = PStore.new("query.db")
-#   db.transaction do
-#     db["params"] = cgi.params
+#   cgi.params.class # => Hash
+#   cgi.params       # => {"a" => ["111"], "b" => ["222"], "c" => [], "d" => [""]}
+#   cgi.params.keys  # => ["a", "b", "c", "d"]
+#   cgi.params['a']  # => ["111"]  # Returns an array.
+#   cgi.params['d']  # => [""]     # Returns empty string in array if no value.
+#   cgi.params['x']  # => []       # Returns empty array if no key.
+#
+# A \CGI instance has these convenience methods:
+#
+#   # Convenience method for cgi.params.keys.
+#   cgi.keys          # => ["a", "b", "c", "d"]
+#   # Convenience method for cgi.params[key].first.
+#   cgi['a']          # => "111"  # Returns string, not array.
+#   cgi['d']          # => ""     # Returns empty string if no value.
+#   cgi['x']          # => ""     # Returns empty string if no key.
+#   # Convenience method for cgi.params.include?.
+#   cgi.include?('a') # => true
+#   cgi.include?('x') # => false
+#
+# ==== Save and Restore Form Values
+#
+# This example uses {Pstore}[https://docs.ruby-lang.org/en/3.4/PStore.html]
+# to store and retrieve form values:
+#
+#   ENV.update(
+#    'REQUEST_METHOD' => 'GET',
+#    'QUERY_STRING'   => 'a=111&&b=222&c&d='
+#   )
+#   cgi = CGI.new
+#   require 'pstore'
+#   store = PStore.new('params.store')
+#   store.transaction do
+#     store['params'] = cgi.params
 #   end
-#
-#
-# === Restore form values from file
-#
-#   require "pstore"
-#   db = PStore.new("query.db")
-#   db.transaction do
-#     cgi.params = db["params"]
+#   cgi.params.clear # Oops! Lost my params!
+#   store.transaction do
+#     cgi.params = store['params']
 #   end
+#   cgi.params # => {"a" => ["111"], "b" => ["222"], "c" => [], "d" => [""]}
 #
+# ==== Get multipart form values
 #
-# === Get multipart form values
-#
-#   require "cgi"
 #   cgi = CGI.new
 #   value = cgi['field_name']   # <== value string for 'field_name'
 #   value.read                  # <== body of value
@@ -211,7 +226,6 @@
 #
 # === Get cookie values
 #
-#   require "cgi"
 #   cgi = CGI.new
 #   values = cgi.cookies['name']  # <== array of 'name'
 #     # if not 'name' included, then return [].
@@ -221,7 +235,6 @@
 #
 # === Get cookie objects
 #
-#   require "cgi"
 #   cgi = CGI.new
 #   for name, cookie in cgi.cookies
 #     cookie.expires = Time.now + 30
@@ -230,14 +243,12 @@
 #
 #   cgi.cookies # { "name1" => cookie1, "name2" => cookie2, ... }
 #
-#   require "cgi"
 #   cgi = CGI.new
 #   cgi.cookies['name'].expires = Time.now + 30
 #   cgi.out("cookie" => cgi.cookies['name']) {"string"}
 #
 # === Print http header and html string to $DEFAULT_OUTPUT ($>)
 #
-#   require "cgi"
 #   cgi = CGI.new("html4")  # add HTML generation methods
 #   cgi.out do
 #     cgi.html do
@@ -274,24 +285,26 @@
 #
 # === Some utility methods
 #
-#   require 'cgi/util'
+#   require 'cgi/escape'
 #   CGI.escapeHTML('Usage: foo "bar" <baz>')
 #
 #
 # === Some utility methods like a function
 #
-#   require 'cgi/util'
-#   include CGI::Util
+#   require 'cgi/escape'
+#   include CGI::Escape
 #   escapeHTML('Usage: foo "bar" <baz>')
 #   h('Usage: foo "bar" <baz>') # alias
 #
 #
 
 class CGI
-  VERSION = "0.4.2"
+  # The version string
+  VERSION = "0.5.1"
 end
 
+require 'cgi/util'
+require 'cgi/escape' unless defined?(CGI::EscapeExt)
 require 'cgi/core'
 require 'cgi/cookie'
-require 'cgi/util'
 CGI.autoload(:HtmlExtension, 'cgi/html')

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: cgi
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.1
 platform: ruby
 authors:
 - Yukihiro Matsumoto
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-26 00:00:00.000000000 Z
+date: 2025-12-10 00:00:00.000000000 Z
 dependencies: []
 description: Support for the Common Gateway Interface protocol.
 email:
@@ -27,6 +26,7 @@ files:
 - lib/cgi.rb
 - lib/cgi/cookie.rb
 - lib/cgi/core.rb
+- lib/cgi/escape.rb
 - lib/cgi/html.rb
 - lib/cgi/session.rb
 - lib/cgi/session/pstore.rb
@@ -38,7 +38,6 @@ licenses:
 metadata:
   homepage_uri: https://github.com/ruby/cgi
   source_code_uri: https://github.com/ruby/cgi
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -53,8 +52,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Support for the Common Gateway Interface protocol.
 test_files: []