ruby-changes:31584
From: zzak <ko1@a...>
Date: Wed, 13 Nov 2013 17:15:54 +0900 (JST)
Subject: [ruby-changes:31584] zzak:r43663 (trunk): * ext/openssl/lib/openssl/*.rb: [DOC] Document the following:
zzak 2013-11-13 17:15:48 +0900 (Wed, 13 Nov 2013) New Revision: 43663 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=43663 Log: * ext/openssl/lib/openssl/*.rb: [DOC] Document the following: - Integer#to_bn - OpenSSL::Buffering module - Document deprecated OpenSSL::Digest::Digest compatibility class - OpenSSL::Config These changes were based on a patch by @vbatts via GH-436 https://github.com/ruby/ruby/pull/436 Modified files: trunk/ChangeLog trunk/ext/openssl/lib/openssl/bn.rb trunk/ext/openssl/lib/openssl/buffering.rb trunk/ext/openssl/lib/openssl/config.rb trunk/ext/openssl/lib/openssl/digest.rb Index: ChangeLog =================================================================== --- ChangeLog (revision 43662) +++ ChangeLog (revision 43663) @@ -1,3 +1,15 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1 +Wed Nov 13 17:09:45 2013 Zachary Scott <e@z...> + + * ext/openssl/lib/openssl/*.rb: [DOC] Document the following: + + - Integer#to_bn + - OpenSSL::Buffering module + - Document deprecated OpenSSL::Digest::Digest compatibility class + - OpenSSL::Config + + These changes were based on a patch by @vbatts via GH-436 + https://github.com/ruby/ruby/pull/436 + Wed Nov 13 10:55:43 2013 Zachary Scott <e@z...> * doc/regexp.rdoc: [DOC] Fix typo in Special global variables section. Index: ext/openssl/lib/openssl/bn.rb =================================================================== --- ext/openssl/lib/openssl/bn.rb (revision 43662) +++ ext/openssl/lib/openssl/bn.rb (revision 43663) @@ -28,6 +28,9 @@ end # OpenSSL https://github.com/ruby/ruby/blob/trunk/ext/openssl/lib/openssl/bn.rb#L28 # Add double dispatch to Integer # class Integer + # Casts an Integer as an OpenSSL::BN + # + # See `man bn` for more info. def to_bn OpenSSL::BN::new(self) end Index: ext/openssl/lib/openssl/digest.rb =================================================================== --- ext/openssl/lib/openssl/digest.rb (revision 43662) +++ ext/openssl/lib/openssl/digest.rb (revision 43663) @@ -59,8 +59,13 @@ module OpenSSL https://github.com/ruby/ruby/blob/trunk/ext/openssl/lib/openssl/digest.rb#L59 const_set(name, klass) } - # This class is only provided for backwards compatibility. Use OpenSSL::Digest in the future. - class Digest < Digest + # This class is only provided for backwards compatibility. + # + # Use OpenSSL::Digest in the future. + class Digest < Digest # :nodoc: + # Deprecated. + # + # See OpenSSL::Digest.new def initialize(*args) # add warning super(*args) Index: ext/openssl/lib/openssl/config.rb =================================================================== --- ext/openssl/lib/openssl/config.rb (revision 43662) +++ ext/openssl/lib/openssl/config.rb (revision 43663) @@ -13,10 +13,25 @@ https://github.com/ruby/ruby/blob/trunk/ext/openssl/lib/openssl/config.rb#L13 require 'stringio' module OpenSSL + ## + # = OpenSSL::Config + # + # Configuration for the openssl library. + # + # Many system's installation of openssl library will depend on your system + # configuration. See the value of OpenSSL::Config::DEFAULT_CONFIG_FILE for + # the location of the file for your host. + # + # See also http://www.openssl.org/docs/apps/config.html class Config include Enumerable class << self + + ## + # Parses a given +str+ as a blob that contains configuration for openssl. + # + # If the source of the IO is a file, then consider using #parse_config. def parse(str) c = new() parse_config(StringIO.new(str)).each do |section, hash| @@ -25,8 +40,14 @@ module OpenSSL https://github.com/ruby/ruby/blob/trunk/ext/openssl/lib/openssl/config.rb#L40 c end + ## + # load is an alias to ::new alias load new + ## + # Parses the configuration data read from +io+, see also #parse. + # + # Raises a ConfigError on invalid configuration data. def parse_config(io) begin parse_config_lines(io) @@ -209,6 +230,18 @@ module OpenSSL https://github.com/ruby/ruby/blob/trunk/ext/openssl/lib/openssl/config.rb#L230 end end + ## + # Creates an instance of OpenSSL's configuration class. + # + # This can be used in contexts like OpenSSL::X509::ExtensionFactory.config= + # + # If the optional +filename+ parameter is provided, then it is read in and + # parsed via #parse_config. + # + # This can raise IO exceptions based on the access, or availability of the + # file. A ConfigError exception may be raised depending on the validity of + # the data being configured. + # def initialize(filename = nil) @data = {} if filename @@ -220,6 +253,23 @@ module OpenSSL https://github.com/ruby/ruby/blob/trunk/ext/openssl/lib/openssl/config.rb#L253 end end + ## + # Gets the value of +key+ from the given +section+ + # + # Given the following configurating file being loaded: + # + # config = OpenSSL::Config.load('foo.cnf') + # #=> #<OpenSSL::Config sections=["default"]> + # puts config.to_s + # #=> [ default ] + # # foo=bar + # + # You can get a specific value from the config if you know the +section+ + # and +key+ like so: + # + # config.get_value('default','foo') + # #=> "bar" + # def get_value(section, key) if section.nil? raise TypeError.new('nil not allowed') @@ -228,7 +278,12 @@ module OpenSSL https://github.com/ruby/ruby/blob/trunk/ext/openssl/lib/openssl/config.rb#L278 get_key_string(section, key) end - def value(arg1, arg2 = nil) + ## + # + # *Deprecated* + # + # Use #get_value instead + def value(arg1, arg2 = nil) # :nodoc: warn('Config#value is deprecated; use Config#get_value') if arg2.nil? section, key = 'default', arg1 @@ -240,20 +295,84 @@ module OpenSSL https://github.com/ruby/ruby/blob/trunk/ext/openssl/lib/openssl/config.rb#L295 get_key_string(section, key) end + ## + # Set the target +key+ with a given +value+ under a specific +section+. + # + # Given the following configurating file being loaded: + # + # config = OpenSSL::Config.load('foo.cnf') + # #=> #<OpenSSL::Config sections=["default"]> + # puts config.to_s + # #=> [ default ] + # # foo=bar + # + # You can set the value of +foo+ under the +default+ section to a new + # value: + # + # config.add_value('default', 'foo', 'buzz') + # #=> "buzz" + # puts config.to_s + # #=> [ default ] + # # foo=buzz + # def add_value(section, key, value) check_modify (@data[section] ||= {})[key] = value end + ## + # Get a specific +section+ from the current configuration + # + # Given the following configurating file being loaded: + # + # config = OpenSSL::Config.load('foo.cnf') + # #=> #<OpenSSL::Config sections=["default"]> + # puts config.to_s + # #=> [ default ] + # # foo=bar + # + # You can get a hash of the specific section like so: + # + # config['default'] + # #=> {"foo"=>"bar"} + # def [](section) @data[section] || {} end - def section(name) + ## + # Deprecated + # + # Use #[] instead + def section(name) # :nodoc: warn('Config#section is deprecated; use Config#[]') @data[name] || {} end + ## + # Sets a specific +section+ name with a Hash +pairs+ + # + # Given the following configuration being created: + # + # config = OpenSSL::Config.new + # #=> #<OpenSSL::Config sections=[]> + # config['default'] = {"foo"=>"bar","baz"=>"buz"} + # #=> {"foo"=>"bar", "baz"=>"buz"} + # puts config.to_s + # #=> [ default ] + # # foo=bar + # # baz=buz + # + # It's important to note that this will essentially merge any of the keys + # in +pairs+ with the existing +section+. For example: + # + # config['default'] + # #=> {"foo"=>"bar", "baz"=>"buz"} + # config['default'] = {"foo" => "changed"} + # #=> {"foo"=>"changed"} + # config['default'] + # #=> {"foo"=>"changed", "baz"=>"buz"} + # def []=(section, pairs) check_modify @data[section] ||= {} @@ -262,10 +381,38 @@ module OpenSSL https://github.com/ruby/ruby/blob/trunk/ext/openssl/lib/openssl/config.rb#L381 end end + ## + # Get the names of all sections in the current configuration def sections @data.keys end + ## + # Get the parsable form of the current configuration + # + # Given the following configuration being created: + # + # config = OpenSSL::Config.new + # #=> #<OpenSSL::Config sections=[]> + # config['default'] = {"foo"=>"bar","baz"=>"buz"} + # #=> {"foo"=>"bar", "baz"=>"buz"} + # puts config.to_s + # #=> [ default ] + # # foo=bar + # # baz=buz + # + # You can parse get the serialized configuration using #to_s and then parse + # it later: + # + # serialized_config = config.to_s + # # much later... + # new_config = OpenSSL::Config.parse(serialized_config) + # #=> #<OpenSSL::Config sections=["default"]> + # puts new_config + # #=> [ default ] + # foo=bar + # baz=buz + # def to_s ary = [] @data.keys.sort.each do |section| @@ -278,6 +425,15 @@ module OpenSSL https://github.com/ruby/ruby/blob/trunk/ext/openssl/lib/openssl/config.rb#L425 ary.join end + ## + # For a block. + # + # Receive the section and its pairs for the current configuration. + # + # config.each do |section, key, value| + # # ... + # end + # def each @data.each do |section, hash| hash.each do |key, value| @@ -286,13 +442,16 @@ module OpenSSL https://github.com/ruby/ruby/blob/trunk/ext/openssl/lib/openssl/config.rb#L442 end end + ## + # String representation of this configuration object, including the class + # name and its sections. def inspect "#<#{self.class.name} sections=#{sections.inspect}>" end protected - def data + def data # :nodoc: @data end Index: ext/openssl/lib/openssl/buffering.rb =================================================================== --- ext/openssl/lib/openssl/buffering.rb (revision 43662) +++ ext/openssl/lib/openssl/buffering.rb (revision 43663) @@ -18,6 +18,9 @@ https://github.com/ruby/ruby/blob/trunk/ext/openssl/lib/openssl/buffering.rb#L18 # OpenSSL IO buffering mix-in module. # # This module allows an OpenSSL::SSL::SSLSocket to behave like an IO. +# +# You typically won't use this module directly, you can see it implemented in +# OpenSSL::SSL::SSLSocket. module OpenSSL::Buffering include Enumerable @@ -34,6 +37,9 @@ module OpenSSL::Buffering https://github.com/ruby/ruby/blob/trunk/ext/openssl/lib/openssl/buffering.rb#L37 BLOCK_SIZE = 1024*16 + ## + # Creates an instance of OpenSSL's buffering IO module. + def initialize(*args) @eof = false @rbuffer = "" -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/