dyi 1.1.1 → 1.1.2

data/lib/dyi/chart/table.rb

@@ -1,6 +1,6 @@
 # -*- encoding: UTF-8 -*-
 
-# Copyright (c) 2009-2011 Sound-F Co., Ltd. All rights reserved.
+# Copyright (c) 2009-2012 Sound-F Co., Ltd. All rights reserved.
 #
 # Author:: Mamoru Yuo
 #
@@ -19,9 +19,11 @@
 # You should have received a copy of the GNU General Public License
 # along with DYI.  If not, see <http://www.gnu.org/licenses/>.
 
-module DYI #:nodoc:
-  module Chart #:nodoc:
+#
+module DYI
+  module Chart
 
+    # @since 0.0.0
     class Table < Base
       attr_reader :frame_canvas, :data_canvas
 
@@ -130,19 +132,19 @@ module DYI #:nodoc:
 =end
       private
 
-      def options #:nodoc:
+      def options
         @options
       end
 
-      def default_csv_format #:nodoc:
+      def default_csv_format
         [0, 1]
       end
 
-      def convert_data(value) #:nodoc:
+      def convert_data(value)
         value.strip
       end
 
-      def create_vector_image #:nodoc:
+      def create_vector_image
         pen = Drawing::Pen.new
         @frame_canvas = Shape::ShapeGroup.draw_on(@canvas)
         @data_canvas = Shape::ShapeGroup.draw_on(@canvas)
@@ -150,7 +152,7 @@ module DYI #:nodoc:
         draw_data(pen)
       end
 
-      def draw_frame(pen) #:nodoc:
+      def draw_frame(pen)
         w = table_width
         h = table_height
 
@@ -166,7 +168,7 @@ module DYI #:nodoc:
         end
       end
 
-      def draw_column_colors #:nodoc:
+      def draw_column_colors
         if column_colors
           brush = Drawing::Brush.new
           h = table_height
@@ -181,7 +183,7 @@ module DYI #:nodoc:
         end
       end
 
-      def draw_data(pen) #:nodoc:
+      def draw_data(pen)
         cell_margin = (row_height - (font && font.draw_size || Font::DEFAULT_SIZE)) / 2
         series.inject(cell_margin) do |x, column_index|
           y = row_height - cell_margin

data/lib/dyi/color.rb

@@ -1,6 +1,6 @@
 # -*- encoding: UTF-8 -*-
 
-# Copyright (c) 2009-2011 Sound-F Co., Ltd. All rights reserved.
+# Copyright (c) 2009-2012 Sound-F Co., Ltd. All rights reserved.
 #
 # Author:: Mamoru Yuo
 #
@@ -19,8 +19,10 @@
 # You should have received a copy of the GNU General Public License
 # along with DYI.  If not, see <http://www.gnu.org/licenses/>.
 
-module DYI #:nodoc:
+#
+module DYI
 
