dyi 1.1.0 → 1.1.1

data/CHANGES

@@ -1,14 +1,20 @@
 = DYI Changelog
 
-== Version 1.1.0
+== Version 1.1.1 / 2012-02-02
+* Minor Enhancements
+  * Adds a String parsing to CsvReader.
+  * Spports metadata.
+  * Adds `title' and `description' attribute to DYI::Element.
+
+== Version 1.1.0 / 2012-01-06
 * Major Enhancements
-  * Add DYI::Util module
+  * Adds DYI::Util module
   * Can draw a toroid.
-  * Add properties of PieChart.
-  * Support namespace on XML output.
-  * Support Inline-XML mode.
+  * Adds properties of PieChart.
+  * Supports namespace on XML output.
+  * Supports Inline-XML mode.
 
-== Version 1.0.3
+== Version 1.0.3 / 2011-11-27
 * Bug Fixes
   * DataReader is not working properly in Ruby 1.9.
   * A ECMAScript function dose not work properly.
@@ -25,20 +31,20 @@
 == Version 1.0.0 / 2011-09-05
 
 * Major Enhancements
-  * Support events on SVG.
-  * Support animations on SVG.
-  * Support scripts (ex. ECMAScript) on SVG.
-  * Support hyperlinks on SVG.
-  * Support a SVG file that includes style-sheet (ex. CSS, XLST).
-  * Support PNG output. (Needs rsvg-convert)
-  * Support raster image handling (ex. PNG, JPEG) on SVG.
-  * Add Pie-Chart options.
-  * Modify the handling of Reader classes.
+  * Supports events on SVG.
+  * Supports animations on SVG.
+  * Supports scripts (ex. ECMAScript) on SVG.
+  * Supports hyperlinks on SVG.
+  * Supports a SVG file that includes style-sheet (ex. CSS, XLST).
+  * Supports PNG output. (Needs rsvg-convert)
+  * Supports raster image handling (ex. PNG, JPEG) on SVG.
+  * Adds Pie-Chart options.
+  * Modifies the handling of Reader classes.
 
 == Version 0.0.2 / 2011-09-05
 
 * Minor Enhancements
-  * Modify header comments of output file.
+  * Modifies header comments of output file.
 
 * Bug Fixes
   * A path is not drawn correctly.

data/lib/dyi.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,13 @@
 # You should have received a copy of the GNU General Public License
 # along with DYI.  If not, see <http://www.gnu.org/licenses/>.
 
-
+# Root namespace of DYI.
 module DYI
-  VERSION = '1.1.0'
+
+  # DYI program version
+  VERSION = '1.1.1'
+
+  # URL of DYI Project
   URL = 'http://sourceforge.net/projects/dyi/'
 end
 

data/lib/dyi/canvas.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,16 +19,68 @@
 # 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
 
+  # The body of Vector-Image. This class is a container for all graphical
+  # elements that make up the image.
+  # @since 0.0.0
   class Canvas < GraphicalElement
+
+    # @private
     IMPLEMENT_ATTRIBUTES = [:view_box, :preserve_aspect_ratio]
-    attr_length :width, :height
+
+    # Returns width of the vector-image on user unit.
+    # @attribute width
+    # @return [Length] width of vector-image on user unit
+    attr_length :width
+
+    # Returns heigth of the vector-image on user unit.
+    # @attribute height
+    # @return [Length] heigth of vector-image on user unit
+    attr_length :height
+
+    # Returns the value of the view_box.
+    # @attribute view_box
+    # @return [String]
+
+    # Returns the value of the preserve_aspect_ratio.
+    # @attribute preserve_aspect_ratio
+    # @return [String] the value of preserve_aspect_ratio
     attr_reader *IMPLEMENT_ATTRIBUTES
+
+    # Returns an array of child elements.
+    # @return [Array<Element>] an array of child elements
     attr_reader :child_elements
+
+    # Returns hash of event listners.
+    # @return [Hash] hash of event listners
+    # @since 1.0.0
+    attr_reader :event_listeners
+
+    # Returns an array of stylesheets.
+    # @return [Array<Stylesheet::Style>] an array of stylesheets
+    # @since 1.0.0
+    attr_reader :stylesheets
+
+    # Returns an array of scripts.
+    # @return [Array<Script::SimpleScript>] an array of scripts
     # @since 1.0.0
-    attr_reader :event_listeners, :stylesheets, :scripts
+    attr_reader :scripts
+
+    # Returns a metadata object that the image has.
+    # @return [Object] a metadata object that the image has.
+    # @since 1.1.1
+    attr_accessor :metadata
 
