gnuplotrb 0.3.0 → 0.3.1

data/lib/gnuplotrb/mixins/error_handling.rb

@@ -9,10 +9,9 @@ module GnuplotRB
   # handle errors from its stderr.
   module ErrorHandling
     ##
-    # ====== Overview
     # Check if there were errors in previous commands.
     # Throws GnuplotError in case of any errors.
-    def check_errors
+    def check_errors(raw: false)
       return if @err_array.empty?
       command = ''
       rest = ''
@@ -21,14 +20,17 @@ module GnuplotRB
         rest = @err_array[1..-1].join('; ')
         @err_array.clear
       end
-      message = "Error in previous command (\"#{command}\"): \"#{rest}\""
+      message = if raw
+        "#{command};#{rest}}"
+      else
+        "Error in previous command (\"#{command}\"): \"#{rest}\""
+      end
       fail GnuplotError, message
     end
 
     private
 
     ##
-    # ====== Overview
     # Start new thread that will read stderr given as stream
     # and add errors into @err_array.
     def handle_stderr(stream)

data/lib/gnuplotrb/mixins/option_handling.rb

@@ -1,13 +1,12 @@
 module GnuplotRB
   ##
-  # ====== Overview
   # This module contains methods which are mixed into several classes
   # to set, get and convert their options.
   module OptionHandling
     class << self
-      # Some values of options should be quoted to be read by gnuplot
+      # Some values of options should be quoted to be read by gnuplot properly
       #
-      # TODO: update list with data from gnuplot documentation !!!
+      # @todo update list with data from gnuplot documentation !!!
       QUOTED_OPTIONS = %w(
         title
         output
@@ -30,26 +29,33 @@ module GnuplotRB
         format_z
         format_cb
         timefmt
+        dt
+        dashtype
       )
 
+      private_constant :QUOTED_OPTIONS
+
       ##
-      # Replacement '_' with ' ' is made to allow passing several options
-      # with the same first word of key.
-      # See issue #7 for more info.
+      # Replace '_' with ' ' is made to allow passing several options
+      # with the same first word of key. See issue #7 for more info.
+      # @param key [Symbol, String] key to modify
+      # @return [String] given key with '_' replaced with ' '
       def string_key(key)
         key.to_s.gsub(/_/) { ' ' } + ' '
       end
 
       ##
-      # ====== Overview
       # Recursive function that converts Ruby option to gnuplot string
-      # ====== Arguments
-      # * *key* - name of option in gnuplot
-      # * *option* - an option that should be converted
-      # ====== Examples
-      #   option_to_string(['png', size: [300, 300]]) #=> 'png size 300,300'
-      #   option_to_string(xrange: 0..100) #=> 'xrange [0:100]'
-      #   option_to_string(multiplot: true) #=> 'multiplot'
+      #
+      # @param key [Symbol] name of option in gnuplot
+      # @param option an option that should be converted
+      # @example
+      #   option_to_string(['png', size: [300, 300]])
+      #   #=> 'png size 300,300'
+      #   option_to_string(xrange: 0..100)
+      #   #=> 'xrange [0:100]'
+      #   option_to_string(multiplot: true)
+      #   #=> 'multiplot'
       def option_to_string(key = nil, option)
         return string_key(key) if !!option == option # check for boolean
         value = ruby_class_to_gnuplot(option)
@@ -60,6 +66,7 @@ module GnuplotRB
       end
 
       ##
+      # @private
       # Method for inner use.
       # Needed to convert several ruby classes into
       # value that should be piped to gnuplot.
@@ -79,35 +86,33 @@ module GnuplotRB
       end
 
       ##
-      # ====== Overview
       # Check if given terminal available for use.
-      # ====== Arguments
-      # * *terminal* - terminal to check (e.g. 'png', 'qt', 'gif')
+      #
+      # @param terminal [String] terminal to check (e.g. 'png', 'qt', 'gif')
+      # @return [Boolean] true or false
       def valid_terminal?(terminal)
         Settings.available_terminals.include?(terminal)
       end
 
       ##
-      # ====== Overview
       # Check if given options are valid for gnuplot.
       # Raises ArgumentError if invalid options found.
