gnuplotrb 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,35 +1,39 @@
1
1
  module GnuplotRB
2
2
  ##
3
- # This module takes care of path to gnuplot executable
4
- # and checking its version.
3
+ # This module takes care of path to gnuplot executable and checking its version.
5
4
  module Settings
6
5
  ##
7
- # Since gem uses some modern gnuplot features it's
8
- # required to have modern gnuplot installed.
6
+ # GnuplotRB can work with Gnuplot 5.0+
9
7
  MIN_GNUPLOT_VERSION = 5.0
10
8
 
11
9
  class << self
12
10
  ##
13
- # Max fit dely is used inside fit function.
14
- # If it waits for output more than max_fit_delay seconds
15
- # this behaviour is considered as errorneus.
16
11
  # For heavy calculations max_fit_delay may be increased.
17
12
  attr_writer :max_fit_delay
13
+ ##
14
+ # Get max fit delay.
15
+ #
16
+ # Max fit delay (5s by default) is used inside Fit::fit function.
17
+ # If it waits for output more than max_fit_delay seconds
18
+ # this behaviour is considered as errorneus.
19
+ # @return [Integer] seconds to wait for output
18
20
  def max_fit_delay
19
21
  @max_fit_delay ||= 5
20
22
  end
23
+
21
24
  ##
22
- # ====== Overview
23
25
  # Get path that should be used to run gnuplot executable.
24
- # Default value: 'gnuplot'
26
+ # Default value: 'gnuplot'.
27
+ # @return [String] path to gnuplot executable
25
28
  def gnuplot_path
26
29
  self.gnuplot_path = 'gnuplot' unless defined?(@gnuplot_path)
27
30
  @gnuplot_path
28
31
  end
29
32
 
30
33
  ##
31
- # ====== Overview
32
34
  # Set path to gnuplot executable.
35
+ # @param path [String] path to gnuplot executable
36
+ # @return given path
33
37
  def gnuplot_path=(path)
34
38
  validate_version(path)
35
39
  opts = { stdin_data: "set term\n" }
@@ -41,29 +45,28 @@ module GnuplotRB
41
45
  end
42
46
 
43
47
  ##
44
- # ====== Overview
45
- # Get list of terminals (png, html, qt, jpeg etc)
46
- # available for that gnuplot.
48
+ # Get list of terminals (png, html, qt, jpeg etc) available for this gnuplot.
49
+ # @return [Array of String] array of terminals available for this gnuplot
47
50
  def available_terminals
48
51
  gnuplot_path
49
52
  @available_terminals
50
53
  end
51
54
 
52
55
  ##
53
- # ====== Overview
54
- # Get gnuplot version. Uses gnuplot_path to find
55
- # gnuplot executable.
56
+ # Get gnuplot version. Uses gnuplot_path to find gnuplot executable.
57
+ # @return [Numeric] gnuplot version
56
58
  def version
57
59
  gnuplot_path
58
60
  @version
59
61
  end
60
62
 
61
63
  ##
62
- # ====== Overview
63
- # Validates gnuplot version. Compares current gnuplot's
64
- # version with ::MIN_GNUPLOT_VERSION.
65
- # ====== Arguments
66
- # * *path* - path to gnuplot executable.
64
+ # @private
65
+ # Validate gnuplot version. Compares current gnuplot's
66
+ # version with ::MIN_GNUPLOT_VERSION. Throws exception if version is
67
+ # less than min.
68
+ #
69
+ # @param path [String] path to gnuplot executable
67
70
  def validate_version(path)
68
71
  @version = IO.popen("#{path} --version")
69
72
  .read
@@ -1,33 +1,49 @@
1
1
  module GnuplotRB
2
2
  ##
3
- # === Overview
4
3
  # Terminal keeps open pipe to gnuplot process, cares about naming in-memory
5
4
  # datablocks (just indexing with sequential integers). All the output
6
5
  # to gnuplot handled by this class. Terminal also handles options passed
7
6
  # to gnuplot as 'set key value'.
8
7
  class Terminal
9
8
  include ErrorHandling
9
+
10
+ # order is important for some options
10
11
  OPTION_ORDER = [:term, :output, :multiplot, :timefmt, :xrange]
11
12
 
13
+ private_constant :OPTION_ORDER
14
+
12
15
  class << self
13
16
  ##
14
17
  # Close given gnuplot pipe