+  # @since 0.0.0
   class Color
     @@named_colors = {'aliceblue'=>[240,248,255],'antiquewhite'=>[250,235,215],'aqua'=>[0,255,255],'aquamarine'=>[127,255,212],'azure'=>[240,255,255],'beige'=>[245,245,220],'bisque'=>[255,228,196],'black'=>[0,0,0],'blanchedalmond'=>[255,235,205],'blue'=>[0,0,255],'blueviolet'=>[138,43,226],'brown'=>[165,42,42],'burlywood'=>[222,184,135],'cadetblue'=>[95,158,160],'chartreuse'=>[127,255,0],'chocolate'=>[210,105,30],'coral'=>[255,127,80],'cornflowerblue'=>[100,149,237],'cornsilk'=>[255,248,220],'crimson'=>[220,20,60],'cyan'=>[0,255,255],'darkblue'=>[0,0,139],'darkcyan'=>[0,139,139],'darkgoldenrod'=>[184,134,11],'darkgray'=>[169,169,169],'darkgreen'=>[0,100,0],'darkgrey'=>[169,169,169],'darkkhaki'=>[189,183,107],'darkmagenta'=>[139,0,139],'darkolivegreen'=>[85,107,47],'darkorange'=>[255,140,0],'darkorchid'=>[153,50,204],'darkred'=>[139,0,0],'darksalmon'=>[233,150,122],'darkseagreen'=>[143,188,143],'darkslateblue'=>[72,61,139],'darkslategray'=>[47,79,79],'darkslategrey'=>[47,79,79],'darkturquoise'=>[0,206,209],'darkviolet'=>[148,0,211],'deeppink'=>[255,20,147],'deepskyblue'=>[0,191,255],'dimgray'=>[105,105,105],'dimgrey'=>[105,105,105],'dodgerblue'=>[30,144,255],'firebrick'=>[178,34,34],'floralwhite'=>[255,250,240],'forestgreen'=>[34,139,34],'fuchsia'=>[255,0,255],'gainsboro'=>[220,220,220],'ghostwhite'=>[248,248,255],'gold'=>[255,215,0],'goldenrod'=>[218,165,32],'gray'=>[128,128,128],'grey'=>[128,128,128],'green'=>[0,128,0],'greenyellow'=>[173,255,47],'honeydew'=>[240,255,240],'hotpink'=>[255,105,180],'indianred'=>[205,92,92],'indigo'=>[75,0,130],'ivory'=>[255,255,240],'khaki'=>[240,230,140],'lavender'=>[230,230,250],'lavenderblush'=>[255,240,245],'lawngreen'=>[124,252,0],'lemonchiffon'=>[255,250,205],'lightblue'=>[173,216,230],'lightcoral'=>[240,128,128],'lightcyan'=>[224,255,255],'lightgoldenrodyellow'=>[250,250,210],'lightgray'=>[211,211,211],'lightgreen'=>[144,238,144],'lightgrey'=>[211,211,211],'lightpink'=>[255,182,193],'lightsalmon'=>[255,160,122],'lightseagreen'=>[32,178,170],'lightskyblue'=>[135,206,250],'lightslategray'=>[119,136,153],'lightslategrey'=>[119,136,153],'lightsteelblue'=>[176,196,222],'lightyellow'=>[255,255,224],'lime'=>[0,255,0],'limegreen'=>[50,205,50],'linen'=>[250,240,230],'magenta'=>[255,0,255],'maroon'=>[128,0,0],'mediumaquamarine'=>[102,205,170],'mediumblue'=>[0,0,205],'mediumorchid'=>[186,85,211],'mediumpurple'=>[147,112,219],'mediumseagreen'=>[60,179,113],'mediumslateblue'=>[123,104,238],'mediumspringgreen'=>[0,250,154],'mediumturquoise'=>[72,209,204],'mediumvioletred'=>[199,21,133],'midnightblue'=>[25,25,112],'mintcream'=>[245,255,250],'mistyrose'=>[255,228,225],'moccasin'=>[255,228,181],'navajowhite'=>[255,222,173],'navy'=>[0,0,128],'oldlace'=>[253,245,230],'olive'=>[128,128,0],'olivedrab'=>[107,142,35],'orange'=>[255,165,0],'orangered'=>[255,69,0],'orchid'=>[218,112,214],'palegoldenrod'=>[238,232,170],'palegreen'=>[152,251,152],'paleturquoise'=>[175,238,238],'palevioletred'=>[219,112,147],'papayawhip'=>[255,239,213],'peachpuff'=>[255,218,185],'peru'=>[205,133,63],'pink'=>[255,192,203],'plum'=>[221,160,221],'powderblue'=>[176,224,230],'purple'=>[128,0,128],'red'=>[255,0,0],'rosybrown'=>[188,143,143],'royalblue'=>[65,105,225],'saddlebrown'=>[139,69,19],'salmon'=>[250,128,114],'sandybrown'=>[244,164,96],'seagreen'=>[46,139,87],'seashell'=>[255,245,238],'sienna'=>[160,82,45],'silver'=>[192,192,192],'skyblue'=>[135,206,235],'slateblue'=>[106,90,205],'slategray'=>[112,128,144],'slategrey'=>[112,128,144],'snow'=>[255,250,250],'springgreen'=>[0,255,127],'steelblue'=>[70,130,180],'tan'=>[210,180,140],'teal'=>[0,128,128],'thistle'=>[216,191,216],'tomato'=>[255,99,71],'turquoise'=>[64,224,208],'violet'=>[238,130,238],'wheat'=>[245,222,179],'white'=>[255,255,255],'whitesmoke'=>[245,245,245],'yellow'=>[255,255,0],'yellowgreen'=>[154,205,50]}
     @@default_format = ['#%02X%02X%02X', false]