-      # ====== Arguments
-      # * *options* - Hash of options to check
-      #   (e.g. {term: 'qt', title: 'Plot title'})
-      #
       # Now checks only terminal name.
+      #
+      # @param options [Hash] options to check (e.g. "{ term: 'qt', title: 'Plot title' }")
       def validate_terminal_options(options)
         terminal = options[:term]
         return unless terminal
         terminal = terminal[0] if terminal.is_a?(Array)
         message = 'Seems like your Gnuplot does not ' \
-                  'support that terminal, please see supported ' \
-                  'terminals with Settings::available_terminals'
+                  "support that terminal (#{terminal}), please see " \
+                  'supported terminals with Settings::available_terminals'
         fail(ArgumentError, message) unless valid_terminal?(terminal)
       end
     end
 
     ##
+    # @private
     # You should implement #initialize in classes that use OptionsHelper
     def initialize(*_)
       fail NotImplementedError, 'You should implement #initialize' \
@@ -115,6 +120,7 @@ module GnuplotRB
     end
 
     ##
+    # @private
     # You should implement #new_with_options in classes that use OptionsHelper
     def new_with_options(*_)
       fail NotImplementedError, 'You should implement #new_with_options' \
@@ -122,20 +128,19 @@ module GnuplotRB
     end
 
     ##
-    # ====== Overview
     # Create new Plot (or Dataset or Splot or Multiplot) object where current
     # options are merged with given. If no options
     # given it will just return existing set of options.
-    # ====== Arguments
-    # * *options* - options to add. If no options given, current
-    #   options are returned.
-    # ====== Example
+    #
+    # @param options [Hash] options to add
+    # @return [Dataset, Splot, Multiplot] new object created with given options
+    # @return [Hamster::Hash] current options if given options empty
+    # @example
     #   sin_graph = Plot.new(['sin(x)', title: 'Sin'], title: 'Sin on [0:3]', xrange: 0..3)
     #   sin_graph.plot
     #   sin_graph_update = sin_graph.options(title: 'Sin on [-10:10]', xrange: -10..10)
     #   sin_graph_update.plot
-    #   # this may also be considered as
-    #   # sin_graph.title(...).xrange(...)
+    #   # sin_graph IS NOT affected
     def options(**options)
       @options ||= Hamster::Hash.new
       if options.empty?
@@ -145,12 +150,27 @@ module GnuplotRB
       end
     end
 
+    ##
+    # Update existing Plot (or Dataset or Splot or Multiplot) object with given options.
+    #
+    # @param options [Hash] options to add
+    # @return [Dataset, Splot, Multiplot] self
+    # @example
+    #   sin_graph = Plot.new(['sin(x)', title: 'Sin'], title: 'Sin on [0:3]', xrange: 0..3)
+    #   sin_graph.plot
+    #   sin_graph.options!(title: 'Sin on [-10:10]', xrange: -10..10)
+    #   sin_graph.plot
+    #   # second #plot call will plot not the same as first, sin_graph IS affected
+    def options!(**options)
+      @options = @options ? @options.merge(options) : Hamster::Hash.new(options)
+      self
+    end
+
     private
 
     ##
-    # ====== Arguments
-    # * *key* - [Symbol] - option key
-    # * *value* - anything treated as options value in gnuplot gem
+    # Return current option value if no value given. Create new
+    # object with given option set if value given.
     def option(key, *value)
       if value.empty?
         value = options[key]
@@ -160,5 +180,11 @@ module GnuplotRB
         options(key => value)
       end
     end
+
+    ##
+    # Just set an option.
+    def option!(key, *value)
+      options!(key => value)
+    end
   end
 end

data/lib/gnuplotrb/mixins/plottable.rb

@@ -7,57 +7,64 @@ module GnuplotRB
     include OptionHandling
 
     ##
+    # @private
     # You should implement #plot in classes that are Plottable
     def plot(*_)
       fail NotImplementedError, 'You should implement #plot in classes that are Plottable!'
     end
 
     ##
-    # ====== Overview
     # In this gem #method_missing is used both to handle
     # options and to handle plotting to specific terminal.
     #
