base64 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e354beb33c4cd44aec636c9fef7f2948971fca963a60c87efb96d02f5a1a0b84
-  data.tar.gz: 6925a1c6847f48c78cc2ef572bceb84e2e0b88f08ad6cff08267c57d56fca9f6
+  metadata.gz: da8017f88b13b4bcce299b2b4b5a3023ceca129259e34c96cf4ee8444651cb54
+  data.tar.gz: c13e817c37612d65668c7266945f2356982e090f0781d739cc9e2fbaadf5bad7
 SHA512:
-  metadata.gz: 5b12ef4b892b908de5a44db9822565082911af176add02b565a6d34a5d2bc0997fba5caf3bbd2554337c95ce8b78a53373c60da8b2d61449f078d8948c053330
-  data.tar.gz: 5dde38796eff1286680e7589a18862be76424c53fcfdea12e2964c7b290df738fb6c9830767dc9dc1370d989c30258564d0af0d6452bf8513780dfcf5cae8804
+  metadata.gz: 0c070995dc383eb45bb66d9b413eaf567434932477a4121834567c6deb5493c3498c652db0f23901696232ff098573db5b094f180c7ad2b90be189156f98e87e
+  data.tar.gz: a23bc57298678e16663a9a2f0007259437b8efe6c25d37481a2e47585b31229fdd9ff5dd76fb9f0618954e88d6a63d9f316a19d531ee7cbe6e9bea607ef859c5

data/{LICENSE.txt → BSDL}

@@ -4,10 +4,10 @@ Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 1. Redistributions of source code must retain the above copyright
-notice, this list of conditions and the following disclaimer.
+   notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright
-notice, this list of conditions and the following disclaimer in the
-documentation and/or other materials provided with the distribution.
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
 
 THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

data/COPYING

@@ -0,0 +1,56 @@
+Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.jp>.
+You can redistribute it and/or modify it under either the terms of the
+2-clause BSDL (see the file BSDL), or the conditions below:
+
+1. You may make and give away verbatim copies of the source form of the
+   software without restriction, provided that you duplicate all of the
+   original copyright notices and associated disclaimers.
+
+2. You may modify your copy of the software in any way, provided that
+   you do at least ONE of the following:
+
+   a. place your modifications in the Public Domain or otherwise
+      make them Freely Available, such as by posting said
+      modifications to Usenet or an equivalent medium, or by allowing
+      the author to include your modifications in the software.
+
+   b. use the modified software only within your corporation or
+      organization.
+
+   c. give non-standard binaries non-standard names, with
+      instructions on where to get the original software distribution.
+
+   d. make other distribution arrangements with the author.
+
+3. You may distribute the software in object code or binary form,
+   provided that you do at least ONE of the following:
+
+   a. distribute the binaries and library files of the software,
+      together with instructions (in the manual page or equivalent)
+      on where to get the original distribution.
+
+   b. accompany the distribution with the machine-readable source of
+      the software.
+
+   c. give non-standard binaries non-standard names, with
+      instructions on where to get the original software distribution.
+
+   d. make other distribution arrangements with the author.
+
+4. You may modify and include the part of the software into any other
+   software (possibly commercial).  But some files in the distribution
+   are not written by the author, so that they are not under these terms.
+
+   For the list of those files and their copying conditions, see the
+   file LEGAL.
+
+5. The scripts and library files supplied as input to or produced as
+   output from the software do not automatically fall under the
+   copyright of the software, but belong to whomever generated them,
+   and may be sold commercially, and may be aggregated with this
+   software.
+
+6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+   IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+   WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+   PURPOSE.

data/LEGAL

@@ -0,0 +1,60 @@
+# -*- rdoc -*-
+
+= LEGAL NOTICE INFORMATION
+--------------------------
+
+All the files in this distribution are covered under either the Ruby's
+license (see the file COPYING) or public-domain except some files
+mentioned below.
+
+== MIT License
+>>>
+      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.
+
+== Old-style BSD license
+>>>
+      Redistribution and use in source and binary forms, with or without
+      modification, are permitted provided that the following conditions
+      are met:
+      1. Redistributions of source code must retain the above copyright
+         notice, this list of conditions and the following disclaimer.
+      2. Redistributions in binary form must reproduce the above copyright
+         notice, this list of conditions and the following disclaimer in the
+         documentation and/or other materials provided with the distribution.
+      3. Neither the name of the University nor the names of its contributors
+         may be used to endorse or promote products derived from this software
+         without specific prior written permission.
+
+      THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+      ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+      IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+      ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+      FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+      DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+      OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+      LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+      OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+      SUCH DAMAGE.
+
+      IMPORTANT NOTE::
+
+      From ftp://ftp.cs.berkeley.edu/pub/4bsd/README.Impt.License.Change
+      paragraph 3 above is now null and void.

data/lib/base64.rb

@@ -1,85 +1,345 @@
 # frozen_string_literal: true
 #
-# = base64.rb: methods for base64-encoding and -decoding strings
+# \Module \Base64 provides methods for:
 #
-
-# The Base64 module provides for the encoding (#encode64, #strict_encode64,
-# #urlsafe_encode64) and decoding (#decode64, #strict_decode64,
-# #urlsafe_decode64) of binary data using a Base64 representation.
+# - \Encoding a binary string (containing non-ASCII characters)
+#   as a string of printable ASCII characters.
+# - Decoding such an encoded string.
 #
