numru-misc 0.1.1 → 0.1.2

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1,44 @@
1
+ Fri Mar 14 2014 T Koshiro < M Nakano [dennou-ruby:003646]
2
+ * install.rb: for Ruby 2.x
3
+
4
+ Mon Aug 11 2011 T Horinouchi
5
+ * numru-misc-0.1.1 released (relase tag: numru-misc-0_1_1)
6
+ * LICENCE.txt: Added (BSD 2-clause licence)
7
+
8
+ Mon Mar 15 2010 T Horinouchi
9
+ * numru-misc-0.1.0 released (relase tag: numru-misc-0_1_0)
10
+
11
+ 2008-02-05 S Otsuka
12
+ * install.rb: for ruby 1.9
13
+
14
+ Fri May 13 2005 T Horinouchi
15
+ * numru-misc-0.0.6 released (relase tag: numru-misc-0_0_6)
16
+ * keywordopt.rb: KeywordOpt#keys --> public (returns @keys.dup).
17
+ Added KeywordOpt#select_keys.
18
+ Tue Aug 12 2004 T Horinouchi
19
+ * keywordopt.rb: modified KeywordOptAutoHelp#set to show help
20
+ message if 'help'==true.
21
+ Tue Aug 10 2004 T Horinouchi
22
+ * numru-misc-0.0.5 released (relase tag: numru-misc-0_0_5)
23
+ * package renamed from misc to numru-misc: started new CVS
24
+ Fri Mar 19 2004 T Horinouchi
25
+ * emath.rb: basically, a refactoring
26
+ * install.rb: debug
27
+ Wed Dec 10 2003 T Horinouchi
28
+ * misc-0.0.4 released
29
+ * emath.rb: NumRu::EMath --> NumRu::Misc::EMath
30
+ Documentation.
31
+ * misc.rb: documentation update for EMath.
32
+ Tue Oct 7 2003 T Horinouchi
33
+ * emath.rb: created
34
+ Mon Sep 1 2003 T Horinouchi
35
+ * misc-0.0.3 released
36
+ * keywordopt.rb: minor debug of the help messaging in
37
+ KeywordOptAutoHelp#interpret
38
+ Tue Aug 26 2003 T Horinouchi
39
+ * keywordopt.rb: added class KeywordOptAutoHelp. refined help.
40
+ allowed KeywordOpt.new to accept another KeywordOpt.
41
+ Mon Aug 25 2003 T Horinouchi
42
+ * keywordopt.rb: KeywordOpt#interpret slightly modified
43
+ Mon Aug 25 2003 T Horinouchi
44
+ * version 0.0.2 released
@@ -0,0 +1,6 @@
1
+ *.[oa]
2
+ *~
3
+ *.so
4
+ Makefile
5
+ ChangeLog
6
+ /pkg/
data/ChangeLog CHANGED
@@ -1,41 +1,93 @@
1
+ 2015-03-18 Takeshi Horinouchi (HEAD, numru-misc-0_1_2, origin/master, origin/HEAD, master)
2
+ Years updated.
3
+
4
+ M LICENSE.txt
5
+
6
+ 2015-03-18 Takeshi Horinouchi
7
+ To release version 0.1.2 (git tag numru-misc-0_1_2)
8
+
9
+ M lib/numru/misc/version.rb
10
+
11
+ 2015-03-18 Takeshi Horinouchi
12
+ To require 'numru/misc/version'
13
+
14
+ M lib/numru/misc.rb
15
+
16
+ 2015-03-18 Takeshi Horinouchi
17
+ Created lib/numru/misc/version.rb
18
+
19
+ A lib/numru/misc/version.rb
20
+
21
+ 2015-03-18 Takeshi Horinouchi
22
+ Renamed the current ChangeLog to back up.
23
+
24
+ A .ChangeLog.until201414
25
+ D ChangeLog
26
+
27
+ 2015-03-18 Takeshi Horinouchi
28
+ Registered files (patterns) to ignore in the repository
29
+
30
+ A .gitignore
31
+
32
+ 2014-03-13 koshiro
33
+ Fri Mar 14 2014 T Koshiro < M Nakano [dennou-ruby:003646]
34
+ * install.rb: for Ruby 2.x
35
+
36
+ M ChangeLog
37
+ M install.rb
38
+
39
+ 2011-08-11 T Horinouchi (numru-misc-0_1_1)
1
40
  Mon Aug 11 2011 T Horinouchi