+    # @param [Length] width width of the canvas on user unit
+    # @param [Length] height height of the canvas on user unit
+    # @param [Length] real_width width of the image. When this value
+    #   is nil, uses a value that equals value of width parameter.
+    # @param [Length] real_height height of the image. When this value
+    #   is nil, uses a value that equals value of height parameter.
+    # @param [String] preserve_aspect_ratio value that indicates
+    #   whether or not to force uniform scaling
+    # @option options [String] :css_class CSS class of body element
     def initialize(width, height,
                    real_width = nil, real_height = nil,
                    preserve_aspect_ratio='none', options={})
@@ -47,60 +99,93 @@ module DYI #:nodoc:
       self.real_height = real_height
     end
 
+    # Returns width of the image.
+    # @return [Length] width of the image
     def real_width
       @real_width || width
     end
 
+    # Sets width of the image.
+    # @param [Length] width width of the image
     def real_width=(width)
       @real_width = Length.new_or_nil(width)
     end
 
+    # Returns height of the image.
+    # @return [Length] height of the image
     def real_height
       @real_height || height
     end
 
+    # Sets height of the image.
+    # @param [Length] height height of the image
     def real_height=(height)
       @real_height = Length.new_or_nil(height)
     end
 
-    # This method is depricated; use Canvas#root_element?
-    # @deprecated
+    # @deprecated Use {#root_element?} instead.
     def root_node?
       msg = [__FILE__, __LINE__, ' waring']
-      msg << ' DYI::Canvas#root_node? is depricated; use DYI::Canvas#root_element?'
+      msg << ' DYI::Canvas#root_node? is deprecated; use DYI::Canvas#root_element?'
       warn(msg.join(':'))
       true
     end
 
+    # Returns whether this instance is root element of the shape.
+    # @return [Boolean] always true.
     # @since 1.0.0
     def root_element?
       true
     end
 
-    # Returns the canvas where the shape is drawn
-    # @return [Canvas] the canvas where the shape is drawn
+    # Returns the canvas where the shape is drawn.
+    # @return [Canvas] itself
     # @since 1.0.0
     def canvas
       self
     end
 
+    # Writes image on io object.
+    # @param [Formatter::Base] formatter an object that defines the image format
+    # @param [IO] io an io to be written
+    # @since 1.0.0
     def write_as(formatter, io=$>)
       formatter.write_canvas(self, io)
     end
 
+    # Saves as image file.
+    # @param [String] file_name a name of an image file
+    # @param [Symbol] format an image format. When this parameter is nil, saves
+    #   as SVG. This method supports following values: :svg, :eps, :xaml, :png
+    # @option options [Integer] :indent indent of XML output. Defualt to 2
+    # @since 1.0.0
     def save(file_name, format=nil, options={})
       get_formatter(format, options).save(file_name)
     end
 
+    # Puts in io.
+    # @param [Symbol] format an image format. When this parameter is nil, saves
+    #   as SVG. This method supports following values: :svg, :eps, :xaml, :png
+    # @param [IO] io an io to be written
+    # @option options [Integer] :indent indent of XML output. Defualt to 2
+    # @since 1.0.0
     def puts_in_io(format=nil, io=$>, options={})
       get_formatter(format, options).puts(io)
     end
 
+    # Returns data that means the image.
+    # @param [Symbol] format an image format. When this parameter is nil, saves
+    #   as SVG. This method supports following values: :svg, :eps, :xaml, :png
+    # @option options [Integer] :indent indent of XML output. Defualt to 2
+    # @return [String] data that means the image
+    # @since 1.0.0
     def string(format=nil, options={})
       get_formatter(format, options).string
     end
 
-    def attributes #:nodoc:
+    # Returns optional attributes.
+    # @return [Hash] optional attributes
+    def attributes
       IMPLEMENT_ATTRIBUTES.inject({}) do |hash, attribute|
         variable_name = '@' + attribute.to_s.split(/(?=[A-Z])/).map{|str| str.downcase}.join('_')
         value = instance_variable_get(variable_name)
@@ -109,33 +194,33 @@ module DYI #:nodoc:
       end
     end
 
-    # Create a new id for a descendant element
+    # Create a new id for a descendant element.
     # @return [String] new id for a descendant element
     # @since 1.0.0
     def publish_shape_id
       'elm%04d' % (@seed_of_id += 1)
     end
 