-# == Example
+# \Base64 is commonly used in contexts where binary data
+# is not allowed or supported:
 #
-# A simple encoding and decoding.
+# - Images in HTML or CSS files, or in URLs.
+# - Email attachments.
 #
-#     require "base64"
+# A \Base64-encoded string is about one-third larger that its source.
+# See the {Wikipedia article}[https://en.wikipedia.org/wiki/Base64]
+# for more information.
 #
-#     enc   = Base64.encode64('Send reinforcements')
-#                         # -> "U2VuZCByZWluZm9yY2VtZW50cw==\n"
-#     plain = Base64.decode64(enc)
-#                         # -> "Send reinforcements"
+# This module provides three pairs of encode/decode methods.
+# Your choices among these methods should depend on:
+#
+# - Which character set is to be used for encoding and decoding.
+# - Whether "padding" is to be used.
+# - Whether encoded strings are to contain newlines.
+#
+# Note: Examples on this page assume that the including program has executed:
+#
+#   require 'base64'
+#
+# == \Encoding Character Sets
+#
+# A \Base64-encoded string consists only of characters from a 64-character set:
+#
+# - <tt>('A'..'Z')</tt>.
+# - <tt>('a'..'z')</tt>.
+# - <tt>('0'..'9')</tt>.
+# - <tt>=</tt>, the 'padding' character.
+# - Either:
+#   - <tt>%w[+ /]</tt>:
+#     {RFC-2045-compliant}[https://datatracker.ietf.org/doc/html/rfc2045];
+#     _not_ safe for URLs.
+#   - <tt>%w[- _]</tt>:
+#     {RFC-4648-compliant}[https://datatracker.ietf.org/doc/html/rfc4648];
+#     safe for URLs.
+#
+# If you are working with \Base64-encoded strings that will come from
+# or be put into URLs, you should choose this encoder-decoder pair
+# of RFC-4648-compliant methods:
+#
+# - Base64.urlsafe_encode64 and Base64.urlsafe_decode64.
+#
+# Otherwise, you may choose any of the pairs in this module,
+# including the pair above, or the RFC-2045-compliant pairs:
+#
+# - Base64.encode64 and Base64.decode64.
+# - Base64.strict_encode64 and Base64.strict_decode64.
+#
+# == Padding
+#
+# \Base64-encoding changes a triplet of input bytes
+# into a quartet of output characters.
+#
+# <b>Padding in Encode Methods</b>
+#
+# Padding -- extending an encoded string with zero, one, or two trailing
+# <tt>=</tt> characters -- is performed by methods Base64.encode64,
+# Base64.strict_encode64, and, by default, Base64.urlsafe_encode64:
+#
+#   Base64.encode64('s')                         # => "cw==\n"
+#   Base64.strict_encode64('s')                  # => "cw=="
+#   Base64.urlsafe_encode64('s')                 # => "cw=="
+#   Base64.urlsafe_encode64('s', padding: false) # => "cw"
+#
+# When padding is performed, the encoded string is always of length <em>4n</em>,
+# where +n+ is a non-negative integer:
+#
+# - Input bytes of length <em>3n</em> generate unpadded output characters
+#   of length <em>4n</em>:
+#
+#     # n = 1:  3 bytes => 4 characters.
+#     Base64.strict_encode64('123')      # => "MDEy"
+#     # n = 2:  6 bytes => 8 characters.
+#     Base64.strict_encode64('123456')   # => "MDEyMzQ1"
+#
+# - Input bytes of length <em>3n+1</em> generate padded output characters
+#   of length <em>4(n+1)</em>, with two padding characters at the end:
+#
+#     # n = 1:  4 bytes => 8 characters.
+#     Base64.strict_encode64('1234')     # => "MDEyMw=="
+#     # n = 2:  7 bytes => 12 characters.
+#     Base64.strict_encode64('1234567')  # => "MDEyMzQ1Ng=="
+#
+# - Input bytes of length <em>3n+2</em> generate padded output characters
+#   of length <em>4(n+1)</em>, with one padding character at the end:
+#
+#     # n = 1:  5 bytes => 8 characters.
+#     Base64.strict_encode64('12345')    # => "MDEyMzQ="
+#     # n = 2:  8 bytes => 12 characters.
+#     Base64.strict_encode64('12345678') # => "MDEyMzQ1Njc="
+#
+# When padding is suppressed, for a positive integer <em>n</em>:
+#
+# - Input bytes of length <em>3n</em> generate unpadded output characters
+#   of length <em>4n</em>:
+#
+#     # n = 1:  3 bytes => 4 characters.
+#     Base64.urlsafe_encode64('123', padding: false)      # => "MDEy"
+#     # n = 2:  6 bytes => 8 characters.
+#     Base64.urlsafe_encode64('123456', padding: false)   # => "MDEyMzQ1"
+#
+# - Input bytes of length <em>3n+1</em> generate unpadded output characters
+#   of length <em>4n+2</em>, with two padding characters at the end:
+#
+#     # n = 1:  4 bytes => 6 characters.
+#     Base64.urlsafe_encode64('1234', padding: false)     # => "MDEyMw"
+#     # n = 2:  7 bytes => 10 characters.
+#     Base64.urlsafe_encode64('1234567', padding: false)  # => "MDEyMzQ1Ng"
+#
+# - Input bytes of length <em>3n+2</em> generate unpadded output characters
+#   of length <em>4n+3</em>, with one padding character at the end:
+#
+#     # n = 1:  5 bytes => 7 characters.
+#     Base64.urlsafe_encode64('12345', padding: false)    # => "MDEyMzQ"
+#     # m = 2:  8 bytes => 11 characters.
+#     Base64.urlsafe_encode64('12345678', padding: false) # => "MDEyMzQ1Njc"
+#
+# <b>Padding in Decode Methods</b>
+#
+# All of the \Base64 decode methods support (but do not require) padding.
+#
+# \Method Base64.decode64 does not check the size of the padding:
+#
+#   Base64.decode64("MDEyMzQ1Njc") # => "01234567"
+#   Base64.decode64("MDEyMzQ1Njc=") # => "01234567"
+#   Base64.decode64("MDEyMzQ1Njc==") # => "01234567"
+#
+# \Method Base64.strict_decode64 strictly enforces padding size:
+#
+#   Base64.strict_decode64("MDEyMzQ1Njc")   # Raises ArgumentError
+#   Base64.strict_decode64("MDEyMzQ1Njc=")  # => "01234567"
+#   Base64.strict_decode64("MDEyMzQ1Njc==") # Raises ArgumentError
+#
+# \Method Base64.urlsafe_decode64 allows padding in the encoded string,
+# which if present, must be correct:
+# see {Padding}[Base64.html#module-Base64-label-Padding], above:
+#
+#   Base64.urlsafe_decode64("MDEyMzQ1Njc") # => "01234567"
+#   Base64.urlsafe_decode64("MDEyMzQ1Njc=") # => "01234567"
+#   Base64.urlsafe_decode64("MDEyMzQ1Njc==") # Raises ArgumentError.
+#
+# == Newlines
+#
+# An encoded string returned by Base64.encode64 or Base64.urlsafe_encode64
+# has an embedded newline character
+# after each 60-character sequence, and, if non-empty, at the end:
+#
+#   # No newline if empty.
+#   encoded = Base64.encode64("\x00" *  0)
+#   encoded.index("\n") # => nil
+#
+#   # Newline at end of short output.
+#   encoded = Base64.encode64("\x00" *  1)
+#   encoded.size        # => 4
+#   encoded.index("\n") # => 4
+#
+#   # Newline at end of longer output.
+#   encoded = Base64.encode64("\x00" * 45)
+#   encoded.size        # => 60
+#   encoded.index("\n") # => 60
+#
+#   # Newlines embedded and at end of still longer output.
+#   encoded = Base64.encode64("\x00" * 46)
+#   encoded.size                          # => 65
+#   encoded.rindex("\n")                  # => 65
+#   encoded.split("\n").map {|s| s.size } # => [60, 4]
+#
+# The string to be encoded may itself contain newlines,
+# which are encoded as \Base64:
+#
+#      #   Base64.encode64("\n\n\n") # => "CgoK\n"
+#    s = "This is line 1\nThis is line 2\n"
+#    Base64.encode64(s) # => "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK\n"
 #
-# The purpose of using base64 to encode data is that it translates any
-# binary data into purely printable characters.
-
 module Base64
+
+  VERSION = "0.3.0"
+
   module_function
 
-  # Returns the Base64-encoded version of +bin+.
-  # This method complies with RFC 2045.
-  # Line feeds are added to every 60 encoded characters.
+  # :call-seq:
+  #   Base64.encode64(string) -> encoded_string
+  #
+  # Returns a string containing the RFC-2045-compliant \Base64-encoding of +string+.
+  #
+  # Per RFC 2045, the returned string may contain the URL-unsafe characters
+  # <tt>+</tt> or <tt>/</tt>;
+  # see {Encoding Character Set}[Base64.html#module-Base64-label-Encoding+Character+Sets] above:
+  #
+  #   Base64.encode64("\xFB\xEF\xBE") # => "++++\n"
+  #   Base64.encode64("\xFF\xFF\xFF") # => "////\n"
+  #
+  # The returned string may include padding;
+  # see {Padding}[Base64.html#module-Base64-label-Padding] above.
+  #
+  #   Base64.encode64('*') # => "Kg==\n"
   #
-  #    require 'base64'
-  #    Base64.encode64("Now is the time for all good coders\nto learn Ruby")
+  # The returned string ends with a newline character, and if sufficiently long
+  # will have one or more embedded newline characters;
+  # see {Newlines}[Base64.html#module-Base64-label-Newlines] above:
   #
-  # <i>Generates:</i>
+  #   Base64.encode64('*') # => "Kg==\n"
+  #   Base64.encode64('*' * 46)
+  #   # => "KioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioq\nKg==\n"
+  #
+  # The string to be encoded may itself contain newlines,
+  # which will be encoded as ordinary \Base64:
+  #
+  #   Base64.encode64("\n\n\n") # => "CgoK\n"
+  #   s = "This is line 1\nThis is line 2\n"
+  #   Base64.encode64(s) # => "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK\n"
   #