-    # ====== Options handling
-    # ======= Overview
+    # == Options handling
+    # === Overview
     # You may set options using #option_name(option_value) method.
     # A new object will be constructed with selected option set.
     # And finally you can get current value of any option using
     # #options_name without arguments.
-    # ======= Arguments
+    # === Arguments
     # * *option_value* - value to set an option. If none given
     #   method will just return current option's value
-    # ======= Examples
+    # === Examples
     #   plot = Splot.new
     #   new_plot = plot.title('Awesome plot')
     #   plot.title #=> nil
     #   new_plot.title #=> 'Awesome plot'
     #
-    # ====== Plotting to specific term
-    # ======= Overview
+    # == Plotting to specific term
+    # === Overview
     # Gnuplot offers possibility to output graphics to many image formats.
     # The easiest way to to so is to use #to_<plot_name> methods.
-    # ======= Arguments
+    # === Arguments
     # * *options* - set of options related to terminal (size, font etc).
     #   Be careful, some terminals have their own specific options.
-    # ======= Examples
+    # === Examples
     #   # font options specific for png term
     #   multiplot.to_png('./result.png', size: [300, 500], font: ['arial', 12])
     #   # font options specific for svg term
     #   content = multiplot.to_svg(size: [100, 100], fname: 'Arial', fsize: 12)
     def method_missing(meth_id, *args)
       meth = meth_id.id2name
-      if meth[0..2] == 'to_'
+      case
+      when meth[0..2] == 'to_'
         term = meth[3..-1]
         super unless OptionHandling.valid_terminal?(term)
         to_specific_term(term, *args)
+      when meth[-1] == '!'
+        option!(meth[0..-2].to_sym, *args)
+      when meth[-1] == '='
+        option!(meth[0..-2].to_sym, *args)
+        option(meth[0..-2].to_sym)
       else
         option(meth_id, *args)
       end
     end
 
     ##
-    # Returns true foe existing methods and
-    # #to_<term_name> when name is a valid terminal type.
+    # @return [true] for existing methods and
+    #   #to_|term_name| when name is a valid terminal type.
+    # @return [false] otherwise
     def respond_to?(meth_id)
       # Next line is here to force iRuby use #to_iruby
       # instead of #to_svg.
@@ -68,8 +75,7 @@ module GnuplotRB
     end
 
     ##
-    # This method is used to embed plottable objects
-    # into iRuby notebooks. There is
+    # This method is used to embed plottable objects into iRuby notebooks. There is
     # {a notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/basic_usage.ipynb]
     # with examples of its usage.
     def to_iruby
@@ -86,20 +92,16 @@ module GnuplotRB
     end
 
     ##
-    # :call-seq:
-    # to_png('file.png') -> creates file with plot
-    # to_svg -> svg file contents
-    # to_canvas('plot.html', size: [300,300]) -> creates file with plot
-    #
-    # ====== Overview
-    # Method which outputs plot to specific terminal (possibly some file).
+    # @private
+    # Output plot to specific terminal (possibly some file).
     # Explicit use should be avoided. This method is called from #method_missing
     # when it handles method names like #to_png(options).
-    # ====== Arguments
-    # * *path* - path to output file, if none given it will output to temp file
+    #
+    # @param trminal [String] terminal name ('png', 'svg' etc)
+    # @param path [String] path to output file, if none given it will output to temp file
     #   and then read it and return binary contents of file
-    # * *options* - used in #plot
-    # ====== Examples
+    # @param options [Hash] used in #plot
+    # @example
     #   ## plot here may be Plot, Splot, Multiplot or any other plottable class
     #   plot.to_png('./result.png', size: [300, 500])
     #   contents = plot.to_svg(size: [100, 100])
@@ -117,9 +119,90 @@ module GnuplotRB
     end
 
     ##
-    # Returns terminal object linked with this Plottable object.
+    # @return [Terminal] terminal object linked with this Plottable object
     def own_terminal
       @terminal ||= Terminal.new
     end
+
+    ##
+    # @!method xrange(value = nil)
+    # @!method yrange(value = nil)
+    # @!method title(value = nil)
+    # @!method option_name(value = nil)
+    # Clone existing object and set new options value in created one or just return
+    # existing value if nil given.
+    #
+    # Method is handled by #method_missing.
+    #
+    # You may set options using #option_name(option_value) method.
+    # A new object will be constructed with selected option set.
+    # And finally you can get current value of any option using
+    # #options_name without arguments.
+    # 
+    # Available options are listed in Plot, Splot, Multiplot etc class top level doc.
+    #
+    # @param value new value for option
+    # @return new object with option_name set to *value* if value given
+    # @return old option value if no value given
+    #
+    # @example
+    #   plot = Splot.new
+    #   new_plot = plot.title('Awesome plot')
+    #   plot.title #=> nil
+    #   new_plot.title #=> 'Awesome plot'
+
+    ##
+    # @!method xrange!(value)
+    # @!method yrange!(value)
+    # @!method title!(value)
+    # @!method option_name!(value)
+    # Set value for an option.
+    #
+    # Method is handled by #method_missing.
+    #
+    # You may set options using obj.option_name!(option_value) or 
+    # obj.option_name = option_value methods.
+    # 
+    # Available options are listed in Plot, Splot, Multiplot etc class top level doc.
+    #
+    # @param value new value for option
+    # @return self
+    #
+    # @example
+    #   plot = Splot.new
+    #   plot.title #=> nil
+    #   plot.title!('Awesome plot')
+    #   plot.title #=> 'Awesome plot'
+    #
+    # @example
+    #   plot = Splot.new
+    #   plot.title #=> nil
+    #   plot.title = 'Awesome plot'
+    #   plot.title #=> 'Awesome plot'
+
+    ##
+    # @!method to_png(path = nil, **options)
+    # @!method to_svg(path = nil, **options)
+    # @!method to_gif(path = nil, **options)
+    # @!method to_canvas(path = nil, **options)
+    # Output to plot to according image format.
+    #
+    # All of #to_|terminal_name| methods are handled with #method_missing.
+    #
+    # Gnuplot offers possibility to output graphics to many image formats.
+    # The easiest way to to so is to use #to_<plot_name> methods.
+    #
+    # @param path [String] path to save plot file to.
+    # @param options [Hash] specific terminal options like 'size',
+    #   'font' etc
+    #
+    # @return [String] contents of plotted file unless path given
+    # @return self if path given
+    #
+    # @example
+    #   # font options specific for png term
+    #   multiplot.to_png('./result.png', size: [300, 500], font: ['arial', 12])
+    #   # font options specific for svg term
+    #   content = multiplot.to_svg(size: [100, 100], fname: 'Arial', fsize: 12)
   end
 end

data/lib/gnuplotrb/multiplot.rb

@@ -1,38 +1,44 @@
 module GnuplotRB
   ##
-  # === Overview
   # Multiplot allows to place several plots on one layout.
-  # It's usage is covered in {multiplot notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/multiplot_layout.ipynb].
+  # It's usage is covered in
+  # {multiplot notebook}[http://nbviewer.ipython.org/github/dilcom/gnuplotrb/blob/master/notebooks/multiplot_layout.ipynb].
+  #
+  # == Options
+  # Most of Multiplot options are the same as in Plot so one can also set any options related
+  # to Plot and they will be considered by all nested plots
+  # (if they does not override it with their own values).
+  #
+  # There are only 2 specific options:
+  # * title - set title for the whole layout (above all the plots)
+  # * layout - set layout size, examples:
+  #     { layout : [1, 3] } # 3 plots, 1 row, 3 columns
+  #     { layout : [2, 2] } # 4 plots, 2 rows, 2 columns
   class Multiplot
     include Plottable
     ##
-    # Array of plots contained by this object.
+    # @return [Array] Array of plots contained by this object
     attr_reader :plots
 
     ##
-    # ====== Arguments
-    # * *plots* are Plot or Splot objects which should be placed
-    #   on this multiplot layout
-    # * *options* will be considered as 'settable' options of gnuplot
-    #   ('set xrange [1:10]' for { xrange: 1..10 } etc) just as in Plot.
-    #   Special options of Multiplot are :layout and :title.
+    # @param plots [Plot, Splot, Hamster::Vector] Hamster vector (or just sequence) with Plot
+    #   or Splot objects which should be placed on this multiplot layout
+    # @param options [Hash] see options in top class docs
     def initialize(*plots, **options)
       @plots = plots[0].is_a?(Hamster::Vector) ? plots[0] : Hamster::Vector.new(plots)
       @options = Hamster.hash(options)
       OptionHandling.validate_terminal_options(@options)