@@ -87,7 +89,7 @@ module DYI #:nodoc:
       self == other
     end
 
-    def hash #:nodoc:
+    def hash
       (@r << 16) + (@g << 8) + @b 
     end
 
@@ -149,7 +151,7 @@ module DYI #:nodoc:
 
       public
 
-      def new(*args) #:nodoc:
+      def new(*args)
         if args.size == 1
           case args.first
           when self
@@ -167,7 +169,7 @@ module DYI #:nodoc:
         (args.size == 1 && args.first.nil?) ? nil : new(*args)
       end
 
-      def method_missing(name, *args) #:nodoc:
+      def method_missing(name, *args)
         if args.size == 0 && color = named_color(name)
           instance_eval %{
             def self.#{name}
@@ -192,7 +194,7 @@ module DYI #:nodoc:
         @@default_format
       end
 
-      def check_format(fmt) #:nodoc:
+      def check_format(fmt)
         begin
           (fmt = fmt.to_s) % [0.0, 0.0, 0.0]
           fmt
@@ -203,7 +205,7 @@ module DYI #:nodoc:
 
       private
 
-      def named_color(name) #:nodoc:
+      def named_color(name)
         name = name.to_s.downcase
         color = instance_variable_get('@' + name) rescue (return nil)
         return color if color

data/lib/dyi/coordinate.rb

@@ -1,9 +1,8 @@
 # -*- encoding: UTF-8 -*-
 
-# Copyright (c) 2009-2011 Sound-F Co., Ltd. All rights reserved.
+# Copyright (c) 2009-2012 Sound-F Co., Ltd. All rights reserved.
 #
 # Author:: Mamoru Yuo
-# Documentation:: Mamoru Yuo
 #
 # This file is part of DYI.
 #
@@ -19,52 +18,51 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with DYI.  If not, see <http://www.gnu.org/licenses/>.
-#
-# == Overview
-#
-# This file provides the DYI::Coordinate class, which provides
-# coordinate supports for DYI scripts.  The coordinate represents a
-# length in the user coordinate system that is the given distance from the
-# origin of the user coordinate system along the relevant axis (the x-axis for
-# X coordinates, the y-axis for Y coordinates).
-#
-# See the documentation to the DYI::Coordinate class for more details
-# and examples of usage.
-#
 
-module DYI #:nodoc:
+#
+module DYI
 
-  # Class representing a coordinate.  See documentation for the file
-  # dyi/coordinate.rb for an overview.
-  #
-  # == Introduction
-  #
-  # This class works with two length that mean orthogonal coordinates.  The
-  # initial coordinate system has the origin at the top/left with the x-axis
-  # pointing to the right and the y-axis pointing down.
+  # Class representing a coordinate. This class works with two length that mean
+  # orthogonal coordinates. The initial coordinate system has the origin at the
+  # top/left with the x-axis pointing to the right and the y-axis pointing down.
   #
-  # The equality operator '<tt>==</tt>' does not test equality instance but test
+  # The equality operator '{#== ==}' does not test equality instance but test
   # equality value of x-coordinate and y-coordinate.
   #
-  # == Ways of calculating
+  # == Ways of Calculating
   #
-  # This class suports following arithmetic operators and methods: <tt>+</tt>,
-  # <tt>-</tt>, <tt>*</tt>, <tt>/</tt>, <tt>**</tt>, +#quo+.  The operators
-  # '<tt>+</tt>', '<tt>-</tt>' coerced right hand operand into Coordinate, and
-  # then calculate.
+  # This class suports following arithmetic operators and methods: {#+ +},
+  # {#- -}, {#* *}, {#/ /}, {#** **}, {#quo}. The operators '{#+ +}', '{#- -}'
+  # coerces a right hand operand into Coordinate, and then calculates.
   #
-  # See the documentation to each operators and methods class for details.
+  # @since 0.0.0
   class Coordinate
-    @@default_format = '(x,y)'
 
-    attr_reader :x, :y
+    # @private
+    @@default_format = '(x,y)'
 
-    # :call-seq:
-    # new (x_length, y_length)
-    # new (x_number, y_number)
-    # new (array)
-    # new (coordinate)
-    #
+    # Returns an x-coordinate
+    # @return [Length] an x-coordinate
+    attr_reader :x
+
+    # Returns a y-coordinate
+    # @return [Length] a y-coordinate
+    attr_reader :y
+
+    # @overload initialize(coordinate)
+    #   Returns the argument itself.
+    #   @param [Coordinate] coordinate the source coordinate
+    # @overload initialize(array)
+    #   Return a new instance of Coordinate. First element of _array_ is used
+    #   for x-coordinate, second element of _array_ is used y-coordinate.
+    #   @param [Array<Length, Number, String>] array an array converted into
+    #     Coordinate
+    #   @raise [ArgumentError] size of _array_ does not equal to 2
+    # @overload initialize(x, y)
+    #   @param [Length, Number, String] x an x-cooridnate
+    #   @param [Length, Number, String] y a y-cooridnate
+    # @raise [TypeError] the argument can not be coerced into +Coordinate+
+    # @see .new
     def initialize(*args)
       case args.size
       when 1
@@ -87,70 +85,123 @@ module DYI #:nodoc:
       end
     end
 
+    # The origin point.
     ZERO = new(0,0)
 
+    # Unary Plus -- Returns the receiver's value.
+    # @return [Length] receiver itself
     def +@
       self
     end
 
+    # Unary Minus -- Returns a coordinate whose x-coordinate and y-coordinate
+    # negated.
+    # @return [Length] the negated receiver's value
     def -@
       self.class.new(-@x, -@y)
     end
 
+    # Returns a new coordinate which is the sum of the receiver and _other_.
+    # First, _other_ is converted into +Coordinate+.
+    # @param [Coordinate, Array<Length, Number, String>] other the value that
+    #   can be converted into +Coordinate+
+    # @return [Length] a new length which is the sum of the receiver and _other_
     def +(other)
       other = self.class.new(other)
       self.class.new(@x + other.x, @y + other.y)
     end
 
+    # Returns a new length which is the difference of the receiver and _other_.
+    # First _other_ is converted into +Coordinate+.
+    # @param [Length, Numeric, String] other the value that can be converted
+    #   into +Coordinate+
+    # @return [Length] a new length which is the difference of the receiver and
+    #   _other_
     def -(other)
       other = self.class.new(other)
       self.class.new(@x - other.x, @y - other.y)
     end
 
+    # Returns a new muliplicative coordinate of the receiver by _number_.
+    # @param [Numeric] number the operand value
+    # @return [Length] a new muliplicative length
     def *(number)
       self.class.new(@x * number, @y * number)
     end
 
+    # Raises a coordinate the _number_ power.
+    # @param [Numeric] number the operand value
+    # @return [Length] a coordinate the _number_ power
     def **(number)
       self.class.new(@x ** number, @y ** number)
     end
 
-    def quo(number)
+    # Returns a new divisional length of the receiver by _number_.
+    # @param [Numeric] other the operand value
+    # @return [Length] a new divisional length
+    # @raise [TypeError] _other_ can't be coerced into Numeric
+    def /(number)
       raise TypeError, "#{number.class} can't be coerced into Numeric" unless number.kind_of?(Numeric)
       self.class.new(@x.quo(number.to_f), @y.quo(number.to_f))
     end
 
-    alias / quo
+    alias quo /
 
+    # Returns whether the receiver is the origin point.
+    # @return [Boolean] true if the receiver is the origin point, false
+    #   otherwise
     def zero?
       @x.zero? && @y.zero?
     end
 
+    # Returns whether the receiver is not the origin point.
+    # @return [Coordinate, nil] self if the receiver is not the origin point,
+    #   nil otherwise
     def nonzero?
       zero? ? nil : self
     end
 
+    # Returns whether the receiver equals to _other_.
+    # @param [Object] other an object
+    # @return [Boolean] true if _other_ is an instance of +Coordinate+ and
+    #   each coordinate of receiver equals to a coordinate of _other_, false
+    #   otherwise
     def ==(other)
       return false unless other.kind_of?(self.class)
       @x == other.x && @y == other.y
     end
 
+    # Returns a distance between receiver and the origin point.
+    # @return [Length] a distance between receiver and the origin point
     def abs
       (@x ** 2 + @y ** 2) ** 0.5
     end
 
+    # Returns a distance between receiver and _origin_.
+    # @return [Length] a distance between receiver and _origin_
     def distance(other)
       (self - other).abs
     end
 
+    # Returns a coordinate that converted into the user unit.
+    # @return [Coordinate] a coordinate that converted into the user unit
     def to_user_unit
       self.class.new(@x.to_user_unit, @y.to_user_unit)
     end
 
-    # :call-seq:
-    # to_s ()
-    # to_s (format)
-    # 
+    # Returns a string to represent the receiver.
+    #
+    # Format string can be specified for the argument. If no argument is given,
+    # {.default_format} is used as format string. About format string, see the
+    # documentation of {.default_format} method.
+    # @param [String] format a format string
+    # @return [Length] a string to represent the receiver
+    # @example
+    #   point = DYI::Coordinate.new(10, 20)
+    #   point.to_s('<x, y>')         # => "<10, 20>"
+    #   point.to_s('\\x:x, \\y:y')   # => "x:10, y:20"
+    # @see .default_format=
+    # @see .set_default_format
     def to_s(format=nil)
       fmts = (format || @@default_format).split('\\\\')
       fmts = fmts.map do |fmt|
@@ -159,7 +210,8 @@ module DYI #:nodoc:
       fmts.join('\\')
     end
 
-    def inspect #:nodoc:
+    # @private
+    def inspect
       "(#{@x.inspect}, #{@y.inspect})"
     end
 
@@ -167,26 +219,84 @@ module DYI #:nodoc:
 
       public
 
-      def new(*args) #:nodoc:
+      # Creates and returns a new instance of Coordinate provided the argument
+      # is not an instace of Coordinate. If the argument is an instace of
+      # Coordinate, returns the argument itself.
+      # @overload new(coordinate)
+      #   Returns the argument itself.
+      #   @param [Coordinate] coordinate the source coordinate
+      # @overload new(array)
+      #   Return a new instance of Coordinate. First element of _array_ is used
+      #   for x-coordinate, second element of _array_ is used y-coordinate.
+      #   @param [Array<Length, Number, String>] array an array converted into
+      #     Coordinate
+      #   @raise [ArgumentError] size of _array_ does not equal to 2
+      # @overload new(x, y)
+      #   @param [Length, Number, String] x an x-cooridnate
+      #   @param [Length, Number, String] y a y-cooridnate
+      # @raise (see #initialize)
+      # @example
+      #   x = DYI::Length(10)
+      #   y = DYI::Length(20)
+      #   point1 = DYI::Coordinate.new(x, y)              # this point is (10, 20)
+      #   point2 = DYI::Coordinate.new(10, 20)            # it is (10, 20) too
+      #   point3 = DYI::Coordinate.new([x, y])            # it is (10, 20) too
+      #   point4 = DYI::Coordinate.new([10, 20])          # it is (10, 20) too
+      #   point5 = DYI::Coordinate.new(['10px', '20px'])  # it is (10, 20) too
+      def new(*args)
         return args.first if args.size == 1 && args.first.instance_of?(self)
         super
       end
 
-
-      # Creats and Returns new instance as +new+ method when an argument is not
-      # +nil+.  If an argument is +nil+, returns +nil+.
+      # Returns a new instace of Coordinate if the argments is not +nil+ (calls
+      # +Coordinate.new+ method), but returns +nil+ if the argument is +nil+.
+      # @return [Coordinate, nil] a new instace of Length if the argments is not
+      #   nil, nil otherwise
+      # @see .new
       def new_or_nil(*args)
         (args.size == 1 && args.first.nil?) ? nil : new(*args)
       end
 
+      # Creates a new instance of Coordinate using the cartesian coordinates,
+      # and returns it.
+      # @param [Length, Number, String] x an x-cooridnate
+      # @param [Length, Number, String] y a y-cooridnate
       def orthogonal_coordinates(x, y)
         new(x, y)
       end
 
+      # Creates a new instance of Coordinate using the polar coordinates,
+      # and returns it.
+      # @param [Length, Number, String] radius distance from the origin point
+      # @param [Numeric] theta the angle from x-direction in degrees
       def polar_coordinates(radius, theta)
         new(radius * DYI::Util.cos(theta), radius * DYI::Util.sin(theta))
       end
 
+      # Invokes block with given format string as default format.
+      # @overload set_default_format(format)
+      #   Invokes block with given _format_ as default format. After invokes the
+      #   block, the original format is used. 
+      #   @param [String] format a format string
+      #   @yield a block which the format string is used in
+      #   @return [Length] the receiver itself
+      # @overload set_default_format(format)
+      #   Sets default format setring as {.default_format=} method.
+      #   @param [String] format a format string
+      #   @return [String] the given argument
+      # @example
+      #   # an initial format string is "(x,y)"
+      #   point = DYI::Coordinate.new(10, 20)
+      #   point.to_s                            # => "(10,20)"
+      #   DYI::Coordinate.set_default_format('<x, y>') {
+      #     point.to_s                          # => "<10, 20>"
+      #     DYI::Length.set_default_format('0.0u') {
+      #       point.to_s                        # => "<10.0pt, 20.0pt>"
+      #     }
+      #   }
+      #   point.to_s                            # => "(10,20)"
+      # @see Length.set_default_format
+      # @see .default_format=
       def set_default_format(format)
         if block_given?
           org_format = default_format
@@ -199,23 +309,29 @@ module DYI #:nodoc:
         end
       end
 
+      # Returns a format that is used when called {#to_s} without an argument.
+      # @return [String] a format string
+      # @see .default_format=
       def default_format
         @@default_format
       end
 
-      # Sets format that is used when called to_s.
-      #
-      # The following format indicators can be used for the format specification
-      # character string.
+      # Sets a format string that is used when called {#to_s} without an
+      # argument. The format string that is set at this method is used
+      # permanently. Use {.set_default_format} with a block when you want to use
+      # a format string temporarily.
       #
-      # +x+:: (x-coordinate placeholder) Placeholder '+x+' is replaced as
-      #       x-coordinate.
-      # +y+:: (y-coordinate placeholder) Placeholder '+y+' is replaced as
-      #       y-coordinate.
-      # <tt>\\\\<tt>:: (escape character) Causes the next character to be interpreted
-      #                as a literal rather than as a custom format specifier.
-      # all other characters:: The character is copied to the result string
-      #                        unchanged.
+      # Uses the following characters as coordinate format strings.
+      # [<tt>"x"</tt> (x-coordinate placeholder)] Placeholder '+x+' is replaced
+      #                                           as x-coordinate.
+      # [<tt>"y"</tt> (y-coordinate placeholder)] Placeholder '+y+' is replaced
+      #                                           as y-coordinate.
+      # [<tt>"\\"</tt> (Escape Character)] Causes the next character to be
+      #                                    interpreted as a literal.
+      # @see #to_s
+      # @see .set_default_format
+      # @see Length.default_format=
+      # @see Numeric#strfnum
       def default_format=(fromat)
         @@default_format = fromat.clone
       end