18
+ # @param stream [IO] pipe to close
15
19
  def close_arg(stream)
16
20
  stream.puts
17
21
  stream.puts 'exit'
18
22
  Process.waitpid(stream.pid)
19
23
  end
24
+
25
+ ##
26
+ # Plot test page for given term_name into file
27
+ # with file_name (optional).
28
+ #
29
+ # Test page contains possibilities of the term.
30
+ # @param term_name [String] terminal name ('png', 'gif', 'svg' etc)
31
+ # @param file_name [String] filename to output image if needed
32
+ # and chosen terminal supports image output
33
+ # @return nil
34
+ def test(term_name, file_name = nil)
35
+ Terminal.new.set(term: term_name).test(file_name)
36
+ end
20
37
  end
21
38
 
22
39
  ##
23
- # ====== Overview
24
- # Creates new Terminal connected with gnuplot.
40
+ # Create new Terminal connected with gnuplot.
25
41
  # Uses Settings::gnuplot_path to find gnuplot
26
42
  # executable. Each time you create Terminal it starts new
27
43
  # gnuplot subprocess which is closed after GC deletes
28
44
  # linked Terminal object.
29
- # ====== Arguments
30
- # * *persist* - gnuplot's -persist option
45
+ #
46
+ # @param :persist [Boolean] gnuplot's "-persist" option
31
47
  def initialize(persist: false)
32
48
  @cmd = Settings.gnuplot_path
33
49
  @current_datablock = 0
@@ -41,11 +57,10 @@ module GnuplotRB
41
57
  end
42
58
 
43
59
  ##
44
- # ====== Overview
45
- # Outputs datablock to this gnuplot terminal.
46
- # ====== Arguments
47
- # * *data* - data stored in datablock
48
- # ====== Examples
60
+ # Output datablock to this gnuplot terminal.
61
+ #
62
+ # @param data [String] data stored in datablock
63
+ # @example
49
64
  # data = "1 1\n2 4\n3 9"
50
65
  # Terminal.new.store_datablock(data)
51
66
  # #=> returns '$DATA1'
@@ -64,14 +79,15 @@ module GnuplotRB
64
79
  end
65
80
 
66
81
  ##
67
- # ====== Overview
68
- # Converts given options to gnuplot format;
69
- # for {opt1: val1, .. , optN: valN} it returns
82
+ # Convert given options to gnuplot format.
83
+ #
84
+ # For "{ opt1: val1, .. , optN: valN }" it returns
70
85
  # set opt1 val1
71
86
  # ..
72
87
  # set optN valN
73
- # ====== Arguments
74
- # * *options* - hash of options to convert
88
+ #
89
+ # @param ptions [Hash] options to convert
90
+ # @return [String] options in Gnuplot format
75
91
  def options_hash_to_string(options)
76
92
  result = ''
77
93
  options.sort_by { |key, _| OPTION_ORDER.find_index(key) || -1 }.each do |key, value|
@@ -85,15 +101,16 @@ module GnuplotRB
85
101
  end
86
102
 
87
103
  ##
88
- # ====== Overview
89
- # Applies given options to current gnuplot instance;
90
- # for {opt1: val1, .. , optN: valN} it will output to gnuplot
104
+ # Applie given options to current gnuplot instance.
105
+ #
106
+ # For "{ opt1: val1, .. , optN: valN }" it will output to gnuplot
91
107
  # set opt1 val1
92
108
  # ..
93
109
  # set optN valN
94
- # ====== Arguments
95
- # *options* - hash of options to set
96
- # ====== Examples
110
+ #
111
+ # @param options [Hash] options to set
112
+ # @return [Terminal] self
113
+ # @example
97
114
  # set({term: ['qt', size: [100, 100]]})
98
115
  # #=> outputs to gnuplot: "set term qt size 100,100\n"
99
116
  def set(options)
@@ -102,10 +119,10 @@ module GnuplotRB
102
119
  end
103
120
 
104
121
  ##
105
- # ====== Overview
106
- # Unset some options
107
- # ====== Arguments
108
- # * **options* - Array of options need to unset
122
+ # Unset options
123
+ #
124
+ # @param *options [Sequence of Symbol] each symbol considered as option key
125
+ # @return [Terminal] self
109
126
  def unset(*options)
110
127
  options.flatten
111
128
  .sort_by { |key| OPTION_ORDER.find_index(key) || -1 }
@@ -114,9 +131,10 @@ module GnuplotRB
114
131
  end
115
132
 
116
133
  ##
117
- # ====== Overview
118
134
  # Short way to plot Datablock, Plot or Splot object.
119
135
  # Other items will be just piped out to gnuplot.
136
+ # @param item Object that should be outputted to Gnuplot
137
+ # @return [Terminal] self
120
138
  def <<(item)
121
139
  if item.is_a? Plottable
122
140
  item.plot(self)
@@ -127,17 +145,17 @@ module GnuplotRB
127
145
  end
128
146
 
129
147
  ##
130
- # ====== Overview
131
- # Just puts *command* to gnuplot pipe and returns self
132
- # to allow chaining.
148
+ # Just put *command* + "\n" to gnuplot pipe.
149
+ # @param command [String] command to send
150
+ # @return [Terminal] self
133
151
  def stream_puts(command)
134
152
  stream_print("#{command}\n")
135
153
  end
136
154
 
137
155
  ##
138
- # ====== Overview
139
- # Just prints *command* to gnuplot pipe and returns self
140
- # to allow chaining.
156
+ # Just print *command* to gnuplot pipe.
157
+ # @param command [String] command to send
158
+ # @return [Terminal] self
141
159
  def stream_print(command)
142
160
  check_errors
143
161
  @in.print(command)
@@ -145,9 +163,11 @@ module GnuplotRB
145
163
  end
146
164
 
147
165
  ##
148
- # ====== Overview
166
+ # @deprecated
149
167
  # Call replot on gnuplot. This will execute last plot once again
150
168
  # with rereading data.
169
+ # @param options [Hash] options will be set before replotting
170
+ # @return [Terminal] self
151
171
  def replot(**options)
152
172
  set(options)
153
173
  stream_puts('replot')
@@ -157,12 +177,26 @@ module GnuplotRB
157
177
  end
158
178
 
159
179
  ##
160
- # ====== Overview
161
180
  # Send gnuplot command to turn it off and for its Process to quit.
162
181
  # Closes pipe so Terminal object should not be used after #close call.
163
182
  def close
164
183
  check_errors
165
184
  Terminal.close_arg(@in)
166
185
  end
186
+
187
+
188
+ ##
189
+ # Plot test page into file with file_name (optional).
190
+ #
191
+ # Test page contains possibilities of the term.
192
+ # @param file_name [String] filename to output image if needed
193
+ # and chosen terminal supports image output
194
+ # @return nil
195
+ def test(file_name = nil)
196
+ set(output: file_name) if file_name
197
+ stream_puts('test')
198
+ unset(:output)
199
+ nil
200
+ end
167
201
  end
168
202
  end
@@ -2,5 +2,7 @@
2
2
  # === Overview
3
3
  # Ruby bindings for gnuplot.
4
4
  module GnuplotRB
5
- VERSION = '0.3.0'
5
+ ##
6
+ # Gem version
7
+ VERSION = '0.3.1'
6
8
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: gnuplotrb
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.3.0
4
+ version: 0.3.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Ivan Evgrafov
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2015-07-30 00:00:00.000000000 Z
11
+ date: 2015-08-18 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: hamster
@@ -67,19 +67,19 @@ dependencies:
67
67
  - !ruby/object:Gem::Version
68
68
  version: '3.2'
69
69
  - !ruby/object:Gem::Dependency
70
- name: rdoc
70
+ name: yard
71
71
  requirement: !ruby/object:Gem::Requirement
72
72
  requirements:
73
73
  - - "~>"
74
74
  - !ruby/object:Gem::Version
75
- version: '4.2'
75
+ version: '0.8'
76
76
  type: :development
77
77
  prerelease: false
78
78
  version_requirements: !ruby/object:Gem::Requirement
79
79
  requirements:
80
80
  - - "~>"
81
81
  - !ruby/object:Gem::Version
82
- version: '4.2'
82
+ version: '0.8'
83
83
  - !ruby/object:Gem::Dependency
84
84
  name: rubocop
85
85
  requirement: !ruby/object:Gem::Requirement
@@ -185,8 +185,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
185
185
  version: '0'
186
186
  requirements: []
187
187
  rubyforge_project:
188
- rubygems_version: 2.4.5
188
+ rubygems_version: 2.2.3
189
189
  signing_key:
190
190
  specification_version: 4
191
191
  summary: Ruby bindings for gnuplot
192
192
  test_files: []
193
+ has_rdoc: