Class: GnuplotRB::Terminal

Inherits:
Object
  • Object
show all
Includes:
ErrorHandling
Defined in:
lib/gnuplotrb/staff/terminal.rb

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 Method Summary collapse

Instance Method Summary collapse

Methods included from ErrorHandling

#check_errors

Constructor Details

#initialize(persist: false) {|_self| ... } ⇒ Terminal

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.

Parameters:

  • :persist (Boolean)

    gnuplot's “-persist” option

Yields:

  • (_self)

Yield Parameters:


47
48
49
50
51
52
53
54
55
56
57
# File 'lib/gnuplotrb/staff/terminal.rb', line 47

def initialize(persist: false)
  @cmd = Settings.gnuplot_path
  @current_datablock = 0
  @cmd += ' -persist' if persist
  @cmd += ' 2>&1'
  stream = IO.popen(@cmd, 'w+')
  handle_stderr(stream)
  ObjectSpace.define_finalizer(self, proc { Terminal.close_arg(stream) })
  @in = stream
  yield(self) if block_given?
end

Class Method Details

.close_arg(stream) ⇒ Object

Close given gnuplot pipe

Parameters:

  • stream (IO)

    pipe to close


19
20
21
22
23
# File 'lib/gnuplotrb/staff/terminal.rb', line 19

def close_arg(stream)
  stream.puts
  stream.puts 'exit'
  Process.waitpid(stream.pid)
end

.test(term_name, file_name = nil) ⇒ Object

Plot test page for given term_name into file with file_name (optional).

Test page contains possibilities of the term.

Parameters:

  • term_name (String)

    terminal name ('png', 'gif', 'svg' etc)

  • file_name (String) (defaults to: nil)

    filename to output image if needed and chosen terminal supports image output

Returns:

  • nil


34
35
36
# File 'lib/gnuplotrb/staff/terminal.rb', line 34

def test(term_name, file_name = nil)
  Terminal.new.set(term: term_name).test(file_name)
end

Instance Method Details

#<<(item) ⇒ Terminal

Short way to plot Datablock, Plot or Splot object. Other items will be just piped out to gnuplot.

Parameters:

  • item

    Object that should be outputted to Gnuplot

Returns:


138
139
140
141
142
143
144
145
# File 'lib/gnuplotrb/staff/terminal.rb', line 138

def <<(item)
  if item.is_a? Plottable
    item.plot(self)
  else
    stream_print(item.to_s)
  end
  self
end

#closeObject

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.


182
183
184
185
# File 'lib/gnuplotrb/staff/terminal.rb', line 182

def close
  check_errors
  Terminal.close_arg(@in)
end

#options_hash_to_string(options) ⇒ String

Convert given options to gnuplot format.

For “{ opt1: val1, .. , optN: valN }” it returns

set opt1 val1
..
set optN valN

Parameters:

  • ptions (Hash)

    options to convert

Returns:

  • (String)

    options in Gnuplot format


91
92
93
94
95
96
97
98
99
100
101
# File 'lib/gnuplotrb/staff/terminal.rb', line 91

def options_hash_to_string(options)
  result = ''
  options.sort_by { |key, _| OPTION_ORDER.find_index(key) || -1 }.each do |key, value|
    if value
      result += "set #{OptionHandling.option_to_string(key, value)}\n"
    else
      result += "unset #{key}\n"
    end
  end
  result
end

#replot(**options) ⇒ Terminal

Deprecated.

Call replot on gnuplot. This will execute last plot once again with rereading data.

Parameters:

  • options (Hash)

    options will be set before replotting

Returns:


171
172
173
174
175
176
177
# File 'lib/gnuplotrb/staff/terminal.rb', line 171

def replot(**options)
  set(options)
  stream_puts('replot')
  unset(options.keys)
  sleep 0.01 until File.size?(options[:output]) if options[:output]
  self
end

#set(options) ⇒ Terminal

Applie given options to current gnuplot instance.

For “{ opt1: val1, .. , optN: valN }” it will output to gnuplot

set opt1 val1
..
set optN valN

Examples:

set({term: ['qt', size: [100, 100]]})
#=> outputs to gnuplot: "set term qt size 100,100\n"

Parameters:

  • options (Hash)

    options to set

Returns:


116
117
118
119
# File 'lib/gnuplotrb/staff/terminal.rb', line 116

def set(options)
  OptionHandling.validate_terminal_options(options)
  stream_puts(options_hash_to_string(options))
end

#store_datablock(data) ⇒ Object

Output datablock to this gnuplot terminal.

Examples:

data = "1 1\n2 4\n3 9"
Terminal.new.store_datablock(data)
#=> returns '$DATA1'
#=> outputs to gnuplot:
#=>   $DATA1 << EOD
#=>   1 1
#=>   2 4
#=>   3 9
#=>   EOD

Parameters:

  • data (String)

    data stored in datablock


73
74
75
76
77
78
79
# File 'lib/gnuplotrb/staff/terminal.rb', line 73

def store_datablock(data)
  name = "$DATA#{@current_datablock += 1}"
  stream_puts "#{name} << EOD"
  stream_puts data
  stream_puts 'EOD'
  name
end

#stream_print(command) ⇒ Terminal

Just print command to gnuplot pipe.

Parameters:

  • command (String)

    command to send

Returns:


159
160
161
162
163
# File 'lib/gnuplotrb/staff/terminal.rb', line 159

def stream_print(command)
  check_errors
  @in.print(command)
  self
end

#stream_puts(command) ⇒ Terminal

Just put command + “n” to gnuplot pipe.

Parameters:

  • command (String)

    command to send

Returns:


151
152
153
# File 'lib/gnuplotrb/staff/terminal.rb', line 151

def stream_puts(command)
  stream_print("#{command}\n")
end

#test(file_name = nil) ⇒ Object

Plot test page into file with file_name (optional).

Test page contains possibilities of the term.

Parameters:

  • file_name (String) (defaults to: nil)

    filename to output image if needed and chosen terminal supports image output

Returns:

  • nil


195
196
197
198
199
200
# File 'lib/gnuplotrb/staff/terminal.rb', line 195

def test(file_name = nil)
  set(output: file_name) if file_name
  stream_puts('test')
  unset(:output)
  nil
end

#unset(*options) ⇒ Terminal

Unset options

Parameters:

  • *options (Sequence of Symbol)

    each symbol considered as option key

Returns:


126
127
128
129
130
131
# File 'lib/gnuplotrb/staff/terminal.rb', line 126

def unset(*options)
  options.flatten
         .sort_by { |key| OPTION_ORDER.find_index(key) || -1 }
         .each { |key| stream_puts "unset #{OptionHandling.string_key(key)}" }
  self
end