+    # Sets event to the image.
+    # @param [Event] event an event that is set to this image
     # @since 1.0.0
     def set_event(event)
       super
       @receive_event = true
     end
 
-    # @return [Boolean] whether event is set to the shape
+    # Returns whether an event is set to the shape.
+    # @return [Boolean] true if an event set to the shape, false otherwise.
     # @since 1.0.0
     def receive_event?
       @receive_event
     end
 
-    # @overload add_script(script)
-    #   Registers a script object with this canvas
-    #   @param [Script::SimpleScript] script a script that is registered
-    # @overload add_script(script_body, content_type='application/ecmascript')
-    #   Registers a script.  Create a script object and Registers it with this
-    #   canvas.
-    #   @param [String] script_body a string that is script body
-    #   @param [String] content_type a content-type of the script
+    # Registers a script with the image.
+    # @param [String, Script::SimpleScript] script_body a string that is a
+    #   script body or a script object that is registered
+    # @param [String] content_type a content-type of the script. If parameter
+    #   `script_body' is {Script::SimpleScript} object, this parameter is ignored
     # @since 1.0.0
     def add_script(script_body, content_type = 'application/ecmascript')
       if script_body.respond_to?(:include_external_file?)
@@ -145,21 +230,33 @@ module DYI #:nodoc:
       end
     end
 
+    # Registers a reference to a script file with the image.
+    # @param [String] reference_path a file path of a script file
+    # @param [String] content_type a content-type of the script
     # @since 1.0.0
     def reference_script_file(reference_path, content_type = 'application/ecmascript')
       @scripts << Script::ScriptReference.new(reference_path, content_type)
     end
 
+    # Registers a stylesheet with the image.
+    # @param [String] style_body a string that is a stylesheet body
+    # @param [String] content_type a content-type of the stylesheet
     # @since 1.0.0
     def add_stylesheet(style_body, content_type = 'text/css')
       @stylesheets << Stylesheet::Style.new(style_body, content_type)
     end
 
+    # Registers a reference to a stylesheet file with the image.
+    # @param [String] reference_path a file path of a stylesheet file
+    # @param [String] content_type a content-type of the stylesheet
     # @since 1.0.0
     def reference_stylesheet_file(reference_path, content_type = 'text/css')
       @stylesheets << Stylesheet::StyleReference.new(reference_path, content_type)
     end
 
+    # Registers a script with the image for initialization.
+    # @param [String] script_body a string that is a script body for
+    #   initialization
     # @since 1.0.0
     def add_initialize_script(script_body)
       if @init_script
@@ -172,7 +269,7 @@ module DYI #:nodoc:
 
     private
 
-    def get_formatter(format=nil, options={}) #:nodoc:
+    def get_formatter(format=nil, options={})
       case format
         when :svg, nil
           options[:indent] = 2 unless options.key?(:indent)

data/lib/dyi/chart/array_reader.rb

@@ -51,7 +51,6 @@ module DYI #:nodoc:
         @records.clear
       end
 
-      # @return [void]
       # @since 1.0.0
       def values_each(&block)
         @records.each do |record|
@@ -73,7 +72,6 @@ module DYI #:nodoc:
         @schema.members.include?(RUBY_VERSION >= '1.9' ? field_name.to_sym : field_name.to_s)
       end
 
-      # @return [void]
       # @since 1.0.0
       def each(&block)
         @records.each(&block)
@@ -83,6 +81,14 @@ module DYI #:nodoc:
         @records = []
       end
 
+      # Loads array-of-array and sets data.
+      # @param [Array<Array>] array_of_array two dimensional array
+      # @option options [Range] :row_range a range of rows
+      # @option options [Range] :column_range a range of columns
+      # @option options [Array<Symbol>] :schema array of field names
+      # @option options [Array<Symbol>] :data_types array of field data types
+      # @option options [Boolean] :transposed whether the array-of-array is
+      #   transposed
       def read(array_of_array, options={})
         clear_data
         row_range = options[:row_range] || (0..-1)
@@ -183,6 +189,10 @@ module DYI #:nodoc:
       end
 
       class << self
+        # Create a new instance of ArrayReader, loading array-of-array.
+        # @param (see #read)
+        # @option (see #read)
+        # @return [ArrayReader] a new instance of ArrayReader
         def read(array_of_array, options={})
           new.read(array_of_array, options)
         end

data/lib/dyi/chart/base.rb