+      yield(self) if block_given?
     end
 
     ##
-    # ====== Overview
-    # This outputs all the plots to term (if given) or to this
-    # Multiplot's own terminal.
-    # ====== Arguments
-    # * *term* - Terminal to plot to
-    # * *options* - will be considered as 'settable' options of gnuplot
-    #   ('set xrange [1:10]', 'set title 'plot'' etc)
-    # Options passed here have priority over already existing.
-    # Inner options of Plots have the highest priority (except
-    # :term and :output which are ignored in this case).
+    # Output all the plots to term (if given) or to this Multiplot's own terminal.
+    #
+    # @param term [Terminal] Terminal to plot to
+    # @param multiplot_part [Boolean] placeholder, does not really needed and should not be used
+    # @param options [Hash] see options in top class docs.
+    #   Options passed here have priority over already set.
+    # @return [Multiplot] self
     def plot(term = nil, multiplot_part: false, **options)
       plot_options = mix_options(options) do |plot_opts, mp_opts|
         plot_opts.merge(multiplot: mp_opts.to_h)
@@ -50,21 +56,25 @@ module GnuplotRB
     end
 
     ##
-    # ====== Overview
-    # Create new Multiplot object where plot (Plot or Splot object)
-    # at *position* will
+    # Create new updated Multiplot object
+    # where plot (Plot or Splot object) at *position* will
     # be replaced with the new one created from it by updating.
     # To update a plot you can pass some options for it or a
     # block, that should take existing plot (with new options if
     # you gave them) and return a plot too.
-    # ====== Arguments
-    # * *position* - position of plot which you need to update
+    #
+    # Method yields new created Plot or Splot to allow you update it manually.
+    #
+    # @param position [Integer] position of plot which you need to update
     #   (by default first plot is updated)
-    # * *options* - options to update plot with
-    # * *&block* - method also may take a block which returns a plot
-    # ====== Example
+    # @param options [Hash] options to set into updated plot
+    # @return [Multiplot] self
+    # @yieldparam plot [Plot, Splot] a new plot
+    # @yieldreturn [Plot, Splot] changed plot
+    # @example
     #   mp = Multiplot.new(Plot.new('sin(x)'), Plot.new('cos(x)'), layout: [2,1])
-    #   updated_mp = mp.update_plot(title: 'Sin(x) and Exp(x)') { |sinx| sinx.add('exp(x)') }
+    #   updated_mp = mp.update_plot(title: 'Sin(x) and Exp(x)') { |sinx| sinx.add!('exp(x)') }
+    #   # mp IS NOT affected
     def update_plot(position = 0, **options)
       return self unless block_given? if options.empty?
       replacement = @plots[position].options(options)
@@ -75,16 +85,34 @@ module GnuplotRB
     alias_method :update, :update_plot
 
     ##
-    # ====== Overview
+    # Destructive version of #update_plot.
+    #
+    # @return [Multiplot] self
+    # @example
+    #   Multiplot.new(Plot.new('sin(x)'), Plot.new('cos(x)'), layout: [2,1])
+    #   mp.update_plot!(title: 'Sin(x) and Exp(x)') { |sinx| sinx.add!('exp(x)') }
+    #   # mp IS affected
+    def update_plot!(position = 0, **options)
+      return self unless block_given? if options.empty?
+      replacement = @plots[position].options!(options)
+      yield(replacement) if block_given?
+      self
+    end
+
+    alias_method :update!, :update_plot!
+
+    ##
     # Create new Multiplot object where plot (Plot or Splot object)
     # at *position* will be replaced with the given one.
-    # ====== Arguments
-    # * *position* - position of plot which you need to update
-    #   (by default first plot is updated)
-    # * *plot* - replacement for existing plot
-    # ====== Example
+    #
+    # @param position [Integer] position of plot which you need to replace
+    #   (by default first plot is replace)
+    # @param plot [Plot, Splot] replacement
+    # @return [Multiplot] self
+    # @example
     #   mp = Multiplot.new(Plot.new('sin(x)'), Plot.new('cos(x)'), layout: [2,1])
     #   mp_with_replaced_plot = mp.replace_plot(Plot.new('exp(x)', title: 'exp instead of sin'))
