gnuplotrb 0.3.0 → 0.3.1

data/lib/gnuplotrb/staff/settings.rb

@@ -1,35 +1,39 @@
 module GnuplotRB
   ##
-  # This module takes care of path to gnuplot executable
-  # and checking its version.
+  # This module takes care of path to gnuplot executable and checking its version.
   module Settings
     ##
-    # Since gem uses some modern gnuplot features it's
-    # required to have modern gnuplot installed.
+    # GnuplotRB can work with Gnuplot 5.0+
     MIN_GNUPLOT_VERSION = 5.0
 
     class << self
       ##
-      # Max fit dely is used inside fit function.
-      # If it waits for output more than max_fit_delay seconds
-      # this behaviour is considered as errorneus.
       # For heavy calculations max_fit_delay may be increased.
       attr_writer :max_fit_delay
+      ##
+      # Get max fit delay.
+      #
+      # Max fit delay (5s by default) is used inside Fit::fit function.
+      # If it waits for output more than max_fit_delay seconds
+      # this behaviour is considered as errorneus.
+      # @return [Integer] seconds to wait for output
       def max_fit_delay
         @max_fit_delay ||= 5
       end
+
       ##
-      # ====== Overview
       # Get path that should be used to run gnuplot executable.
-      # Default value: 'gnuplot'
+      # Default value: 'gnuplot'.
+      # @return [String] path to gnuplot executable
       def gnuplot_path
         self.gnuplot_path = 'gnuplot' unless defined?(@gnuplot_path)
         @gnuplot_path
       end
 
       ##
-      # ====== Overview
       # Set path to gnuplot executable.
+      # @param path [String] path to gnuplot executable
+      # @return given path
       def gnuplot_path=(path)
         validate_version(path)
         opts = { stdin_data: "set term\n" }
@@ -41,29 +45,28 @@ module GnuplotRB
       end
 
       ##
-      # ====== Overview
-      # Get list of terminals (png, html, qt, jpeg etc)
-      # available for that gnuplot.
+      # Get list of terminals (png, html, qt, jpeg etc) available for this gnuplot.
+      # @return [Array of String] array of terminals available for this gnuplot
       def available_terminals
         gnuplot_path
         @available_terminals
       end
 
       ##
-      # ====== Overview
-      # Get gnuplot version. Uses gnuplot_path to find
-      # gnuplot executable.
+      # Get gnuplot version. Uses gnuplot_path to find gnuplot executable.
+      # @return [Numeric] gnuplot version
       def version
         gnuplot_path
         @version
       end
 
       ##
-      # ====== Overview
-      # Validates gnuplot version. Compares current gnuplot's
-      # version with ::MIN_GNUPLOT_VERSION.
-      # ====== Arguments
-      # * *path* - path to gnuplot executable.
+      # @private
+      # Validate gnuplot version. Compares current gnuplot's
+      # version with ::MIN_GNUPLOT_VERSION. Throws exception if version is
+      # less than min.
+      #
+      # @param path [String] path to gnuplot executable
       def validate_version(path)
         @version = IO.popen("#{path} --version")
                      .read

data/lib/gnuplotrb/staff/terminal.rb

@@ -1,33 +1,49 @@
 module GnuplotRB
   ##
-  # === Overview
   # Terminal keeps open pipe to gnuplot process, cares about naming in-memory
   # datablocks (just indexing with sequential integers). All the output
   # to gnuplot handled by this class. Terminal also handles options passed
   # to gnuplot as 'set key value'.
   class Terminal
     include ErrorHandling
+
+    # order is important for some options
     OPTION_ORDER = [:term, :output, :multiplot, :timefmt, :xrange]
 
+    private_constant :OPTION_ORDER
+
     class << self
       ##
       # Close given gnuplot pipe
+      # @param stream [IO] pipe to close
       def close_arg(stream)
         stream.puts
         stream.puts 'exit'
         Process.waitpid(stream.pid)
       end
+
+      ##
+      # Plot test page for given term_name into file
+      # with file_name (optional).
+      #
+      # Test page contains possibilities of the term.
+      # @param term_name [String] terminal name ('png', 'gif', 'svg' etc)
+      # @param file_name [String] filename to output image if needed
+      #   and chosen terminal supports image output
+      # @return nil
+      def test(term_name, file_name = nil)
+        Terminal.new.set(term: term_name).test(file_name)
+      end
     end
 
     ##
-    # ====== Overview
-    # Creates new Terminal connected with gnuplot.
+    # Create new Terminal connected with gnuplot.
     # Uses Settings::gnuplot_path to find gnuplot
     # executable. Each time you create Terminal it starts new
     # gnuplot subprocess which is closed after GC deletes
     # linked Terminal object.
-    # ====== Arguments
-    # * *persist* - gnuplot's -persist option
+    #
+    # @param :persist [Boolean] gnuplot's "-persist" option
     def initialize(persist: false)
       @cmd = Settings.gnuplot_path
       @current_datablock = 0
@@ -41,11 +57,10 @@ module GnuplotRB
     end
 
     ##
-    # ====== Overview
-    # Outputs datablock to this gnuplot terminal.
-    # ====== Arguments
-    # * *data* - data stored in datablock
-    # ====== Examples
+    # Output datablock to this gnuplot terminal.
+    #
+    # @param data [String] data stored in datablock
+    # @example
     #   data = "1 1\n2 4\n3 9"
     #   Terminal.new.store_datablock(data)
     #   #=> returns '$DATA1'
@@ -64,14 +79,15 @@ module GnuplotRB
     end
 
     ##
-    # ====== Overview
-    # Converts given options to gnuplot format;
-    # for {opt1: val1, .. , optN: valN} it returns
+    # Convert given options to gnuplot format.
+    #
+    # For "{ opt1: val1, .. , optN: valN }" it returns
     #   set opt1 val1
     #   ..
     #   set optN valN
-    # ====== Arguments
-    # * *options* - hash of options to convert
+    #
+    # @param ptions [Hash] options to convert
+    # @return [String] options in Gnuplot format
     def options_hash_to_string(options)
       result = ''
       options.sort_by { |key, _| OPTION_ORDER.find_index(key) || -1 }.each do |key, value|
@@ -85,15 +101,16 @@ module GnuplotRB
     end
 
     ##
-    # ====== Overview
-    # Applies given options to current gnuplot instance;
-    # for {opt1: val1, .. , optN: valN} it will output to gnuplot
+    # Applie given options to current gnuplot instance.
+    #
+    # For "{ opt1: val1, .. , optN: valN }" it will output to gnuplot
     #   set opt1 val1
     #   ..
     #   set optN valN
-    # ====== Arguments
-    # *options* - hash of options to set
-    # ====== Examples
+    #
+    # @param options [Hash] options to set
+    # @return [Terminal] self
+    # @example
     #   set({term: ['qt', size: [100, 100]]})
     #   #=> outputs to gnuplot: "set term qt size 100,100\n"
     def set(options)
@@ -102,10 +119,10 @@ module GnuplotRB
     end
 
     ##
-    # ====== Overview
-    # Unset some options
-    # ====== Arguments
-    # * **options* - Array of options need to unset
+    # Unset options
+    #
+    # @param *options [Sequence of Symbol] each symbol considered as option key
+    # @return [Terminal] self
     def unset(*options)
       options.flatten
              .sort_by { |key| OPTION_ORDER.find_index(key) || -1 }
@@ -114,9 +131,10 @@ module GnuplotRB
     end
 
     ##
-    # ====== Overview
     # Short way to plot Datablock, Plot or Splot object.
     # Other items will be just piped out to gnuplot.
+    # @param item Object that should be outputted to Gnuplot
+    # @return [Terminal] self
     def <<(item)
       if item.is_a? Plottable
         item.plot(self)
@@ -127,17 +145,17 @@ module GnuplotRB
     end
 
     ##
-    # ====== Overview
-    # Just puts *command* to gnuplot pipe and returns self
-    # to allow chaining.
+    # Just put *command* + "\n" to gnuplot pipe.
+    # @param command [String] command to send
+    # @return [Terminal] self
     def stream_puts(command)
       stream_print("#{command}\n")
     end
 
     ##
-    # ====== Overview
-    # Just prints *command* to gnuplot pipe and returns self
-    # to allow chaining.
+    # Just print *command* to gnuplot pipe.
+    # @param command [String] command to send
+    # @return [Terminal] self
     def stream_print(command)
       check_errors
       @in.print(command)
@@ -145,9 +163,11 @@ module GnuplotRB
     end
 
     ##
-    # ====== Overview
+    # @deprecated
     # Call replot on gnuplot. This will execute last plot once again
     # with rereading data.
+    # @param options [Hash] options will be set before replotting
+    # @return [Terminal] self
     def replot(**options)
       set(options)
       stream_puts('replot')
@@ -157,12 +177,26 @@ module GnuplotRB
     end
 
     ##
-    # ====== Overview
     # Send gnuplot command to turn it off and for its Process to quit.
     # Closes pipe so Terminal object should not be used after #close call.
     def close
       check_errors
       Terminal.close_arg(@in)
     end
+
+
+    ##
+    # Plot test page into file with file_name (optional).
+    #
+    # Test page contains possibilities of the term.
+    # @param file_name [String] filename to output image if needed
+    #   and chosen terminal supports image output
+    # @return nil
+    def test(file_name = nil)
+      set(output: file_name) if file_name
+      stream_puts('test')
+      unset(:output)
+      nil
+    end
   end
 end

data/lib/gnuplotrb/version.rb

@@ -2,5 +2,7 @@
 # === Overview
 # Ruby bindings for gnuplot.
 module GnuplotRB
-  VERSION = '0.3.0'
+  ##
+  # Gem version
+  VERSION = '0.3.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gnuplotrb
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Ivan Evgrafov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-30 00:00:00.000000000 Z
+date: 2015-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hamster
@@ -67,19 +67,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.2'
 - !ruby/object:Gem::Dependency
-  name: rdoc
+  name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.2'
+        version: '0.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.2'
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -185,8 +185,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.2.3
 signing_key: 
 specification_version: 4
 summary: Ruby bindings for gnuplot
 test_files: []
+has_rdoc: