From 59cf9ebf4dc211cb9d71a484866895b3d927fbe6 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Tue, 3 Jan 2023 09:33:31 -0600 Subject: [PATCH] [ruby/uri] [DOC] Enhanced RDoc for common methods (https://github.com/ruby/uri/pull/48) https://github.com/ruby/uri/commit/2bfd848c26 --- lib/uri/common.rb | 143 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 116 insertions(+), 27 deletions(-) diff --git a/lib/uri/common.rb b/lib/uri/common.rb index ca38bec7ec..0ec38d70a6 100644 --- a/lib/uri/common.rb +++ b/lib/uri/common.rb @@ -314,17 +314,41 @@ module URI TBLDECWWWCOMP_['+'] = ' ' TBLDECWWWCOMP_.freeze - # Encodes given +str+ to URL-encoded form data. + # Returns a URL-encoded string derived from the given string +str+. # - # This method doesn't convert *, -, ., 0-9, A-Z, _, a-z, but does convert SP - # (ASCII space) to + and converts others to %XX. + # The returned string: # - # If +enc+ is given, convert +str+ to the encoding before percent encoding. + # - Preserves: # - # This is an implementation of - # https://www.w3.org/TR/2013/CR-html5-20130806/forms.html#url-encoded-form-data. + # - Characters '*', '.', '-', and '_'. + # - Character in ranges 'a'..'z', 'A'..'Z', + # and '0'..'9'. + # + # Example: + # + # URI.encode_www_form_component('*.-_azAZ09') + # # => "*.-_azAZ09" + # + # - Converts: + # + # - Character ' ' to character '+'. + # - Any other character to "percent notation"; + # the percent notation for character c is '%%%X' % c.ord. + # + # Example: + # + # URI.encode_www_form_component('Here are some punctuation characters: ,;?:') + # # => "Here+are+some+punctuation+characters%3A+%2C%3B%3F%3A" + # + # Encoding: + # + # - If +str+ has encoding Encoding::ASCII_8BIT, argument +enc+ is ignored. + # - Otherwise +str+ is converted first to Encoding::UTF_8 + # (with suitable character replacements), + # and then to encoding +enc+. + # + # In either case, the returned string has forced encoding Encoding::US_ASCII. # - # See URI.decode_www_form_component, URI.encode_www_form. def self.encode_www_form_component(str, enc=nil) _encode_uri_component(/[^*\-.0-9A-Z_a-z]/, TBLENCWWWCOMP_, str, enc) end @@ -372,33 +396,98 @@ module URI end private_class_method :_decode_uri_component - # Generates URL-encoded form data from given +enum+. + # Returns a URL-encoded string derived from the given + # {Enumerable}[rdoc-ref:Enumerable@Enumerable+in+Ruby+Classes] + # +enum+. # - # This generates application/x-www-form-urlencoded data defined in HTML5 - # from given an Enumerable object. + # The result is suitable for use as form data + # for an \HTTP request whose Content-Type is + # 'application/x-www-form-urlencoded'. # - # This internally uses URI.encode_www_form_component(str). + # The returned string consists of the elements of +enum+, + # each converted to one or more URL-encoded strings, + # and all joined with character '&'. # - # This method doesn't convert the encoding of given items, so convert them - # before calling this method if you want to send data as other than original - # encoding or mixed encoding data. (Strings which are encoded in an HTML5 - # ASCII incompatible encoding are converted to UTF-8.) + # Simple examples: # - # This method doesn't handle files. When you send a file, use - # multipart/form-data. + # URI.encode_www_form([['foo', 0], ['bar', 1], ['baz', 2]]) + # # => "foo=0&bar=1&baz=2" + # URI.encode_www_form({foo: 0, bar: 1, baz: 2}) + # # => "foo=0&bar=1&baz=2" # - # This refers https://url.spec.whatwg.org/#concept-urlencoded-serializer + # When +enum+ is Array-like, each element +ele+ is converted to a field: # - # URI.encode_www_form([["q", "ruby"], ["lang", "en"]]) - # #=> "q=ruby&lang=en" - # URI.encode_www_form("q" => "ruby", "lang" => "en") - # #=> "q=ruby&lang=en" - # URI.encode_www_form("q" => ["ruby", "perl"], "lang" => "en") - # #=> "q=ruby&q=perl&lang=en" - # URI.encode_www_form([["q", "ruby"], ["q", "perl"], ["lang", "en"]]) - # #=> "q=ruby&q=perl&lang=en" + # - If +ele+ is an array of two or more elements, + # the field is formed from its first two elements + # (and any additional elements are ignored): + # + # name = URI.encode_www_form_component(ele[0], enc) + # value = URI.encode_www_form_component(ele[1], enc) + # "#{name}=#{value}" + # + # Examples: + # + # URI.encode_www_form([%w[foo bar], %w[baz bat bah]]) + # # => "foo=bar&baz=bat" + # URI.encode_www_form([['foo', 0], ['bar', :baz, 'bat']]) + # # => "foo=0&bar=baz" + # + # - If +ele+ is an array of one element, + # the field is formed from ele[0]: + # + # URI.encode_www_form_component(ele[0]) + # + # Example: + # + # URI.encode_www_form([['foo'], [:bar], [0]]) + # # => "foo&bar&0" + # + # - Otherwise the field is formed from +ele+: + # + # URI.encode_www_form_component(ele) + # + # Example: + # + # URI.encode_www_form(['foo', :bar, 0]) + # # => "foo&bar&0" + # + # The elements of an Array-like +enum+ may be mixture: + # + # URI.encode_www_form([['foo', 0], ['bar', 1, 2], ['baz'], :bat]) + # # => "foo=0&bar=1&baz&bat" + # + # When +enum+ is Hash-like, + # each +key+/+value+ pair is converted to one or more fields: + # + # - If +value+ is + # {Array-convertible}[rdoc-ref:implicit_conversion.rdoc@Array-Convertible+Objects], + # each element +ele+ in +value+ is paired with +key+ to form a field: + # + # name = URI.encode_www_form_component(key, enc) + # value = URI.encode_www_form_component(ele, enc) + # "#{name}=#{value}" + # + # Example: + # + # URI.encode_www_form({foo: [:bar, 1], baz: [:bat, :bam, 2]}) + # # => "foo=bar&foo=1&baz=bat&baz=bam&baz=2" + # + # - Otherwise, +key+ and +value+ are paired to form a field: + # + # name = URI.encode_www_form_component(key, enc) + # value = URI.encode_www_form_component(value, enc) + # "#{name}=#{value}" + # + # Example: + # + # URI.encode_www_form({foo: 0, bar: 1, baz: 2}) + # # => "foo=0&bar=1&baz=2" + # + # The elements of a Hash-like +enum+ may be mixture: + # + # URI.encode_www_form({foo: [0, 1], bar: 2}) + # # => "foo=0&foo=1&bar=2" # - # See URI.encode_www_form_component, URI.decode_www_form. def self.encode_www_form(enum, enc=nil) enum.map do |k,v| if v.nil?