i3ipc 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e40ae80557aa74e152aa616ae813744d8b755586
-  data.tar.gz: a5f833254c367b6d9bc4b4bdecd8303020388194
+  metadata.gz: d1656014a13ed6678e5efba71d74c72e7d910906
+  data.tar.gz: c41b56ab703cf2bc2322ed83218aa7f696e2552f
 SHA512:
-  metadata.gz: 4af0b717ee2d06d19d858694305c21eef45c2ef0b1e74427acafd18c32c9db0835694c9c84fadc5456d1a55bb51a7b1e5664d58f50f564ba4aed75095a1769de
-  data.tar.gz: 38fef1144589bacb4c4b7edcae7427f435aeaa95fca85a0b45789f4805f2e9b21deade91c6f396096bf4e201a8cd0603b0207e21dc25787f0a50f10113403208
+  metadata.gz: 38f1d719f5c32f6ebd335d376481e76cb6be67ecba380af9753792654b05cf6adeecdb54847089fbf91372c3994291861d1cd49d22e9e660d3c62a9f1a3b5d69
+  data.tar.gz: 136c448a42f39671740959c11c5beca1cd5f16115f2e983b590e6d60dbfd9ee480decde1f66b2c3fa4376ac708b5abe771fe055fd10f0ee2a676ba1adc2f045f

data/README.md

