Skip to content

Commit

Permalink
update mixins doc for YARD
Browse files Browse the repository at this point in the history
  • Loading branch information
@ievgrafov
ievgrafov committed Aug 9, 2015
1 parent a9ca5aa commit 11011fe
Show file tree
Hide file tree
Showing 3 changed files with 148 additions and 60 deletions.
2 changes: 0 additions & 2 deletions lib/gnuplotrb/mixins/error_handling.rb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@ class GnuplotError < ArgumentError
# 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
Expand All @@ -28,7 +27,6 @@ def check_errors
private

##
# ====== Overview
# Start new thread that will read stderr given as stream
# and add errors into @err_array.
def handle_stderr(stream)
Expand Down
79 changes: 46 additions & 33 deletions lib/gnuplotrb/mixins/option_handling.rb
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -34,24 +33,29 @@ class << self
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)
Expand All @@ -62,6 +66,7 @@ def option_to_string(key = nil, option)
end

##
# @private
# Method for inner use.
# Needed to convert several ruby classes into
# value that should be piped to gnuplot.
Expand All @@ -81,23 +86,20 @@ def ruby_class_to_gnuplot(option_object)
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
Expand All @@ -110,34 +112,35 @@ def validate_terminal_options(options)
end

##
# @private
# You should implement #initialize in classes that use OptionsHelper
def initialize(*_)
fail NotImplementedError, 'You should implement #initialize' \
' in classes that use OptionsHelper!'
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' \
' in classes that use OptionsHelper!'
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?
Expand All @@ -148,7 +151,16 @@ def options(**options)
end

##
# Destructive twin of #options
# 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
Expand All @@ -157,9 +169,8 @@ def options!(**options)
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]
Expand All @@ -170,6 +181,8 @@ def option(key, *value)
end
end

##
# Just set an option.
def option!(key, *value)
options!(key => value)
end
Expand Down
127 changes: 102 additions & 25 deletions lib/gnuplotrb/mixins/plottable.rb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,39 +7,39 @@ module Plottable
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
Expand All @@ -62,8 +62,9 @@ def method_missing(meth_id, *args)
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.
Expand All @@ -74,8 +75,7 @@ def respond_to?(meth_id)
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
Expand All @@ -92,20 +92,16 @@ def to_iruby
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])
Expand All @@ -123,9 +119,90 @@ def to_specific_term(terminal, path = nil, **options)
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

0 comments on commit 11011fe

Please sign in to comment.