ni.rb in uri-ni-0.1.2

- old
+ new

@@ -159,19 +159,44 @@
   end
 
   public
 
   # Compute an RFC6920 URI from a data source.
+  #
   # @param data [#to_s, IO, Digest, nil]
-  # @param algorithm [Symbol] See algorithms
+  # @param algorithm [Symbol] See available algorithms. Default: +:"sha-256"+
+  # @param blocksize [Integer] The number or bytes per call to the Digest
+  # @param authority [String, nil] Optional authority (user, host, port)
+  # @param query [String, nil] Optional query string
+  # @yield [ctx, buf] Passes the Digest and (maybe) the buffer
+  # @yieldparam ctx [Digest::Instance] The digest instance to the block
+  # @yieldparam buf [String, nil] The current read buffer (if +data+ is set)
+  # @yieldreturn [nil] The result of the block is ignored
+  # 
+  # @return [URI::NI] 
   def self.compute data = nil, algorithm: :"sha-256", blocksize: 65536,
       authority: nil, query: nil, &block
 
     build({ scheme: 'ni' }).compute data, algorithm: algorithm,
       blocksize: blocksize, authority: authority, query: query, &block
   end
 
+  # Return a Digest::Instance for a supported algorithm.
+  # @param  [#to_s, #to_sym]  The algorithm
+  # @return [Digest:Instance] The digest context
+  # @raise  [ArgumentError] if the algorithm is unrecognized
+  def self.context algorithm
+    raise ArgumentError, "Cannot coerce #{algorithm} to a symbol" unless
+      algorithm.respond_to(:to_s) # cheat: symbols respond to to_s
+    algorithm = algorithm.to_s.to_sym unless algorithm.is_a? Symbol
+    raise ArgumentError, "Unsupported digest algorithm #{algorithm}" unless
+      ctx = DIGESTS[algorithm]
+    ctx.new
+  end
+  
+  # (Re)-compute a digest using existing information from an instance.
+  # @see .compute
   def compute data = nil, algorithm: nil, blocksize: 65536,
       authority: nil, query: nil, &block
 
     # enforce block size
     raise ArgumentError,
@@ -184,11 +209,11 @@
       algorithm ||= algo_for data, algorithm
       ctx  = data
       data = nil # unset data
     else
       # make sure we're all on the same page hurr
-      self.algorithm = algorithm ||= self.algorithm
+      self.algorithm = algorithm ||= self.algorithm || :"sha-256"
       raise URI::InvalidComponentError,
         "Can't resolve a Digest context for the algorithm #{algorithm}." unless
         ctx = DIGESTS[algorithm]
       ctx = ctx.new
     end
@@ -286,10 +311,10 @@
     transcode raw_digest, from: 64, to: radix, alt: alt
   end
 
   # Set the digest to the data, with an optional radix. Data may
   # either be a +Digest::Instance+—in which case the radix is
-  # ignored–a string, or +nil+. +Digest::Instance+ objects will
+  # ignored—a string, or +nil+. +Digest::Instance+ objects will
   # just be run through #compute, with all that entails.
   #
   # @param value [String, nil, Digest::Instance] The new digest
   # @param radix [256, 64, 32, 16] The radix of the encoding (default 256)
   # @return [String] The _old_ digest in the given radix