-  #    Tm93IGlzIHRoZSB0aW1lIGZvciBhbGwgZ29vZCBjb2RlcnMKdG8gbGVhcm4g
-  #    UnVieQ==
   def encode64(bin)
     [bin].pack("m")
   end
 
-  # Returns the Base64-decoded version of +str+.
-  # This method complies with RFC 2045.
-  # Characters outside the base alphabet are ignored.
-  #
-  #   require 'base64'
-  #   str = 'VGhpcyBpcyBsaW5lIG9uZQpUaGlzIG' +
-  #         'lzIGxpbmUgdHdvClRoaXMgaXMgbGlu' +
-  #         'ZSB0aHJlZQpBbmQgc28gb24uLi4K'
-  #   puts Base64.decode64(str)
-  #
-  # <i>Generates:</i>
-  #
-  #    This is line one
-  #    This is line two
-  #    This is line three
-  #    And so on...
+  # :call-seq:
+  #   Base64.decode(encoded_string) -> decoded_string
+  #
+  # Returns a string containing the decoding of an RFC-2045-compliant
+  # \Base64-encoded string +encoded_string+:
+  #
+  #   s = "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK\n"
+  #   Base64.decode64(s) # => "This is line 1\nThis is line 2\n"
+  #
+  # Non-\Base64 characters in +encoded_string+ are ignored;
+  # see {Encoding Character Set}[Base64.html#module-Base64-label-Encoding+Character+Sets] above:
+  # these include newline characters and characters <tt>-</tt> and <tt>/</tt>:
+  #
+  #   Base64.decode64("\x00\n-_") # => ""
+  #
+  # Padding in +encoded_string+ (even if incorrect) is ignored:
+  #
+  #   Base64.decode64("MDEyMzQ1Njc")   # => "01234567"
+  #   Base64.decode64("MDEyMzQ1Njc=")  # => "01234567"
+  #   Base64.decode64("MDEyMzQ1Njc==") # => "01234567"
+  #
   def decode64(str)
-    str.unpack("m").first
+    str.unpack1("m")
   end
 
-  # Returns the Base64-encoded version of +bin+.
-  # This method complies with RFC 4648.
-  # No line feeds are added.
+  # :call-seq:
+  #   Base64.strict_encode64(string) -> encoded_string
+  #
+  # Returns a string containing the RFC-2045-compliant \Base64-encoding of +string+.
+  #
+  # Per RFC 2045, the returned string may contain the URL-unsafe characters
+  # <tt>+</tt> or <tt>/</tt>;
+  # see {Encoding Character Set}[Base64.html#module-Base64-label-Encoding+Character+Sets] above:
+  #
+  #   Base64.strict_encode64("\xFB\xEF\xBE") # => "++++\n"
+  #   Base64.strict_encode64("\xFF\xFF\xFF") # => "////\n"
+  #
+  # The returned string may include padding;
+  # see {Padding}[Base64.html#module-Base64-label-Padding] above.
+  #
+  #   Base64.strict_encode64('*') # => "Kg==\n"
+  #
+  # The returned string will have no newline characters, regardless of its length;
+  # see {Newlines}[Base64.html#module-Base64-label-Newlines] above:
+  #
+  #   Base64.strict_encode64('*') # => "Kg=="
+  #   Base64.strict_encode64('*' * 46)
+  #   # => "KioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKg=="
+  #
+  # The string to be encoded may itself contain newlines,
+  # which will be encoded as ordinary \Base64:
+  #
+  #   Base64.strict_encode64("\n\n\n") # => "CgoK"
+  #   s = "This is line 1\nThis is line 2\n"
+  #   Base64.strict_encode64(s) # => "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK"
+  #
   def strict_encode64(bin)
     [bin].pack("m0")
   end
 
-  # Returns the Base64-decoded version of +str+.
-  # This method complies with RFC 4648.
-  # ArgumentError is raised if +str+ is incorrectly padded or contains
-  # non-alphabet characters.  Note that CR or LF are also rejected.
+  # :call-seq:
+  #   Base64.strict_decode64(encoded_string) -> decoded_string
+  #
+  # Returns a string containing the decoding of an RFC-2045-compliant
+  # \Base64-encoded string +encoded_string+:
+  #
+  #   s = "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK"
+  #   Base64.strict_decode64(s) # => "This is line 1\nThis is line 2\n"
+  #
+  # Non-\Base64 characters in +encoded_string+ are not allowed;
+  # see {Encoding Character Set}[Base64.html#module-Base64-label-Encoding+Character+Sets] above:
+  # these include newline characters and characters <tt>-</tt> and <tt>/</tt>:
+  #
+  #   Base64.strict_decode64("\n") # Raises ArgumentError
+  #   Base64.strict_decode64('-')  # Raises ArgumentError
+  #   Base64.strict_decode64('_')  # Raises ArgumentError
+  #
+  # Padding in +encoded_string+, if present, must be correct:
+  #
+  #   Base64.strict_decode64("MDEyMzQ1Njc")   # Raises ArgumentError
+  #   Base64.strict_decode64("MDEyMzQ1Njc=")  # => "01234567"
+  #   Base64.strict_decode64("MDEyMzQ1Njc==") # Raises ArgumentError
+  #
   def strict_decode64(str)
-    str.unpack("m0").first
+    str.unpack1("m0")
   end
 
-  # Returns the Base64-encoded version of +bin+.
-  # This method complies with ``Base 64 Encoding with URL and Filename Safe
-  # Alphabet'' in RFC 4648.
-  # The alphabet uses '-' instead of '+' and '_' instead of '/'.
-  # Note that the result can still contain '='.
-  # You can remove the padding by setting +padding+ as false.
+  # :call-seq:
+  #   Base64.urlsafe_encode64(string) -> encoded_string
+  #
+  # Returns the RFC-4648-compliant \Base64-encoding of +string+.
+  #
+  # Per RFC 4648, the returned string will not contain the URL-unsafe characters
+  # <tt>+</tt> or <tt>/</tt>,
+  # but instead may contain the URL-safe characters
+  # <tt>-</tt> and <tt>_</tt>;
+  # see {Encoding Character Set}[Base64.html#module-Base64-label-Encoding+Character+Sets] above:
+  #
+  #   Base64.urlsafe_encode64("\xFB\xEF\xBE") # => "----"
+  #   Base64.urlsafe_encode64("\xFF\xFF\xFF") # => "____"
+  #
+  # By default, the returned string may have padding;
+  # see {Padding}[Base64.html#module-Base64-label-Padding], above:
+  #
+  #   Base64.urlsafe_encode64('*') # => "Kg=="
+  #
+  # Optionally, you can suppress padding:
+  #
+  #   Base64.urlsafe_encode64('*', padding: false) # => "Kg"
+  #
+  # The returned string will have no newline characters, regardless of its length;
+  # see {Newlines}[Base64.html#module-Base64-label-Newlines] above:
+  #
+  #   Base64.urlsafe_encode64('*') # => "Kg=="
+  #   Base64.urlsafe_encode64('*' * 46)
+  #   # => "KioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKg=="
+  #
   def urlsafe_encode64(bin, padding: true)
     str = strict_encode64(bin)
     str.chomp!("==") or str.chomp!("=") unless padding
@@ -87,14 +347,25 @@ module Base64
     str
   end
 
-  # Returns the Base64-decoded version of +str+.
-  # This method complies with ``Base 64 Encoding with URL and Filename Safe
-  # Alphabet'' in RFC 4648.
-  # The alphabet uses '-' instead of '+' and '_' instead of '/'.
-  #
-  # The padding character is optional.
-  # This method accepts both correctly-padded and unpadded input.
-  # Note that it still rejects incorrectly-padded input.
+  # :call-seq:
+  #   Base64.urlsafe_decode64(encoded_string) -> decoded_string
+  #
+  # Returns the decoding of an RFC-4648-compliant \Base64-encoded string +encoded_string+:
+  #
+  # +encoded_string+ may not contain non-Base64 characters;
+  # see {Encoding Character Set}[Base64.html#module-Base64-label-Encoding+Character+Sets] above:
+  #
+  #   Base64.urlsafe_decode64('+')  # Raises ArgumentError.
+  #   Base64.urlsafe_decode64('/')  # Raises ArgumentError.
+  #   Base64.urlsafe_decode64("\n") # Raises ArgumentError.
+  #
+  # Padding in +encoded_string+, if present, must be correct:
+  # see {Padding}[Base64.html#module-Base64-label-Padding], above:
+  #
+  #   Base64.urlsafe_decode64("MDEyMzQ1Njc") # => "01234567"
+  #   Base64.urlsafe_decode64("MDEyMzQ1Njc=") # => "01234567"
+  #   Base64.urlsafe_decode64("MDEyMzQ1Njc==") # Raises ArgumentError.
+  #
   def urlsafe_decode64(str)
     # NOTE: RFC 4648 does say nothing about unpadded input, but says that
     # "the excess pad characters MAY also be ignored", so it is inferred that

data/sig/base64.rbs

@@ -0,0 +1,355 @@
+# <!-- rdoc-file=lib/base64.rb -->
+# Module Base64 provides methods for:
+#
+# *   Encoding a binary string (containing non-ASCII characters) as a string of
+#     printable ASCII characters.
+# *   Decoding such an encoded string.
+#
+# Base64 is commonly used in contexts where binary data is not allowed or
+# supported:
+#
+# *   Images in HTML or CSS files, or in URLs.
+# *   Email attachments.
+#
+# A Base64-encoded string is about one-third larger that its source. See the
+# [Wikipedia article](https://en.wikipedia.org/wiki/Base64) for more
+# information.
+#
+# This module provides three pairs of encode/decode methods. Your choices among
+# these methods should depend on:
+#
+# *   Which character set is to be used for encoding and decoding.
+# *   Whether "padding" is to be used.
+# *   Whether encoded strings are to contain newlines.
+#
+# Note: Examples on this page assume that the including program has executed:
+#
+#     require 'base64'
+#
+# ## Encoding Character Sets
+#
+# A Base64-encoded string consists only of characters from a 64-character set:
+#
+# *   `('A'..'Z')`.
+# *   `('a'..'z')`.
+# *   `('0'..'9')`.
+# *   `=`, the 'padding' character.
+# *   Either:
+#     *   `%w[+ /]`:
+#         [RFC-2045-compliant](https://datatracker.ietf.org/doc/html/rfc2045);
+#         *not* safe for URLs.
+#     *   `%w[- _]`:
+#         [RFC-4648-compliant](https://datatracker.ietf.org/doc/html/rfc4648);
+#         safe for URLs.
+#
+# If you are working with Base64-encoded strings that will come from or be put
+# into URLs, you should choose this encoder-decoder pair of RFC-4648-compliant
+# methods:
+#
+# *   Base64.urlsafe_encode64 and Base64.urlsafe_decode64.
+#
+# Otherwise, you may choose any of the pairs in this module, including the pair
+# above, or the RFC-2045-compliant pairs:
+#
+# *   Base64.encode64 and Base64.decode64.
+# *   Base64.strict_encode64 and Base64.strict_decode64.
+#
+# ## Padding
+#
+# Base64-encoding changes a triplet of input bytes into a quartet of output
+# characters.
+#
+# **Padding in Encode Methods**
+#
+# Padding -- extending an encoded string with zero, one, or two trailing `=`
+# characters -- is performed by methods Base64.encode64, Base64.strict_encode64,
+# and, by default, Base64.urlsafe_encode64:
+#
+#     Base64.encode64('s')                         # => "cw==\n"
+#     Base64.strict_encode64('s')                  # => "cw=="
+#     Base64.urlsafe_encode64('s')                 # => "cw=="
+#     Base64.urlsafe_encode64('s', padding: false) # => "cw"
+#
+# When padding is performed, the encoded string is always of length *4n*, where
+# `n` is a non-negative integer:
+#
+# *   Input bytes of length *3n* generate unpadded output characters of length
+#     *4n*:
+#
+#         # n = 1:  3 bytes => 4 characters.
+#         Base64.strict_encode64('123')      # => "MDEy"
+#         # n = 2:  6 bytes => 8 characters.
+#         Base64.strict_encode64('123456')   # => "MDEyMzQ1"
+#
+# *   Input bytes of length *3n+1* generate padded output characters of length
+#     *4(n+1)*, with two padding characters at the end:
+#
+#         # n = 1:  4 bytes => 8 characters.
+#         Base64.strict_encode64('1234')     # => "MDEyMw=="
+#         # n = 2:  7 bytes => 12 characters.
+#         Base64.strict_encode64('1234567')  # => "MDEyMzQ1Ng=="
+#
+# *   Input bytes of length *3n+2* generate padded output characters of length
+#     *4(n+1)*, with one padding character at the end:
+#
+#         # n = 1:  5 bytes => 8 characters.
+#         Base64.strict_encode64('12345')    # => "MDEyMzQ="
+#         # n = 2:  8 bytes => 12 characters.
+#         Base64.strict_encode64('12345678') # => "MDEyMzQ1Njc="
+#
+# When padding is suppressed, for a positive integer *n*:
+#
+# *   Input bytes of length *3n* generate unpadded output characters of length
+#     *4n*:
+#
+#         # n = 1:  3 bytes => 4 characters.
+#         Base64.urlsafe_encode64('123', padding: false)      # => "MDEy"
+#         # n = 2:  6 bytes => 8 characters.
+#         Base64.urlsafe_encode64('123456', padding: false)   # => "MDEyMzQ1"
+#
+# *   Input bytes of length *3n+1* generate unpadded output characters of length
+#     *4n+2*, with two padding characters at the end:
+#
+#         # n = 1:  4 bytes => 6 characters.
+#         Base64.urlsafe_encode64('1234', padding: false)     # => "MDEyMw"
+#         # n = 2:  7 bytes => 10 characters.
+#         Base64.urlsafe_encode64('1234567', padding: false)  # => "MDEyMzQ1Ng"
+#
+# *   Input bytes of length *3n+2* generate unpadded output characters of length
+#     *4n+3*, with one padding character at the end:
+#
+#         # n = 1:  5 bytes => 7 characters.
+#         Base64.urlsafe_encode64('12345', padding: false)    # => "MDEyMzQ"
+#         # m = 2:  8 bytes => 11 characters.
+#         Base64.urlsafe_encode64('12345678', padding: false) # => "MDEyMzQ1Njc"
+#
+# **Padding in Decode Methods**
+#
+# All of the Base64 decode methods support (but do not require) padding.
+#
+# Method Base64.decode64 does not check the size of the padding:
+#
+#     Base64.decode64("MDEyMzQ1Njc") # => "01234567"
+#     Base64.decode64("MDEyMzQ1Njc=") # => "01234567"
+#     Base64.decode64("MDEyMzQ1Njc==") # => "01234567"
+#
+# Method Base64.strict_decode64 strictly enforces padding size:
+#
+#     Base64.strict_decode64("MDEyMzQ1Njc")   # Raises ArgumentError
+#     Base64.strict_decode64("MDEyMzQ1Njc=")  # => "01234567"
+#     Base64.strict_decode64("MDEyMzQ1Njc==") # Raises ArgumentError
+#
+# Method Base64.urlsafe_decode64 allows padding in `str`, which if present, must
+# be correct: see [Padding](Base64.html#module-Base64-label-Padding), above:
+#
+#     Base64.urlsafe_decode64("MDEyMzQ1Njc") # => "01234567"
+#     Base64.urlsafe_decode64("MDEyMzQ1Njc=") # => "01234567"
+#     Base64.urlsafe_decode64("MDEyMzQ1Njc==") # Raises ArgumentError.
+#
+# ## Newlines
+#
+# An encoded string returned by Base64.encode64 or Base64.urlsafe_encode64 has
+# an embedded newline character after each 60-character sequence, and, if
+# non-empty, at the end:
+#
+#     # No newline if empty.
+#     encoded = Base64.encode64("\x00" *  0)
+#     encoded.index("\n") # => nil
+#
+#     # Newline at end of short output.
+#     encoded = Base64.encode64("\x00" *  1)
+#     encoded.size        # => 4
+#     encoded.index("\n") # => 4
+#
+#     # Newline at end of longer output.
+#     encoded = Base64.encode64("\x00" * 45)
+#     encoded.size        # => 60
+#     encoded.index("\n") # => 60
+#
+#     # Newlines embedded and at end of still longer output.
+#     encoded = Base64.encode64("\x00" * 46)
+#     encoded.size                          # => 65
+#     encoded.rindex("\n")                  # => 65
+#     encoded.split("\n").map {|s| s.size } # => [60, 4]
+#
+# The string to be encoded may itself contain newlines, which are encoded as
+# Base64:
+#
+#       #   Base64.encode64("\n\n\n") # => "CgoK\n"
+#     s = "This is line 1\nThis is line 2\n"
+#     Base64.encode64(s) # => "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK\n"
+#
+module Base64
+  # <!--
+  #   rdoc-file=lib/base64.rb
+  #   - decode64(str)
+  # -->
+  # Returns a string containing the decoding of an RFC-2045-compliant
+  # Base64-encoded string `str`:
+  #
+  #     s = "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK\n"
+  #     Base64.decode64(s) # => "This is line 1\nThis is line 2\n"
+  #
+  # Non-Base64 characters in `str` are ignored; see [Encoding Character
+  # Set](Base64.html#module-Base64-label-Encoding+Character+Sets) above: these
+  # include newline characters and characters `-` and `/`:
+  #
+  #     Base64.decode64("\x00\n-_") # => ""
+  #
+  # Padding in `str` (even if incorrect) is ignored:
+  #
+  #     Base64.decode64("MDEyMzQ1Njc")   # => "01234567"
+  #     Base64.decode64("MDEyMzQ1Njc=")  # => "01234567"
+  #     Base64.decode64("MDEyMzQ1Njc==") # => "01234567"
+  #
+  def self?.decode64: (String str) -> String
+
+  # <!--
+  #   rdoc-file=lib/base64.rb
+  #   - encode64(bin)
+  # -->
+  # Returns a string containing the RFC-2045-compliant Base64-encoding of `bin`.
+  #
+  # Per RFC 2045, the returned string may contain the URL-unsafe characters `+` or
+  # `/`; see [Encoding Character
+  # Set](Base64.html#module-Base64-label-Encoding+Character+Sets) above:
+  #
+  #     Base64.encode64("\xFB\xEF\xBE") # => "++++\n"
+  #     Base64.encode64("\xFF\xFF\xFF") # => "////\n"
+  #
+  # The returned string may include padding; see
+  # [Padding](Base64.html#module-Base64-label-Padding) above.
+  #
+  #     Base64.encode64('*') # => "Kg==\n"
+  #
+  # The returned string ends with a newline character, and if sufficiently long
+  # will have one or more embedded newline characters; see
+  # [Newlines](Base64.html#module-Base64-label-Newlines) above:
+  #
+  #     Base64.encode64('*') # => "Kg==\n"
+  #     Base64.encode64('*' * 46)
+  #     # => "KioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioq\nKg==\n"
+  #
+  # The string to be encoded may itself contain newlines, which will be encoded as
+  # ordinary Base64:
+  #
+  #     Base64.encode64("\n\n\n") # => "CgoK\n"
+  #     s = "This is line 1\nThis is line 2\n"
+  #     Base64.encode64(s) # => "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK\n"
+  #
+  def self?.encode64: (String bin) -> String
+
+  # <!--
+  #   rdoc-file=lib/base64.rb
+  #   - strict_decode64(str)
+  # -->
+  # Returns a string containing the decoding of an RFC-2045-compliant
+  # Base64-encoded string `str`:
+  #
+  #     s = "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK"
+  #     Base64.strict_decode64(s) # => "This is line 1\nThis is line 2\n"
+  #
+  # Non-Base64 characters in `str` not allowed; see [Encoding Character
+  # Set](Base64.html#module-Base64-label-Encoding+Character+Sets) above: these
+  # include newline characters and characters `-` and `/`:
+  #
+  #     Base64.strict_decode64("\n") # Raises ArgumentError
+  #     Base64.strict_decode64('-')  # Raises ArgumentError
+  #     Base64.strict_decode64('_')  # Raises ArgumentError
+  #
+  # Padding in `str`, if present, must be correct:
+  #
+  #     Base64.strict_decode64("MDEyMzQ1Njc")   # Raises ArgumentError
+  #     Base64.strict_decode64("MDEyMzQ1Njc=")  # => "01234567"
+  #     Base64.strict_decode64("MDEyMzQ1Njc==") # Raises ArgumentError
+  #
+  def self?.strict_decode64: (String str) -> String
+
+  # <!--
+  #   rdoc-file=lib/base64.rb
+  #   - strict_encode64(bin)
+  # -->
+  # Returns a string containing the RFC-2045-compliant Base64-encoding of `bin`.
+  #
+  # Per RFC 2045, the returned string may contain the URL-unsafe characters `+` or
+  # `/`; see [Encoding Character
+  # Set](Base64.html#module-Base64-label-Encoding+Character+Sets) above:
+  #
+  #     Base64.strict_encode64("\xFB\xEF\xBE") # => "++++\n"
+  #     Base64.strict_encode64("\xFF\xFF\xFF") # => "////\n"
+  #
+  # The returned string may include padding; see
+  # [Padding](Base64.html#module-Base64-label-Padding) above.
+  #
+  #     Base64.strict_encode64('*') # => "Kg==\n"
+  #
+  # The returned string will have no newline characters, regardless of its length;
+  # see [Newlines](Base64.html#module-Base64-label-Newlines) above:
+  #
+  #     Base64.strict_encode64('*') # => "Kg=="
+  #     Base64.strict_encode64('*' * 46)
+  #     # => "KioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKg=="
+  #
+  # The string to be encoded may itself contain newlines, which will be encoded as
+  # ordinary Base64:
+  #
+  #     Base64.strict_encode64("\n\n\n") # => "CgoK"
+  #     s = "This is line 1\nThis is line 2\n"
+  #     Base64.strict_encode64(s) # => "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK"
+  #
+  def self?.strict_encode64: (String bin) -> String
+
+  # <!--
+  #   rdoc-file=lib/base64.rb
+  #   - urlsafe_decode64(str)
+  # -->
+  # Returns the decoding of an RFC-4648-compliant Base64-encoded string `str`:
+  #
+  # `str` may not contain non-Base64 characters; see [Encoding Character
+  # Set](Base64.html#module-Base64-label-Encoding+Character+Sets) above:
+  #
+  #     Base64.urlsafe_decode64('+')  # Raises ArgumentError.
+  #     Base64.urlsafe_decode64('/')  # Raises ArgumentError.
+  #     Base64.urlsafe_decode64("\n") # Raises ArgumentError.
+  #
+  # Padding in `str`, if present, must be correct: see
+  # [Padding](Base64.html#module-Base64-label-Padding), above:
+  #
+  #     Base64.urlsafe_decode64("MDEyMzQ1Njc") # => "01234567"
+  #     Base64.urlsafe_decode64("MDEyMzQ1Njc=") # => "01234567"
+  #     Base64.urlsafe_decode64("MDEyMzQ1Njc==") # Raises ArgumentError.
+  #
+  def self?.urlsafe_decode64: (String str) -> String
+
+  # <!--
+  #   rdoc-file=lib/base64.rb
+  #   - urlsafe_encode64(bin, padding: true)
+  # -->
+  # Returns the RFC-4648-compliant Base64-encoding of `bin`.
+  #
+  # Per RFC 4648, the returned string will not contain the URL-unsafe characters
+  # `+` or `/`, but instead may contain the URL-safe characters `-` and `_`; see
+  # [Encoding Character
+  # Set](Base64.html#module-Base64-label-Encoding+Character+Sets) above:
+  #
+  #     Base64.urlsafe_encode64("\xFB\xEF\xBE") # => "----"
+  #     Base64.urlsafe_encode64("\xFF\xFF\xFF") # => "____"
+  #
+  # By default, the returned string may have padding; see
+  # [Padding](Base64.html#module-Base64-label-Padding), above:
+  #
+  #     Base64.urlsafe_encode64('*') # => "Kg=="
+  #
+  # Optionally, you can suppress padding:
+  #
+  #     Base64.urlsafe_encode64('*', padding: false) # => "Kg"
+  #
+  # The returned string will have no newline characters, regardless of its length;
+  # see [Newlines](Base64.html#module-Base64-label-Newlines) above:
+  #
+  #     Base64.urlsafe_encode64('*') # => "Kg=="
+  #     Base64.urlsafe_encode64('*' * 46)
+  #     # => "KioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKg=="
+  #
+  def self?.urlsafe_encode64: (String bin, ?padding: boolish) -> String
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: base64
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Yusuke Endoh
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Support for encoding and decoding binary data using a Base64 representation.
 email:
@@ -17,9 +16,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- LICENSE.txt
+- BSDL
+- COPYING
+- LEGAL
 - README.md
 - lib/base64.rb
+- sig/base64.rbs
 homepage: https://github.com/ruby/base64
 licenses:
 - Ruby
@@ -27,7 +29,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/ruby/base64
   source_code_uri: https://github.com/ruby/base64
-post_install_message:
+  changelog_uri: https://github.com/ruby/base64/releases
 rdoc_options: []
 require_paths:
 - lib
@@ -35,15 +37,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: '2.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Support for encoding and decoding binary data using a Base64 representation.
 test_files: []