2
41
  * numru-misc-0.1.1 released (relase tag: numru-misc-0_1_1)
3
42
  * LICENCE.txt: Added (BSD 2-clause licence)
4
43
 
44
+ M ChangeLog
45
+ A LICENSE.txt
46
+
47
+ 2010-03-15 T Horinouchi (numru-misc-0_1_0)
5
48
  Mon Mar 15 2010 T Horinouchi
6
49
  * numru-misc-0.1.0 released (relase tag: numru-misc-0_1_0)
7
50
 
8
- 2008-02-05 S Otsuka
9
- * install.rb: for ruby 1.9
51
+ M ChangeLog
52
+
53
+ 2008-02-05 otsuka
54
+ bug fix
55
+
56
+ M install.rb
57
+
58
+ 2008-02-05 otsuka
59
+ change for ruby 1.9
60
+
61
+ M install.rb
10
62
 
63
+ 2005-05-13 T Horinouchi (numru-misc-0_0_6)
11
64
  Fri May 13 2005 T Horinouchi
12
- * numru-misc-0.0.6 released (relase tag: numru-misc-0_0_6)
13
- * keywordopt.rb: KeywordOpt#keys --> public (returns @keys.dup).
65
+ * keywordopt.rb:
14
66
  Added KeywordOpt#select_keys.
15
- Tue Aug 12 2004 T Horinouchi
16
- * keywordopt.rb: modified KeywordOptAutoHelp#set to show help
17
- message if 'help'==true.
18
- Tue Aug 10 2004 T Horinouchi
19
- * numru-misc-0.0.5 released (relase tag: numru-misc-0_0_5)
20
- * package renamed from misc to numru-misc: started new CVS
21
- Fri Mar 19 2004 T Horinouchi
22
- * emath.rb: basically, a refactoring
23
- * install.rb: debug
24
- Wed Dec 10 2003 T Horinouchi
25
- * misc-0.0.4 released
26
- * emath.rb: NumRu::EMath --> NumRu::Misc::EMath
27
- Documentation.
28
- * misc.rb: documentation update for EMath.
29
- Tue Oct 7 2003 T Horinouchi
30
- * emath.rb: created
31
- Mon Sep 1 2003 T Horinouchi
32
- * misc-0.0.3 released
33
- * keywordopt.rb: minor debug of the help messaging in
34
- KeywordOptAutoHelp#interpret
35
- Tue Aug 26 2003 T Horinouchi
36
- * keywordopt.rb: added class KeywordOptAutoHelp. refined help.
37
- allowed KeywordOpt.new to accept another KeywordOpt.
38
- Mon Aug 25 2003 T Horinouchi
39
- * keywordopt.rb: KeywordOpt#interpret slightly modified
40
- Mon Aug 25 2003 T Horinouchi
41
- * version 0.0.2 released
67
+
68
+ M ChangeLog
69
+ M lib/numru/misc/keywordopt.rb
70
+
71
+ 2005-05-13 T Horinouchi
72
+ Fri May 13 2005 T Horinouchi
73
+ * keywordopt.rb: method keys --> public (returns @keys.dup)
74
+
75
+ M ChangeLog
76
+ M lib/numru/misc/keywordopt.rb
77
+
78
+ 2004-08-10 T Horinouchi
79
+ Initial revision
80
+
81
+ A ChangeLog
82
+ A doc/emath.html
83
+ A doc/index.html
84
+ A doc/keywordopt.html
85
+ A doc/md_iterators.html
86
+ A doc/misc.html
87
+ A install.rb
88
+ A lib/numru/misc.rb
89
+ A lib/numru/misc/emath.rb
90
+ A lib/numru/misc/keywordopt.rb
91
+ A lib/numru/misc/md_iterators.rb
92
+ A lib/numru/misc/misc.rb
93
+ A makedoc.csh
data/Gemfile ADDED
@@ -0,0 +1,4 @@
1
+ # A sample Gemfile
2
+ source "https://rubygems.org"
3
+
4
+ gemspec
@@ -1,7 +1,7 @@
1
1
  NumRu::Misc is copyrighted free software by Takeshi Horinouchi and
