Module: Ionian::Extension::IO

Defined in:
lib/ionian/extension/io.rb

Overview

A mixin for IO objects that allows regular expression matching and convenient notification of received data.

This module was designed to be extended by instantiated objects that implement the standard library IO class. my_socket.extend Ionian::IO

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#ionian_timeout ⇒ Object

Number of seconds to attempt an IO operation before timing out. See standard library IO::select.



14
15
16
 
# File 'lib/ionian/extension/io.rb', line 14

def ionian_timeout
  @ionian_timeout
end

Class Method Details

.extended(obj) ⇒ Object

Called automaticallly when the object is extended with #extend.



17
18
19
 
# File 'lib/ionian/extension/io.rb', line 17

def self.extended obj
  obj.initialize_ionian
end

Instance Method Details

#expression ⇒ Regexp

Returns the regular expression used for #read_match.

Returns:

  • (Regexp) —

    the regular expression used for #read_match.



43
44
45
 
# File 'lib/ionian/extension/io.rb', line 43

def expression
  @ionian_expression
end

#expression=(exp) ⇒ Object

Set the expression to match against the read buffer. Can be a regular expression specifying capture groups, or a string specifying the separator or line terminator sequence. It is possible to use named captures in a regex, which allows for convienient accessors like match.

Parameters:

  • exp (Regexp, String) —

    Match expression.



54
55
56
57
 
# File 'lib/ionian/extension/io.rb', line 54

def expression= exp
  @ionian_expression = exp
  @ionian_expression = Regexp.new "(.*?)#{expression}" if exp.is_a? String
end

#has_data?(timeout: 0) ⇒ Boolean

Returns True if there is data in the receive buffer.

Parameters:

  • timeout (Numeric) (defaults to: 0) —

    Number of seconds to wait for data until giving up. Set to nil for blocking.

Returns:

  • (Boolean) —

    True if there is data in the receive buffer.



38
39
40
 
# File 'lib/ionian/extension/io.rb', line 38

def has_data? timeout: 0
  ::IO.select([self], nil, nil, timeout) ? true : false
end

#initialize_ionian ⇒ Object

Initialize the Ionian instance variables. This is called automatically if #extend is called on an object.



23
24
25
26
27
28
29
30
31
 
# File 'lib/ionian/extension/io.rb', line 23

def initialize_ionian
  @ionian_match_handlers = []
  @ionian_error_handlers = []
  @ionian_buf            = ''
  @ionian_expression     = /(.*?)[\r\n]+/
  @ionian_timeout        = nil
  @ionian_skip_select    = false
  @ionian_build_methods  = true
end

#purge ⇒ Object

Erase the data in the IO and Ionian buffers. This is typically handled automatically.



181
182
183
184
185
 
# File 'lib/ionian/extension/io.rb', line 181

def purge
  # Erase IO buffer.
  read_all
  @ionian_buf = ''
end

#read_all(nonblocking: false) ⇒ Object

Read all data in the buffer. An alternative to using #readpartial with a large length. Blocks until data is available unless nonblocking: true. If nonblocking, returns nil if no data available.



63
64
65
66
67
68
69
70
71
 
# File 'lib/ionian/extension/io.rb', line 63

def read_all nonblocking: false
  return nil if nonblocking and not has_data?
  
  # Block until data has arrived.
  data =  readpartial 0xFFFF
  # If there is more data in the buffer, retrieve it nonblocking.
  data += readpartial 0xFFFF while has_data?
  data
end

#read_match(**kwargs) {|match| ... } ⇒ Array<MatchData>

Read matched data from the buffer. This method SHOULD NOT be used if #run_match is used.

Junk data that could exist before a match in the buffer can be accessed with match.pre_match.

Data at the end of the buffer that is not matched can be accessed in the last match with match.post_match. This data remains in the buffer for the next #read_match cycle. This is helpful for protocols like RS232 that do not have packet boundries.

Parameters:

  • kwargs (Hash) —

    a customizable set of options

Options Hash (**kwargs):

  • :timeout (Numeric) — default: nil —

    Timeout in seconds IO::select will block. Blocks indefinitely by default. Set to 0 for nonblocking.

  • :expression (Regexp, String) —

    Override the expression match for this single method call.

  • :notify (Boolean) — default: true —

    Set to false to skip notifying match handler procs.

  • :skip_select (Boolean) — default: false —

    Skip over the IO::select statement. Use if you are calling IO::select ahead of this method.

  • :build_methods (Boolean) — default: true —

    Build accessor methods from named capture groups.

Yield Parameters:

  • match (MatchData) —

    If there are multiple matches, the block is called multiple times.