@@ -29,7 +29,6 @@ module DYI #:nodoc:
       # Difines a read property.
       # @param [Symbol] name the property name
       # @param [Hash] settings settings of the property
-      # @return [void]
       def opt_reader(name, settings = {})
         name = name.to_sym
         getter_name = settings[:type] == :boolean ? name.to_s.gsub(/^(.*[^=\?])[=\?]*$/, '\1?') : name
@@ -47,7 +46,6 @@ module DYI #:nodoc:
       # Difines a write property.
       # @param [Symbol] name the property name
       # @param [Hash] settings settings of the property
-      # @return [void]
       def opt_writer(name, settings = {})
         name = name.to_sym
         setter_name = name.to_s.gsub(/^(.*[^=\?])[=\?]*$/, '\1=')
@@ -184,7 +182,6 @@ module DYI #:nodoc:
       # Difines a read-write property.
       # @param [Symbol] name the property name
       # @param [Hash] settings settings of the property
-      # @return [void]
       def opt_accessor(name, settings = {})
         opt_reader(name, settings)
         opt_writer(name, settings)

data/lib/dyi/chart/csv_reader.rb

@@ -24,11 +24,33 @@ require 'date'
 require 'bigdecimal'
 require 'nkf'
 
-module DYI #:nodoc:
-  module Chart #:nodoc:
+module DYI
+  module Chart
 
+    # CsvReader class provides a interface to CSV file and data for a chart
+    # object.
     class CsvReader < ArrayReader
-      def read(path, options={})
+
+      # @private
+      alias __org_read__ read
+
+      # Parses CSV data and sets data.
+      # @param [String] csv CSV data
+      # @option (see ArrayReader#read)
+      # @option options [String] :date_format date format string of CSV data,
+      #   parsing a date string in CSV at +Date#strptime+
+      # @option options [String] :datetime_format date-time format string of CSV
+      #   data, parsing a date-time string in CSV at +DateTime#strptime+
+      # @option options [Symbol] :encode encoding of CSV data as the following:
+      #   +:utf8+ (default), +:sjis+, +:euc+, +:jis+ (ISO-2022-JP), +:utf16+
+      #   (UTF-16BE)
+      # @option options [String] :col_sep a separator of columns, default to
+      #   <tt>","</tt>
+      # @option options [String] :row_sep a separator of rows, default to
+      #   +:auto+ which means that a separetor is <tt>"\r\n"</tt>, <tt>"\n"</tt>,
+      #   or <tt>"\r"</tt> sequence
+      # @since 1.1.1
+      def parse(csv, options={})
         options = options.clone
         @date_format = options.delete(:date_format)
         @datetime_format = options.delete(:datetime_format)
@@ -43,11 +65,18 @@ module DYI #:nodoc:
           end
         parsed_array = 
           if RUBY_VERSION >= '1.9'
-            CSV.parse(nkf_options ? NKF.nkf(nkf_options, IO.read(path)) : IO.read(path), :col_sep => options[:col_sep] || ',', :row_sep => options[:row_sep] || :auto)
+            CSV.parse(nkf_options ? NKF.nkf(nkf_options, csv) : csv, :col_sep => options[:col_sep] || ',', :row_sep => options[:row_sep] || :auto)
           else
-            CSV.parse(nkf_options ? NKF.nkf(nkf_options, IO.read(path)) : IO.read(path), options[:col_sep], options[:row_sep])
+            CSV.parse(nkf_options ? NKF.nkf(nkf_options, csv) : csv, options[:col_sep], options[:row_sep])
           end
-        super(parsed_array, options)
+        __org_read__(parsed_array, options)
+      end
+
+      # Parses CSV file and sets data.
+      # @param [String] path a path of the CSV file
+      # @option (see #parse)
+      def read(path, options={})
+        parse(IO.read(path), options)
       end
 
       private
@@ -80,9 +109,23 @@ module DYI #:nodoc:
       end
 
       class << self
+        # Parses CSV file and creates instance of CsvReader.
+        # @param (see #read)
+        # @option (see #read)
+        # @return [CsvReader] a new instance of CsvReader
+        # @see ArrayReader.read
         def read(path, options={})
           new.read(path, options)
         end
+
+        # Parses CSV data and creates instance of CsvReader.
+        # @param (see #parse)
+        # @option (see #parse)
+        # @return [CsvReader] a new instance of CsvReader
+        # @see ArrayReader.read
+        def parse(path, options={})
+          new.parse(path, options)
+        end
       end
     end
   end