@@ -17,7 +17,7 @@ An improved Ruby library to control [i3wm](http://i3wm.org/).
 
 i3's interprocess communication (or [ipc](http://i3wm.org/docs/ipc.html)) is the interface i3 wm uses to receive commands from the clients. It also features a publish/subscribe mechanism for notifying interested parties of window manager events.
 
-This gem will be useful for example for controlling i3 windows manager or to get various information like the current workspaces or to implemennt external workspace bar in `Ruby` language.
+This gem will be useful for example for controlling i3 windows manager or to get various information like the current workspaces or to implement external workspace bar in `Ruby` language.
 
 Inspired by [i3ipc-python](https://github.com/acrisci/i3ipc-python), [i3ipc-gjs](https://github.com/acrisci/i3ipc-gjs), [i3ipc-lua](https://github.com/acrisci/i3ipc-lua) and reworked mainly from [i3-ipc](https://github.com/badboy/i3-ipc) (thanks to [@badboy](https://github.com/badboy) for this gem).
 
@@ -98,7 +98,25 @@ Reply consists of a list of workspaces. Each workspace has some properties:
 
 ### Subscribe
 
-To be done (not implemented yet)
+Takes an [event](http://i3wm.org/docs/ipc.html#_available_events) and
+a Proc object. The Proc object will be called with i3's response
+whenever i3 generates the specified event. `subscribe` returns a
+Thread; the block will execute in this thread until the thread is
+killed.
+
+```ruby
+block = Proc.new do |reply|
+  if reply.change == 'title'
+    puts "title changed for window #{reply.container.name}"
+  end
+end
+
+pid = i3.subscribe('window', block)
+pid.join
+```
+
+It is recommended to use separate `Connection`s for each subscription,
+since replies to subscription events may be sent by i3 at any time.
 
 ### Outputs
 

data/lib/i3ipc/connection.rb

@@ -2,11 +2,23 @@ require 'i3ipc/protocol'
 require 'i3ipc/reply'
 
 module I3Ipc
+  # Throws when subscribing to an invalid event. Valid events are
+  # listed in function event_number().
+  class WrongEvent < RuntimeError
+    def initialize(event_name)
+      @event_name = event_name
+    end
+
+    def message
+      %Q{Tried to subscribe to invalid event type '#{@event_name}'}
+    end
+  end
+
   # Entry point for communication with i3-ipc.
   # Able to send/receive messages and convert
   # responses.
   #
-  # Usage example:
+  # @example
   #   con = Connection.new
   #   p con.version.human_readable         # => 4.10.2 (2015-0...
   #   p con.command('focus left').success? # => true
@@ -17,14 +29,14 @@ module I3Ipc
 
     def initialize(connect = true)
       @protocol = Protocol.new
-      connect && @protocol.connect
+      open
     end
 
-    def connect
+    def open
       @protocol.connect
     end
 
-    def disconnect
+    def close
       @protocol.disconnect
     end
 
@@ -36,6 +48,25 @@ module I3Ipc
       reply_for(1)
     end
 
+    def subscribe(event, block)
+      event_number = event_number(event)
+
+      # Send subscription request
+      @protocol.send(2, [event])
+
+      reply = Reply.parse(@protocol.receive 2)
+      raise WrongEvent.new(event) unless reply.success?
+
+      pid = Thread.new do
+        while true
+          reply = Reply.parse(@protocol.receive_event event_number)
+          block.call(reply)
+        end
+      end
+
+      pid
+    end
+
     def outputs
       reply_for(3)
     end
@@ -58,9 +89,23 @@ module I3Ipc
 
     private
 
-    def reply_for(type, message = nil)
+    def reply_for(type, message = nil, events=nil)
       @protocol.send(type, message)
+
       Reply.parse(@protocol.receive type)
     end
+
+    def event_number(event)
+      case event
+      when 'workspace'         then 0
+      when 'output'            then 1
+      when 'mode'              then 2
+      when 'window'            then 3
+      when 'barconfig_update'  then 4
+      when 'binding'           then 5
+      else raise WrongEvent.new(event)
+      end
+    end
+
   end
 end

data/lib/i3ipc/protocol.rb

@@ -2,16 +2,16 @@ require 'socket'
 
 module I3Ipc
   # Communication interface with i3-ipc.
-  #
   # Can connect to i3-ipc socket, disconnect, send and receive messages.
   #
-  # Usage example:
+  # For i3-ipc interface details refer to https://i3wm.org/docs/ipc.html.
+  #
+  # @example
   #   protocol = Protocol.new
   #   protocol.send(7)
   #   puts protocol.receive
   #   protocol.disconnect
   #
-  # For i3-ipc interface details refer to https://i3wm.org/docs/ipc.html.
   class Protocol
     # Magic string for i3-ipc protocol to ensure the integrity of messages.
     MAGIC_STRING = 'i3-ipc'
@@ -49,7 +49,7 @@ module I3Ipc
       @socketpath = socketpath ? socketpath : get_socketpath
     end
 
-    # Connects to i3-ipc server socket using Socket::UNIXSocket.
+    # Connects to i3-ipc server socket using {::UNIXSocket}.
     # Does nothing if already connected.
     def connect
       @socket = UNIXSocket.new(@socketpath) unless @socket
@@ -63,12 +63,10 @@ module I3Ipc
     end
 
     # Sends packed message to i3-ipc server socket.
+    # @param [Integer] type type of the message.
+    # @param [String] payload message payload.
     #
-    # Throws:
-    # * NotConnected if protocol is not connected.
-    #
-    # +type+: type of the message.
-    # +payload+: payload of the message
+    # @raise [NotConnected] if protocol is not connected.
     def send(type, payload = nil)
       check_connected
       @socket.write(pack(type, payload))
@@ -76,12 +74,13 @@ module I3Ipc
 
     # Receives message from i3-ipc server socket.
     #
-    # Throws:
-    # * NotConnected if protocol is not connected.
-    # * WrongMagicString if got message with not expected magic string.
-    # * WrongType if got message with not expected magic type.
+    # @param [Integer] type expected type of the message.
+    #
+    # @return [String] unpacked response from i3 server.
     #
-    # +type+: expected type of the message.
+    # @raise [NotConnected] if protocol is not connected.
+    # @raise [WrongMagicString] if got message with wrong magic string.
+    # @raise [WrongType] if got message with not expected type.
     def receive(type = nil)
       check_connected
       # length of "i3-ipc" + 4 bytes length + 4 bytes type
@@ -94,16 +93,42 @@ module I3Ipc
       @socket.read(len)
     end
 
+    # Receives event from i3-ipc server socket.
+    #
+    # @param [Integer] type expected type of the message.
+    #
+    # @return [String] unpacked response from i3 server.
+    #
+    # @raise [NotConnected] if protocol is not connected.
+    # @raise [WrongMagicString] if got message with wrong magic string.
+    # @raise [WrongType] if got message with not expected type.
+    def receive_event(type = nil)
+      check_connected
+      # length of "i3-ipc" + 4 bytes length + 4 bytes type
+      data = @socket.read 14
+      magic, len, recv_type = unpack_header(data)
+
+      # Strip highest bit
+      recv_type = recv_type & 2147483647
+
+      raise WrongMagicString.new(magic) unless MAGIC_STRING.eql? magic
+      type && (raise WrongType.new(type, recv_type) unless type == recv_type)
+
+      @socket.read(len)
+    end
+
     private
 
     # Packs the message.
     # A typical message looks like:
+    # @example
     #   <header><payload>
     # where a header is:
+    # @example
     #   <magic string><message length><message type>
     #
-    # +type+: type of the message
-    # +payload+: patload of the message
+    # @param [Integer] type type of the message.
+    # @param [String] payload payload of the message.
     def pack(type, payload=nil)
       size = payload ? payload.to_s.bytes.count : 0
       msg = MAGIC_STRING + [size, type].pack("LL")
@@ -113,9 +138,10 @@ module I3Ipc
 
     # Unpacks the header.
     # A typical header looks like:
+    # @example
     #   <magic_string><message length><message type>
     #
-    # +data+: data to be unpacked.
+    # @param [String] data: data to be unpacked.
     def unpack_header(data)
       struct_header_len = MAGIC_STRING.size
       magic_message = data[0, struct_header_len]

data/lib/i3ipc/reply.rb

@@ -3,12 +3,10 @@ require 'json'
 module I3Ipc
   # Wrapper for reply from i3-ipc.
   #
-  # Represents response from i3 as object tree.
-  #
   # Able to parse Numeric, String, TrueClass, FalseClass,
-  # Array, Hash from passed JSON string.
+  # Array, Hash from passed string in json format.
   #
-  # For example:
+  # @example
   #  response = Reply.parse(
   #   %Q{
   #      {
@@ -40,17 +38,18 @@ module I3Ipc
 
     # Parses response from I3-ipc protocol.
     #
-    # Returns Reply object with dynamically accessed values.
+    # @param [String] response response from i3 in json format.
     #
-    # +response+: string, that represents response from i3 in json format.
+    # @return [Reply] object with dynamically accessed values.
     def self.parse(response)
       parse_data JSON.parse(response)
     end
 
-    # Returns false if this reply represents and error
-    # from i3-ipc protocol. Otherwise returns true, which
-    # meens that request is successful and reply has some
-    # data.
+    # Indicates whether this reply success or not.
+    #
+    # @return false if this reply represents and error from i3-ipc protocol.
+    #   Otherwise returns true, which means that request is successful and
+    #   reply has some data.
     def success?
       not self.respond_to? :error
     end

data/lib/i3ipc/version.rb

@@ -1,3 +1,3 @@
 module I3ipc
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: i3ipc
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Vitalii Elengaupt
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-23 00:00:00.000000000 Z
+date: 2015-12-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -101,7 +101,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.6
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Interprocess communication with i3 wm