2
2
  GFD Dennou Club (http://www.gfd-dennou.org/).
3
3
 
4
- Copyright 2011 (C) Takeshi Horinouchi and GFD Dennou Club
4
+ Copyright 2011-2015 (C) Takeshi Horinouchi and GFD Dennou Club
5
5
  (http://www.gfd-dennou.org/) All rights reserved.
6
6
 
7
7
  Redistribution and use in source and binary forms, with or without
data/Rakefile CHANGED
@@ -1,38 +1,35 @@
1
- require 'rake/gempackagetask'
2
-
3
- NAME = 'numru-misc'
4
- VER = '0.1.1'
5
-
6
- PKG_FILES = FileList[
7
- '**',
8
- 'lib/**/*',
9
- 'doc/**/*'
10
- ]
1
+ # -* coding: utf-8 -*-
2
+ #require 'rake/testtask'
3
+ #require 'rake/extensiontask'
4
+ require 'rake/packagetask'
5
+ begin
6
+ require 'bundler/gem_tasks'
7
+ rescue LoadError
8
+ puts 'If you want to create gem, You must install Bundler'
9
+ end
11
10
 
12
- spec = Gem::Specification.new do |s|
13
- s.name = NAME
14
- s.version = VER
15
- s.authors = ["Takeshi Horinouchi"]
16
- s.email = ['eriko@gfd-dennou.org']
17
- s.homepage = 'http://www.gfd-dennou.org/arch/ruby/products/numru-misc/'
18
- s.licenses = ["Takeshi Horinouchi", "GFD Dennou Club"]
19
- s.platform = Gem::Platform::RUBY
20
- s.summary = %q{Collection of miscellaneous functions and classes to facilitate programming.}
21
- s.description = %q{Miscellaneous functions and classes to help Ruby programming. To be used in other NumRu libraries.}
11
+ require './lib/numru/misc.rb'
12
+ def version
13
+ NumRu::Misc::VERSION
14
+ end
22
15
 
23
- s.files = PKG_FILES.to_a
24
- s.require_paths = ['lib']
25
- #s.test_files = Dir.glob("test/*")
26
- #s.has_rdoc = true
27
- s.required_ruby_version = Gem::Requirement.new(">= 1.6")
28
- s.add_runtime_dependency(%q<narray>, [">= 0"])
29
- #s.add_runtime_dependency(%q<narray_miss>, [">= 0"])
30
- #s.extra_rdoc_files = ['README']
16
+ =begin
17
+ task :default => :test
18
+ task :test => :compile
19
+ Rake::TestTask.new do |t|
20
+ t.libs << 'lib' << 'test'
21
+ #t.test_files = FileList['test/test_*.rb'].exclude('test/test_assoccoords.rb')
22
+ #t.test_files = FileList['./demo/rubydcloriginal/*.rb']
23
+ end
31
24
 
32
- #s.extensions << "install.rb"
25
+ Rake::ExtensionTask.new do |ext|
26
+ ext.name = 'dcl_raw'
27
+ ext.ext_dir = 'ext/numru'
28
+ ext.lib_dir = 'lib/numru'
33
29
  end
30
+ =end
34
31
 
35
- Rake::GemPackageTask.new(spec) do |pkg|
36
- pkg.gem_spec = spec
37
- pkg.need_tar = true
32
+ Rake::PackageTask.new('numru-misc', "#{version}") do |t|
33
+ t.need_tar_gz = true
34
+ t.package_files.include `git ls-files`.split("\n")
38
35
  end
data/install.rb CHANGED
@@ -1,8 +1,8 @@
1
1
  require 'rbconfig'
2
2
  require 'find'
3
- include Config
3
+ include RbConfig
4
4
 
5
- if CONFIG["MINOR"].to_i > 6 then $rb_18 = true else $rb_18 = false end
5
+ if CONFIG["MINOR"].to_i > 6 || CONFIG["MAJOR"].to_i >= 2 then $rb_18 = true else $rb_18 = false end
6
6
  if $rb_18
7
7
  require 'fileutils'
8
8
  else
@@ -1,3 +1,4 @@
1
+ require 'numru/misc/version'
1
2
  require 'numru/misc/misc'
2
3
  require 'numru/misc/keywordopt'
3
4
  require 'numru/misc/md_iterators'
@@ -1,30 +1,27 @@
1
- =begin
2
- =module NumRu::Misc::EMath
3
-
4
- To be included instead of the Math predefined module (or NMath in NArray).
5
- Unlike Math and NMath, EMath handles unknown classes by calling its
6
- native instance method (assuming the same name).
7
-
8
- Therefore, if included, its function (module method) is used as:
9
-
10
- cos( obj )
11
-
12
- and so on. If obj is not of a supported class, EMath calls, obj.cos in
13
- this case. (If cos is not a method of obj, then an exception is
14
- raised.) Supported classes are Numeric (by Math) and NArray (by
15
- NMath). EMath stands for "good Math" (for obvious reason for a
16
- Japanese).
17
-
18
- Note: as for atan2(a,b), a.atan2(b) will be called if a or b
19
- is not supported. This is the case for all functions that take
20
- two or more arguments.
21
-
22
- =end
23
-
24
- require "narray"
25
1
 
26
2
  module NumRu
27
3
  module Misc
4
+
5
+ # To be included instead of the Math predefined module (or NMath in NArray).
6
+ # Unlike Math and NMath, EMath handles unknown classes by calling its
7
+ # native instance method (assuming the same name).
8
+ #
9
+ # Therefore, if included, its function (module method) is used as:
10
+ #
11
+ # cos( obj )
12
+ #
13
+ # and so on. If obj is not of a supported class, EMath calls, obj.cos in
14
+ # this case. (If cos is not a method of obj, then an exception is
15
+ # raised.) Supported classes are Numeric (by Math) and NArray (by
16
+ # NMath). EMath stands for "good Math" (for obvious reason for a
17
+ # Japanese).
18
+ #
19
+ # Note: as for atan2(a,b), a.atan2(b) will be called if a or b
20
+ # is not supported. This is the case for all functions that take
21
+ # two or more arguments.
22
+ #
23
+ # require "narray"
24
+ # require "cmath" if RUBY_VERSION.to_f > 1.8
28
25
  module EMath
29
26
 
30
27
  E = Math::E
@@ -41,7 +38,11 @@ module NumRu
41
38
  def #{func}(*arg)
42
39
  case arg[0]
43
40
  when Numeric
41
+ if RUBY_VERSION.to_f > 1.8
42
+ CMath.#{func}(*arg)
43
+ else
44
44
  Math.#{func}(*arg)
45
+ end
45
46
  when NArray
46
47
  NMath.#{func}(*arg)
47
48
  else
@@ -64,6 +65,7 @@ if __FILE__ == $0
64
65
  p cos( PI )
65
66
  p cos( Complex(0, 1) )
66
67
  p cos( NArray[0,PI/3,PI/2] )
68
+ p cos( NArray[ Complex(1,0), Complex(0,1) ] )
67
69
  begin
68
70
  p cos( "ggg" )
69
71
  rescue
@@ -1,205 +1,4 @@
1
- =begin
2
- ==Index
3
- * ((<class NumRu::Misc::KeywordOpt>))
4
- * ((<class NumRu::Misc::KeywordOptAutoHelp < NumRu::Misc::KeywordOpt>))
5
1
 
6
- = class NumRu::Misc::KeywordOpt
7
-
8
- == Overview
9
-
10
- A class to facilitate optional keyword arguments. More specifically,
11
- it helps the use of a Hash to mimic the keyword argument system.
12
- With this, you can set default values and description to each
13
- keyword argument.
14
-
15
- == Classes defined supplementarilly
16
-
17
- === class NumRu::Misc::HelpMessagingException < StandardError
18
-
19
- This is for your convenience. See the usage example below.
20
-
21
- == Usage example
22
-
23
- Suppose that you introduce keyword arguments "flag" and "number"
24
- to the method "hoge" in a class/module Foo. It can be done as
25
- follows:
26
-
27
- require 'numru/misc' # or, specifically, require 'numru/misc/keywordopt'
28
- include NumRu
29
-
30
- class Foo
31
- @@opt_hoge = Misc::KeywordOpt.new(
32
- ['flag', false, 'whether or not ...'],
33
- ['number', 1, 'number of ...'],
34
- ['help', false, 'show help message']
35
- )
36
- def hoge(regular_arg1, regular_arg2, options=nil)
37
- opt = @@opt_hoge.interpret(options)
38
- if opt['help']
39
- puts @@opt_hoge.help
40
- puts ' Current values='+opt.inspect
41
- raise Misc::HelpMessagingException, '** show help message and raise **'
42
- end
43
- # do what you want below
44
- # (options are set in the Hash opt: opt['flag'] and opt['number'])
45
- end
46
- end
47
-
48
- Here, the options are defined in the class variable @@opt_hoge
49
- with option names, default values, and descriptions (for help
50
- messaging). One can use the method hoge as follows:
51
-
52
- foo = Foo.new
53
- ...
54
- x = ...
55
- y = ...
56
- ...
57
- foo.hoge( x, y, {'flag'=>true, 'number'=>10} )
58
-
59
- Or equivalently,
60
-
61
- foo.hoge( x, y, 'flag'=>true, 'number'=>10 )
62
-
63
- because '{}' can be omitted here.
64
-
65
- Tails of options names can be shortened as long as unambiguous:
66
-
67
- foo.hoge( x, y, 'fla'=>true, 'num'=>10 )
68
-
69
-
70
- To show the help message, call
71
-
72
- foo.hoge( x, y, 'help'=>true )
73
-
74
- This will cause the following help message printed with the
75
- exception HelpMessagingException raised.
76
-
77
- << Description of options >>
78
- option name => default value description:
79
- "flag" => false whether or not ...
80
- "number" => 1 number of ...
81
- "help" => false show help message
82
- Current values={"help"=>true, "number"=>1, "flag"=>false}
83
- NumRu::Misc::HelpMessagingException: ** help messaging done **
84
- from (irb):78:in "hoge"
85
- from (irb):83
86
-
87
- Do not affraid to write long descriptions. The help method
88
- breaks lines nicely if they are long.
89
-
90
- == Class methods
91
-
92
- ---KeywordOpt.new( *args )
93
-
94
- Constructor.
95
-
96
- ARGUMENTS
97
- * args : (case 1) arrays of two or three elements: [option name,
98
- default value, description ], or [option name, default value]
99
- if you do not want to write descriptions. Option names and
100
- descriptions must be String. (case 2) another KeywordOpt.
101
- Cases 1 and 2 can be mixed.
102
-
103
- When case 2, a link to the other KeywordOpt is kept. Thus, change
104
- of values in it is reflected to the current one. However,
105
- the link is deleted if values are changed by ((<set>)).
106
-
107
- RETURN VALUE
108
- * a KeywordOpt object
109
-
110
- EXAMPLE
111
- * case 1
112
- opt = Misc::KeywordOpt.new(
113
- ['flag', false, 'whether or not ...'],
114
- ['help', false, 'show help message']
115
- )
116
- * case 2
117
- opt = Misc::KeywordOpt.new( optA, optB )
118
- * case 1 & 2
119
- opt = Misc::KeywordOpt.new(
120
- ['flag', false, 'whether or not ...'],
121
- optA
122
- )
123
-
124
- == Methods
125
- ---interpret(hash)
126
-
127
- Interprets a hash that specifies option values.
128
-
129
- ARGUMENTS
130
- * hash (Hash or nil) : a hash with string keys matching option names
131
- (initializedwhen constructed). The matching is case sensitive and done
132
- such that the tail of a option name can be omitted as long as
133
- unambiguous (for example, 'num' for 'number').
134
- If the argument is nil, the current values are returned.
135
- If there are two options like 'max' and 'maxval', to use
136
- a key 'max' (identical to the former paramer) is allowed, although
137
- it matches 'maxval' as well. (Again 'ma' is regarded ambiguous.)
138
-
139
- RETURN VALUE
140
- * a Hash containing the option values (default values overwritten
141
- with hash).
142
-
143
- POSSIBLE EXCEPTION
144
- * hash has a key that does not match any of the option names.
145
- * hash has a key that is ambiguous
146
-
147
- ---set(hash)
148
-
149
- Similar to ((<interpret>)) but changes internal values.
150
-
151
- ARGUMENTS
152
- * hash (Hash) : see ((<interpret>)). (Here, nil is not permitted though)
153
-
154
- RETURN VALUE
155
- * a Hash containing the values replaced (the ones before calling this
156
- method)
157
-
158
- POSSIBLE EXCEPTION
159
- * the argument is not a Hash
160
- * others are same as in ((<interpret>))
161
-
162
- ---help
163
-
164
- Returns a help message
165
-
166
- RETURN VALUE
167
- * a String describing the option names, default values, and descriptions
168
-
169
- ---[](key)
170
-
171
- Returns a value associated with the key (exact matching unlike interpret)
172
-
173
- ---keys
174
-
175
- Retunrs the keys.
176
-
177
- ---select_existent(hash_or_keys)
178
-
179
- Copies hash_or_keys, exclude ones that are not included in the option
180
- (by comparing keys), and returns it. I.e. select only the ones
181
- exsitent.
182
-
183
- NOTE: ambiguity is not checked, so the resultant value is not
184
- necessarily accepted by ((<interpret>)).
185
-
186
- ARGUMENTS
187
- * hash_or_keys (Hash or Array)
188
-
189
- RETURN VALUE
190
- * a Hash or Array depending on the class of the argument hash_or_keys
191
-
192
- = class NumRu::Misc::KeywordOptAutoHelp < NumRu::Misc::KeywordOpt
193
-
194
- Same as ((<class NumRu::Misc::KeywordOpt>)), but the method ((<interpret>))
195
- shows a help message and raise an exception if option 'help' is provided
196
- as an argument and is not nil or false
197
- ((({NumRu::Misc::HelpMessagingException < StandardError})))
198
- or if the arguments cannot be interpreted correctly ((({ArgumentError}))).
199
- Option 'help' is automatically defined, so you do not have to define it
200
- yourself.
201
-
202
- =end
203
2
 
204
3
  module NumRu
205
4
 
@@ -207,7 +6,119 @@ module NumRu
207
6
  class HelpMessagingException < StandardError
208
7
  end
209
8
 
9
+ # == Overview
10
+ #
11
+ # A class to facilitate optional keyword arguments. More specifically,
12
+ # it helps the use of a Hash to mimic the keyword argument system.
13
+ # With this, you can set default values and description to each
14
+ # keyword argument.
15
+ #
16
+ # == Classes defined supplementarilly
17
+ #
18
+ # === class NumRu::Misc::HelpMessagingException < StandardError
19
+ #
20
+ # This is for your convenience. See the usage example below.
21
+ #
22
+ # == Usage example
23
+ #
24
+ # Suppose that you introduce keyword arguments "flag" and "number"
25
+ # to the method "hoge" in a class/module Foo. It can be done as
26
+ # follows:
27
+ #
28
+ # require 'numru/misc' # or, specifically, require 'numru/misc/keywordopt'
29
+ # include NumRu
30
+ #
31
+ # class Foo
32
+ # @@opt_hoge = Misc::KeywordOpt.new(
33
+ # ['flag', false, 'whether or not ...'],
34
+ # ['number', 1, 'number of ...'],
35
+ # ['help', false, 'show help message']
36
+ # )
37
+ # def hoge(regular_arg1, regular_arg2, options=nil)
38
+ # opt = @@opt_hoge.interpret(options)
39
+ # if opt['help']
40
+ # puts @@opt_hoge.help
41
+ # puts ' Current values='+opt.inspect
42
+ # raise Misc::HelpMessagingException, '** show help message and raise **'
43
+ # end
44
+ # # do what you want below
45
+ # # (options are set in the Hash opt: opt['flag'] and opt['number'])
46
+ # end
47
+ # end
48
+ #
49
+ # Here, the options are defined in the class variable @@opt_hoge
50
+ # with option names, default values, and descriptions (for help
51
+ # messaging). One can use the method hoge as follows:
52
+ #
53
+ # foo = Foo.new
54
+ # ...
55
+ # x = ...
56
+ # y = ...
57
+ # ...
58
+ # foo.hoge( x, y, {'flag'=>true, 'number'=>10} )
59
+ #
60
+ # Or equivalently,
61
+ #
62
+ # foo.hoge( x, y, 'flag'=>true, 'number'=>10 )
63
+ #
64
+ # because '{}' can be omitted here.
65
+ #
66
+ # Tails of options names can be shortened as long as unambiguous:
67
+ #
68
+ # foo.hoge( x, y, 'fla'=>true, 'num'=>10 )
69
+ #
70
+ #
71
+ # To show the help message, call
72
+ #
73
+ # foo.hoge( x, y, 'help'=>true )
74
+ #
75
+ # This will cause the following help message printed with the
76
+ # exception HelpMessagingException raised.
77
+ #
78
+ # << Description of options >>
79
+ # option name => default value description:
80
+ # "flag" => false whether or not ...
81
+ # "number" => 1 number of ...
82
+ # "help" => false show help message
83
+ # Current values={"help"=>true, "number"=>1, "flag"=>false}
84
+ # NumRu::Misc::HelpMessagingException: ** help messaging done **
85
+ # from (irb):78:in "hoge"
86
+ # from (irb):83
87
+ #
88
+ # Do not affraid to write long descriptions. The help method
89
+ # breaks lines nicely if they are long.
90
+ #
210
91
  class KeywordOpt
92
+
93
+ # Constructor.
94
+ #
95
+ # ARGUMENTS
96
+ # * args : (case 1) arrays of two or three elements: [option name,
97
+ # default value, description ], or [option name, default value]
98
+ # if you do not want to write descriptions. Option names and
99
+ # descriptions must be String. (case 2) another KeywordOpt.
100
+ # Cases 1 and 2 can be mixed.
101
+ #
102
+ # When case 2, a link to the other KeywordOpt is kept. Thus, change
103
+ # of values in it is reflected to the current one. However,
104
+ # the link is deleted if values are changed by <b>#set</b>.
105
+ #
106
+ # RETURN VALUE
107
+ # * a KeywordOpt object
108
+ #
109
+ # EXAMPLE
110
+ # * case 1
111
+ # opt = Misc::KeywordOpt.new(
112
+ # ['flag', false, 'whether or not ...'],
113
+ # ['help', false, 'show help message']
114
+ # )
115
+ # * case 2
116
+ # opt = Misc::KeywordOpt.new( optA, optB )
117
+ # * case 1 & 2
118
+ # opt = Misc::KeywordOpt.new(
119
+ # ['flag', false, 'whether or not ...'],
120
+ # optA
121
+ # )
211
122
  def initialize(*args)
212
123
  # USAGE:
213
124
  # KeywordOpt.new([key,val,description],[key,val,description],..)
@@ -252,6 +163,25 @@ module NumRu
252
163
  end
253
164
  end
254
165
 
166
+ # Interprets a hash that specifies option values.
167
+ #
168
+ # ARGUMENTS
169
+ # * hash (Hash or nil) : a hash with string keys matching option names
170
+ # (initializedwhen constructed). The matching is case sensitive and done
171
+ # such that the tail of a option name can be omitted as long as
172
+ # unambiguous (for example, 'num' for 'number').
173
+ # If the argument is nil, the current values are returned.
174
+ # If there are two options like 'max' and 'maxval', to use
175
+ # a key 'max' (identical to the former paramer) is allowed, although
176
+ # it matches 'maxval' as well. (Again 'ma' is regarded ambiguous.)
177
+ #
178
+ # RETURN VALUE
179
+ # * a Hash containing the option values (default values overwritten
180
+ # with hash).
181
+ #
182
+ # POSSIBLE EXCEPTION
183
+ # * hash has a key that does not match any of the option names.
184
+ # * hash has a key that is ambiguous
255
185
  def interpret(hash)
256
186
  return @val.dup if hash.nil?
257
187
  ##
@@ -278,6 +208,18 @@ module NumRu
278
208
  out
279
209
  end
280
210
 
211
+ # Copies hash_or_keys, exclude ones that are not included in the option
212
+ # (by comparing keys), and returns it. I.e. select only the ones
213
+ # exsitent.
214
+ #
215
+ # NOTE: ambiguity is not checked, so the resultant value is not
216
+ # necessarily accepted by <b>#interpret</b>.
217
+ #
218
+ # ARGUMENTS
219
+ # * hash_or_keys (Hash or Array)
220
+ #
221
+ # RETURN VALUE
222
+ # * a Hash or Array depending on the class of the argument hash_or_keys
281
223
  def select_existent(hash_or_keys)
282
224
  hash_or_keys = hash_or_keys.dup # not to alter the original
283
225
  len = @val.length
@@ -298,6 +240,18 @@ module NumRu
298
240
  hash_or_keys
299
241
  end
300
242
 
243
+ # Similar to <b>#interpret</b> but changes internal values.
244
+ #
245
+ # ARGUMENTS
246
+ # * hash (Hash) : see <b>#interpret</b>. (Here, nil is not permitted though)
247
+ #
248
+ # RETURN VALUE
249
+ # * a Hash containing the values replaced (the ones before calling this
250
+ # method)
251
+ #
252
+ # POSSIBLE EXCEPTION
253
+ # * the argument is not a Hash
254
+ # * others are same as in <b>#interpret</b>
301
255
  def set(hash)
302
256
  raise ArgumentError, "not a hash" if !hash.is_a?(Hash)
303
257
  ##
@@ -322,15 +276,6 @@ module NumRu
322
276
  replaced
323
277
  end
324
278
 
325
- # def __line_feed(str)
326
- # if str.length >= 68
327
- # idx = str[0..67].rindex(/\s/)
328
- # if idx
329
- # str[idx, 1] = "\n\t"
330
- # end
331
- # end
332
- # str
333
- # end
334
279
  def __line_feed(str, len)
335
280
  if str.length >= len
336
281
  idx = str[0...len].rindex(/\s/)
@@ -342,6 +287,10 @@ module NumRu
342
287
  end
343
288
  private :__line_feed
344
289
 
290
+ # Returns a help message
291
+ #
292
+ # RETURN VALUE
293
+ # * a String describing the option names, default values, and descriptions
345
294
  def help
346
295
  " option name\tdefault value\t# description:\n" +
347
296
  @keys.collect{|k|
@@ -349,6 +298,7 @@ module NumRu
349
298
  }.join("\n")
350
299
  end
351
300
 
301
+ # Returns a value associated with the key (exact matching unlike interpret)
352
302
  def [](k)
353
303
  v = @val[k]
354
304
  if v.is_a?(KeywordOpt)
@@ -357,17 +307,29 @@ module NumRu
357
307
  v
358
308
  end
359
309
 
310
+ # Returns the keys.
360
311
  def keys
361
312
  @keys.dup
362
313
  end
363
314
 
364
- ##### protected methods #####
315
+ ##### protected method
316
+
365
317
  protected
366
318
  attr_reader :val, :description
367
319
  end
368
320
 
369
321
  ##################################################
370
322
 
323
+ #
324
+ # class NumRu::Misc::KeywordOptAutoHelp < NumRu::Misc::KeywordOpt
325
+ #
326
+ # Same as <b>class NumRu::Misc::KeywordOpt</b>, but the method <b>#interpret</b>
327
+ # shows a help message and raise an exception if option 'help' is provided
328
+ # as an argument and is not nil or false
329
+ # (NumRu::Misc::HelpMessagingException < StandardError
330
+ # or if the arguments cannot be interpreted correctly (ArgumentError).
331
+ # Option 'help' is automatically defined, so you do not have to define it
332
+ # yourself.
371
333
  class KeywordOptAutoHelp < KeywordOpt
372
334
  def initialize(*args)
373
335
  args.push(['help', false, 'show help message if true'])
@@ -404,7 +366,7 @@ end
404
366
  if __FILE__ == $0
405
367
  include NumRu
406
368
 
407
- class Foo
369
+ class Foo # :nodoc:
408
370
  @@opt_hoge = Misc::KeywordOpt.new(
409
371
  ['flag', false, 'whether or not ...'],
410
372
  ['number', 1, 'number of ...'],