+    #   # mp IS NOT affected
     def replace_plot(position = 0, plot)
       self.class.new(@plots.set(position, plot), @options)
     end
@@ -92,15 +120,33 @@ module GnuplotRB
     alias_method :replace, :replace_plot
 
     ##
-    # ====== Overview
+    # Destructive version of #replace_plot.
+    #
+    # @return [Multiplot] self
+    # @example
+    #   mp = Multiplot.new(Plot.new('sin(x)'), Plot.new('cos(x)'), layout: [2,1])
+    #   mp.replace_plot!(Plot.new('exp(x)', title: 'exp instead of sin'))
+    #   # mp IS affected
+    def replace_plot!(position = 0, plot)
+      @plots = @plots.set(position, plot)
+      self
+    end
+
+    alias_method :replace!, :replace_plot!
+    alias_method :[]=, :replace_plot!
+
+    ##
     # Create new Multiplot with given *plots* added before plot at given *position*.
     # (by default it adds plot at the front).
-    # ====== Arguments
-    # * *position* - position before which you want to add a plot
-    # * *plots* - sequence of plots you want to add
-    # ====== Example
+    #
+    # @param position [Integer] position of plot which you need to replace
+    #   (by default first plot is replace)
+    # @param plots [Sequence of Plot or Splot] plots you want to add
+    # @return [Multiplot] self
+    # @example
     #   mp = Multiplot.new(Plot.new('sin(x)'), Plot.new('cos(x)'), layout: [2,1])
     #   enlarged_mp = mp.add_plots(Plot.new('exp(x)')).layout([3,1])
+    #   # mp IS NOT affected
     def add_plots(*plots)
       plots.unshift(0) unless plots[0].is_a?(Numeric)
       self.class.new(@plots.insert(*plots), @options)
@@ -111,14 +157,33 @@ module GnuplotRB
     alias_method :add, :add_plots
 
     ##
-    # ====== Overview
+    # Destructive version of #add_plots.
+    #
+    # @return [Multiplot] self
+    # @example
+    #   mp = Multiplot.new(Plot.new('sin(x)'), Plot.new('cos(x)'), layout: [2,1])
+    #   mp.add_plots!(Plot.new('exp(x)')).layout([3,1])
+    #   # mp IS affected
+    def add_plots!(*plots)
+      plots.unshift(0) unless plots[0].is_a?(Numeric)
+      @plots = @plots.insert(*plots)
+      self
+    end
+
+    alias_method :add_plot!, :add_plots!
+    alias_method :add!, :add_plots!
+
+    ##
     # Create new Multiplot without plot at given position
     # (by default last plot is removed).
-    # ====== Arguments
-    # * *position* - position of plot you want to remove
-    # ====== Example
+    #
+    # @param position [Integer] position of plot which you need to remove
+    #   (by default last plot is removed)
+    # @return [Multiplot] self
+    # @example
     #   mp = Multiplot.new(Plot.new('sin(x)'), Plot.new('cos(x)'), layout: [2,1])
     #   mp_with_only_cos = mp.remove_plot(0)
+    #   # mp IS NOT affected
     def remove_plot(position = -1)
       self.class.new(@plots.delete_at(position), @options)
     end
@@ -126,7 +191,21 @@ module GnuplotRB
     alias_method :remove, :remove_plot
 
     ##
-    # ====== Overview
+    # Destructive version of #remove_plot.
+    #
+    # @return [Multiplot] self
+    # @example
+    #   mp = Multiplot.new(Plot.new('sin(x)'), Plot.new('cos(x)'), layout: [2,1])
+    #   mp.remove_plot!(0)
+    #   # mp IS affected
+    def remove_plot!(position = -1)
+      @plots = @plots.delete_at(position)
+      self
+    end
+
+    alias_method :remove!, :remove_plot!
+
+    ##
     # Equal to #plots[*args]
     def [](*args)
       @plots[*args]