ruby-changes:13827
From: naruse <ko1@a...>
Date: Mon, 2 Nov 2009 11:24:33 +0900 (JST)
Subject: [ruby-changes:13827] Ruby:r25626 (trunk): * ext/dl/win32/lib/win32/registry.rb: update rdoc.
naruse 2009-11-02 11:24:11 +0900 (Mon, 02 Nov 2009) New Revision: 25626 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=25626 Log: * ext/dl/win32/lib/win32/registry.rb: update rdoc. [ruby-core:26022] Modified files: trunk/ChangeLog trunk/ext/dl/win32/lib/win32/registry.rb Index: ChangeLog =================================================================== --- ChangeLog (revision 25625) +++ ChangeLog (revision 25626) @@ -1,3 +1,7 @@ +Mon Nov 2 11:22:19 2009 NARUSE, Yui <naruse@r...> + + * ext/dl/win32/lib/win32/registry.rb: update rdoc. [ruby-core:26022] + Sun Nov 1 20:16:03 2009 NARUSE, Yui <naruse@r...> * ext/bigdecimal/bigdecimal.c: fixed rdoc. [ruby-core:26457] Index: ext/dl/win32/lib/win32/registry.rb =================================================================== --- ext/dl/win32/lib/win32/registry.rb (revision 25625) +++ ext/dl/win32/lib/win32/registry.rb (revision 25626) @@ -1,5 +1,9 @@ -=begin -= Win32 Registry I/F +require 'dl/import' +module Win32 + +=begin rdoc += Win32 Registry + win32/registry is registry accessor library for Win32 platform. It uses dl/import to call Win32 Registry APIs. @@ -24,247 +28,69 @@ == Win32::Registry class -=== including modules - -* Enumerable -* Registry::Constants - -=== class methods ---- Registry.open(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED) ---- Registry.open(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED) { |reg| ... } - Open the registry key ((|subkey|)) under ((|key|)). - ((|key|)) is Win32::Registry object of parent key. - You can use predefined key HKEY_* (see ((<constants>))) - - ((|desired|)) and ((|opt|)) is access mask and key option. - For detail, see ((<MSDN Library|URL:http://msdn.microsoft.com/library/en-us/sysinfo/base/regopenkeyex.asp>)). - - If block is given, the key is closed automatically. - ---- Registry.create(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED) ---- Registry.create(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED) { |reg| ... } - Create or open the registry key ((|subkey|)) under ((|key|)). - You can use predefined key HKEY_* (see ((<constants>))) - - If subkey is already exists, key is opened and Registry#((<created?>)) - method will return false. - - If block is given, the key is closed automatically. - ---- Registry.expand_environ(str) - Replace (({%\w+%})) into the environment value of ((|str|)). - This method is used for REG_EXPAND_SZ. - - For detail, see ((<ExpandEnvironmentStrings|URL:http://msdn.microsoft.com/library/en-us/sysinfo/base/expandenvironmentstrings.asp>)) Win32 API. - ---- Registry.type2name(type) - Convert registry type value to readable string. - ---- Registry.wtime2time(wtime) - Convert 64-bit FILETIME integer into Time object. - ---- Registry.time2wtime(time) - Convert Time object or Integer object into 64-bit FILETIME. - -=== instance methods ---- open(subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED) - Same as (({Win32::((<Registry.open>))(self, subkey, desired, opt)})) - ---- create(subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED) - Same as (({Win32::((<Registry.create>))(self, subkey, desired, opt)})) - ---- close - Close key. - - After closed, most method raises error. - ---- read(name, *rtype) - Read a registry value named ((|name|)) and return array of - [ ((|type|)), ((|data|)) ]. - When name is nil, the `default' value is read. - - ((|type|)) is value type. (see ((<Win32::Registry::Constants module>))) - ((|data|)) is value data, its class is: - :REG_SZ, REG_EXPAND_SZ - String - :REG_MULTI_SZ - Array of String - :REG_DWORD, REG_DWORD_BIG_ENDIAN, REG_QWORD - Integer - :REG_BINARY - String (contains binary data) - - When ((|rtype|)) is specified, the value type must be included by - ((|rtype|)) array, or TypeError is raised. - ---- self[name, *rtype] - Read a registry value named ((|name|)) and return its value data. - The class of value is same as ((<read>)) method returns. - - If the value type is REG_EXPAND_SZ, returns value data whose environment - variables are replaced. - If the value type is neither REG_SZ, REG_MULTI_SZ, REG_DWORD, - REG_DWORD_BIG_ENDIAN, nor REG_QWORD, TypeError is raised. - - The meaning of ((|rtype|)) is same as ((<read>)) method. - ---- read_s(name) ---- read_i(name) ---- read_bin(name) - Read a REG_SZ(read_s), REG_DWORD(read_i), or REG_BINARY(read_bin) - registry value named ((|name|)). - - If the values type does not match, TypeError is raised. - ---- read_s_expand(name) - Read a REG_SZ or REG_EXPAND_SZ registry value named ((|name|)). - - If the value type is REG_EXPAND_SZ, environment variables are replaced. - Unless the value type is REG_SZ or REG_EXPAND_SZ, TypeError is raised. - ---- write(name, type, data) - Write ((|data|)) to a registry value named ((|name|)). - When name is nil, write to the `default' value. - - ((|type|)) is type value. (see ((<Registry::Constants module>))) - Class of ((|data|)) must be same as which ((<read>)) - method returns. - ---- self[name, wtype = nil] = value - Write ((|value|)) to a registry value named ((|name|)). - - If ((|wtype|)) is specified, the value type is it. - Otherwise, the value type is depend on class of ((|value|)): - :Integer - REG_DWORD - :String - REG_SZ - :Array - REG_MULTI_SZ - ---- write_s(name, value) ---- write_i(name, value) ---- write_bin(name, value) - Write ((|value|)) to a registry value named ((|name|)). - - The value type is REG_SZ(write_s), REG_DWORD(write_i), or - REG_BINARY(write_bin). - ---- each { |name, type, value| ... } ---- each_value { |name, type, value| ... } - Enumerate values. - ---- each_key { |subkey, wtime| ... } - Enumerate subkeys. - - ((|subkey|)) is String which contains name of subkey. - ((|wtime|)) is last write time as FILETIME (64-bit integer). - (see ((<Registry.wtime2time>))) - ---- delete(name) ---- delete_value(name) - Delete a registry value named ((|name|)). - We can not delete the `default' value. - ---- delete_key(name, recursive = false) - Delete a subkey named ((|name|)) and all its values. - - If ((|recursive|)) is false, the subkey must not have subkeys. - Otherwise, this method deletes all subkeys and values recursively. - ---- flush - Write all the attributes into the registry file. - ---- created? - Returns if key is created ((*newly*)). - (see ((<Registry.create>))) - ---- open? - Returns if key is not closed. - ---- hkey - Returns key handle value. - ---- parent - Win32::Registry object of parent key, or nil if predefeined key. - ---- keyname - Same as ((|subkey|)) value of ((<Registry.open>)) or - ((<Registry.create>)) method. - ---- disposition - Disposition value (REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY). - ---- name ---- to_s - Full path of key such as (({'HKEY_CURRENT_USER\SOFTWARE\foo\bar'})). - --- info - Returns key information as Array of: - :num_keys - The number of subkeys. - :max_key_length - Maximum length of name of subkeys. - :num_values - The number of values. - :max_value_name_length - Maximum length of name of values. - :max_value_length - Maximum length of value of values. - :descriptor_length - Length of security descriptor. - :wtime - Last write time as FILETIME(64-bit integer) - For detail, see ((<RegQueryInfoKey|URL:http://msdn.microsoft.com/library/en-us/sysinfo/base/regqueryinfokey.asp>)) Win32 API. +--- num_keys ---- num_keys --- max_key_length + --- num_values + --- max_value_name_length + --- max_value_length + --- descriptor_length + --- wtime Returns an item of key information. === constants --- HKEY_CLASSES_ROOT + --- HKEY_CURRENT_USER + --- HKEY_LOCAL_MACHINE + --- HKEY_PERFORMANCE_DATA + --- HKEY_CURRENT_CONFIG + --- HKEY_DYN_DATA + Win32::Registry object whose key is predefined key. - For detail, see ((<MSDN Library|URL:http://msdn.microsoft.com/library/en-us/sysinfo/base/predefined_keys.asp>)). +For detail, see the MSDN[http://msdn.microsoft.com/library/en-us/sysinfo/base/predefined_keys.asp] article. -== Win32::Registry::Constants module +=end rdoc -For detail, see ((<MSDN Library|URL:http://msdn.microsoft.com/library/en-us/sysinfo/base/registry.asp>)). + class Registry ---- HKEY_* - Predefined key ((*handle*)). - These are Integer, not Win32::Registry. - ---- REG_* - Registry value type. - ---- KEY_* - Security access mask. - ---- KEY_OPTIONS_* - Key options. - ---- REG_CREATED_NEW_KEY ---- REG_OPENED_EXISTING_KEY - If the key is created newly or opened existing key. - See also Registry#((<disposition>)) method. - -=end - -require 'dl/import' - -module Win32 - class Registry + # + # For detail, see the MSDN[http://msdn.microsoft.com/library/en-us/sysinfo/base/registry.asp]. + # + # --- HKEY_* + # + # Predefined key ((*handle*)). + # These are Integer, not Win32::Registry. + # + # --- REG_* + # + # Registry value type. + # + # --- KEY_* + # + # Security access mask. + # + # --- KEY_OPTIONS_* + # + # Key options. + # + # --- REG_CREATED_NEW_KEY + # + # --- REG_OPENED_EXISTING_KEY + # + # If the key is created newly or opened existing key. + # See also Registry#disposition method. module Constants HKEY_CLASSES_ROOT = 0x80000000 HKEY_CURRENT_USER = 0x80000001 @@ -365,7 +191,7 @@ raise Error.new(5) ## ERROR_ACCESS_DENIED end - # Fake class for Registry#open, Registry#create + # Fake #class method for Registry#open, Registry#create def class Registry end @@ -498,8 +324,11 @@ end # - # utility functions + # Replace %\w+% into the environment value of what is contained between the %'s + # This method is used for REG_EXPAND_SZ. # + # For detail, see expandEnvironmentStrings[http://msdn.microsoft.com/library/en-us/sysinfo/base/expandenvironmentstrings.asp] \Win32 \API. + # def self.expand_environ(str) str.gsub(/%([^%]+)%/) { ENV[$1] || ENV[$1.upcase] || $& } end @@ -514,23 +343,43 @@ @@type2name[Constants.const_get(type)] = type end + # + # Convert registry type value to readable string. + # def self.type2name(type) @@type2name[type] || type.to_s end + # + # Convert 64-bit FILETIME integer into Time object. + # def self.wtime2time(wtime) Time.at((wtime - 116444736000000000) / 10000000) end + # + # Convert Time object or Integer object into 64-bit FILETIME. + # def self.time2wtime(time) time.to_i * 10000000 + 116444736000000000 end # - # constructors + # constructor # private_class_method :new + # + # --- Registry.open(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED) + # + # --- Registry.open(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED) { |reg| ... } + # + # Open the registry key subkey under key. + # key is Win32::Registry object of parent key. + # You can use predefined key HKEY_* (see Constants) + # desired and opt is access mask and key option. + # For detail, see the MSDN[http://msdn.microsoft.com/library/en-us/sysinfo/base/regopenkeyex.asp]. + # If block is given, the key is closed automatically. def self.open(hkey, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED) subkey = subkey.chomp('\\') newkey = API.OpenKey(hkey.hkey, subkey, opt, desired) @@ -546,6 +395,19 @@ end end + # + # --- Registry.create(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED) + # + # --- Registry.create(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED) { |reg| ... } + # + # Create or open the registry key subkey under key. + # You can use predefined key HKEY_* (see Constants) + # + # If subkey is already exists, key is opened and Registry#created? + # method will return false. + # + # If block is given, the key is closed automatically. + # def self.create(hkey, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED) newkey, disp = API.CreateKey(hkey.hkey, subkey, opt, desired) obj = new(newkey, hkey, subkey, disp) @@ -576,19 +438,37 @@ @hkeyfinal = [ hkey ] ObjectSpace.define_finalizer self, @@final.call(@hkeyfinal) end - attr_reader :hkey, :parent, :keyname, :disposition + # Returns key handle value. + attr_reader :hkey + # Win32::Registry object of parent key, or nil if predefeined key. + attr_reader :parent + # Same as subkey value of Registry.open or + # Registry.create method. + attr_reader :keyname + # Disposition value (REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY). + attr_reader :disposition + # - # attributes + # Returns if key is created ((*newly*)). + # (see Registry.create) -- basically you call create + # then when you call created? on the instance returned + # it will tell if it was successful or not # def created? @disposition == REG_CREATED_NEW_KEY end + # + # Returns if key is not closed. + # def open? !@hkey.nil? end + # + # Full path of key such as 'HKEY_CURRENT_USER\SOFTWARE\foo\bar'. + # def name parent = self name = @keyname @@ -603,23 +483,31 @@ end # - # marshalling + # marshalling is not allowed # def _dump(depth) raise TypeError, "can't dump Win32::Registry" end # - # open/close + # Same as Win32::Registry.open (self, subkey, desired, opt) # def open(subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED, &blk) self.class.open(self, subkey, desired, opt, &blk) end + # + # Same as Win32::Registry.create (self, subkey, desired, opt) + # def create(subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED, &blk) self.class.create(self, subkey, desired, opt, &blk) end + # + # Close key. + # + # After close, most method raise an error. + # def close API.CloseKey(@hkey) @hkey = @parent = @keyname = nil @@ -627,7 +515,7 @@ end # - # iterator + # Enumerate values. # def each_value index = 0 @@ -649,6 +537,13 @@ end alias each each_value + # + # Enumerate subkeys. + # + # subkey is String which contains name of subkey. + # wtime is last write time as FILETIME (64-bit integer). + # (see Registry.wtime2time) + # def each_key index = 0 while true @@ -663,15 +558,31 @@ index end + # + # return keys as an array + # def keys keys_ary = [] each_key { |key,| keys_ary << key } keys_ary end + # Read a registry value named name and return array of + # [ type, data ]. + # When name is nil, the `default' value is read. + # type is value type. (see Win32::Registry::Constants module) + # data is value data, its class is: + # :REG_SZ, REG_EXPAND_SZ + # String + # :REG_MULTI_SZ + # Array of String + # :REG_DWORD, REG_DWORD_BIG_ENDIAN, REG_QWORD + # Integer + # :REG_BINARY + # String (contains binary data) # - # reader - # + # When rtype is specified, the value type must be included by + # rtype array, or TypeError is raised. def read(name, *rtype) type, data = API.QueryValue(@hkey, name) unless rtype.empty? or rtype.include?(type) @@ -695,6 +606,17 @@ end end + # + # Read a registry value named name and return its value data. + # The class of value is same as #read method returns. + # + # If the value type is REG_EXPAND_SZ, returns value data whose environment + # variables are replaced. + # If the value type is neither REG_SZ, REG_MULTI_SZ, REG_DWORD, + # REG_DWORD_BIG_ENDIAN, nor REG_QWORD, TypeError is raised. + # + # The meaning of rtype is same as #read method. + # def [](name, *rtype) type, data = read(name, *rtype) case type @@ -707,10 +629,20 @@ end end + # Read a REG_SZ(read_s), REG_DWORD(read_i), or REG_BINARY(read_bin) + # registry value named name. + # + # If the values type does not match, TypeError is raised. def read_s(name) read(name, REG_SZ)[1] end + # + # Read a REG_SZ or REG_EXPAND_SZ registry value named name. + # + # If the value type is REG_EXPAND_SZ, environment variables are replaced. + # Unless the value type is REG_SZ or REG_EXPAND_SZ, TypeError is raised. + # def read_s_expand(name) type, data = read(name, REG_SZ, REG_EXPAND_SZ) if type == REG_EXPAND_SZ @@ -720,17 +652,34 @@ end end + # + # Read a REG_SZ(read_s), REG_DWORD(read_i), or REG_BINARY(read_bin) + # registry value named name. + # + # If the values type does not match, TypeError is raised. + # def read_i(name) read(name, REG_DWORD, REG_DWORD_BIG_ENDIAN, REG_QWORD)[1] end + # + # Read a REG_SZ(read_s), REG_DWORD(read_i), or REG_BINARY(read_bin) + # registry value named name. + # + # If the values type does not match, TypeError is raised. + # def read_bin(name) read(name, REG_BINARY)[1] end # - # writer + # Write data to a registry value named name. + # When name is nil, write to the `default' value. # + # type is type value. (see Registry::Constants module) + # Class of data must be same as which #read + # method returns. + # def write(name, type, data) case type when REG_SZ, REG_EXPAND_SZ @@ -751,6 +700,18 @@ API.SetValue(@hkey, name, type, data, data.length) end + # + # Write value to a registry value named name. + # + # If wtype is specified, the value type is it. + # Otherwise, the value type is depend on class of value: + # :Integer + # REG_DWORD + # :String + # REG_SZ + # :Array + # REG_MULTI_SZ + # def []=(name, rtype, value = nil) if value write name, rtype, value @@ -769,26 +730,51 @@ value end + # + # Write value to a registry value named name. + # + # The value type is REG_SZ(write_s), REG_DWORD(write_i), or + # REG_BINARY(write_bin). + # def write_s(name, value) write name, REG_SZ, value.to_s end + # + # Write value to a registry value named name. + # + # The value type is REG_SZ(write_s), REG_DWORD(write_i), or + # REG_BINARY(write_bin). + # def write_i(name, value) write name, REG_DWORD, value.to_i end + # + # Write value to a registry value named name. + # + # The value type is REG_SZ(write_s), REG_DWORD(write_i), or + # REG_BINARY(write_bin). + # def write_bin(name, value) write name, REG_BINARY, value.to_s end # - # delete + # Delete a registry value named name. + # We can not delete the `default' value. # def delete_value(name) API.DeleteValue(@hkey, name) end alias delete delete_value + # + # Delete a subkey named name and all its values. + # + # If recursive is false, the subkey must not have subkeys. + # Otherwise, this method deletes all subkeys and values recursively. + # def delete_key(name, recursive = false) if recursive open(name, KEY_ALL_ACCESS) do |reg| @@ -812,18 +798,38 @@ end # - # flush + # Write all the attributes into the registry file. # def flush API.FlushKey @hkey end # - # key information + # Returns key information as Array of: + # :num_keys + # The number of subkeys. + # :max_key_length + # Maximum length of name of subkeys. + # :num_values + # The number of values. + # :max_value_name_length + # Maximum length of name of values. + # :max_value_length + # Maximum length of value of values. + # :descriptor_length + # Length of security descriptor. + # :wtime + # Last write time as FILETIME(64-bit integer) # + # For detail, see RegQueryInfoKey[http://msdn.microsoft.com/library/en-us/sysinfo/base/regqueryinfokey.asp] Win32 API. + # def info API.QueryInfoKey(@hkey) end + + # + # Returns an item of key information. + # %w[ num_keys max_key_length num_values max_value_name_length max_value_length -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/