Returns:

  • (Array<MatchData>) —

    matches. Empty array if no data was received within the timeout period.



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/ionian/extension/io.rb', line 108

def read_match **kwargs, &block
  timeout       = kwargs.fetch :timeout,        @ionian_timeout
  notify        = kwargs.fetch :notify,         true
  skip_select   = kwargs.fetch :skip_select,    @ionian_skip_select
  build_methods = kwargs.fetch :build_methods,  @ionian_build_methods
  
  exp           = kwargs.fetch :expression,     @ionian_expression
  exp           = Regexp.new "(.*?)#{exp}" if exp.is_a? String
  
  unless skip_select
    return [] unless self.has_data? timeout: timeout
  end
  
  @matches = []
  
  # TODO: Implement an option for number of bytes or timeout to throw away
  #       data if no match is found.
  Timeout.timeout(timeout) do
    loop do
      # Read data from the IO buffer until it's empty.
      @ionian_buf << read_all
      break if @ionian_buf =~ exp
    end
  end
  
  while @ionian_buf =~ exp
    @matches << $~   # Match data.
    @ionian_buf = $' # Leave post match data in the buffer.
  end
  
  # Convert named captures to methods.
  if build_methods
    @matches.each do |match|
      match.names
        .map { |name| name.to_sym }
        .each { |symbol|
          match.singleton_class
            .send(:define_method, symbol) { match[symbol] } \
              unless match.respond_to? symbol
        }
    end
  end
  
  # Pass each match to block.
  @matches.each { |match| yield match } if block_given?
  
  # Notify on_match handlers unless the #run_match thread is active.
  @matches.each { |match| notify_match_handlers match } \
    if notify and not @run_match_thread
  
  @matches
end

#register_error_handler {|Exception, self| ... } ⇒ Block Also known as: on_error

Register a block to be called when #run_match raises an error. Method callbacks can be registered with &object.method(:method).

Yields:

  • (Exception, self)

Returns:

  • (Block) —

    a reference to the given block.



226
227
228
229
 
# File 'lib/ionian/extension/io.rb', line 226

def register_error_handler &block
  @ionian_error_handlers << block unless @ionian_error_handlers.include? block
  block
end

#register_match_handler {|MatchData, self| ... } ⇒ Block Also known as: on_match

Register a block to be called when #run_match receives matched data. Method callbacks can be registered with &object.method(:method).

Examples:

registered_block = ionian_socket.register_match_handler { |match| ... }
registered_block = ionian_socket.register_match_handler &my_object.method(:foo)

Yields:

  • (MatchData, self) —

    Regex match.

Returns:

  • (Block) —

    a reference to the given block.



197
198
199
200
 
# File 'lib/ionian/extension/io.rb', line 197

def register_match_handler &block
  @ionian_match_handlers << block unless @ionian_match_handlers.include? block
  block
end

#register_observer(&block) ⇒ Object

Deprecated.

Use #register_match_handler instead.



205
206
207
208
 
# File 'lib/ionian/extension/io.rb', line 205

def register_observer &block
  STDOUT.puts "WARNING: Call to deprecated method: #{__method__}"
  register_match_handler &block
end

#run_match(**kwargs) ⇒ Object

Start a thread that checks for data and notifies match and error handlers. Passes kwargs to #read_match. This method SHOULD NOT be used if #read_match is used.



164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/ionian/extension/io.rb', line 164

def run_match **kwargs
  @run_match_thread ||= Thread.new do
    Thread.current.thread_variable_set :match_thread_running, true
    begin
      while not closed? do
        read_match(**kwargs).each { |match| notify_match_handlers match }
      end
    rescue Exception => e
      notify_error_handlers e
    ensure
      @run_match_thread = nil
    end
  end
end

#unregister_error_handler(&block) ⇒ Object

Unregister a block from being called when a #run_match error is raised.



234
235
236
237
 
# File 'lib/ionian/extension/io.rb', line 234

def unregister_error_handler &block
  @ionian_error_handlers.delete_if { |o| o == block }
  block
end

#unregister_match_handler(&block) ⇒ Object

Unregister a block from being called when matched data is received.



211
212
213
214
 
# File 'lib/ionian/extension/io.rb', line 211

def unregister_match_handler &block
  @ionian_match_handlers.delete_if { |o| o == block }
  block
end

#unregister_observer(&block) ⇒ Object

Deprecated.

Use #unregister_match_handler instead.



217
218
219
220
 
# File 'lib/ionian/extension/io.rb', line 217

def unregister_observer &block
  STDOUT.puts "WARNING: Call to deprecated method: #{__method__}"
  unregister_match_handler &block
end