i3-ipc 0.0.2 → 0.1.0

data/README.markdown

@@ -10,7 +10,7 @@ RubyGem:
 
     gem install i3-ipc
 
-Old school:
+Old school (for the cli script only):
 
     curl -s http://github.com/badboy/i3-ipc/raw/master/i3-ipc > i3-ipc &&
     chmod 755 i3-ipc &&
@@ -24,15 +24,75 @@ Use
     i3-ipc -t 1 -j
     i3-ipc "exec xterm"
 
+Read the [man-page]() for more information.
+
+Subscribing
+-----------
+
+As of commit [3db4890]() i3 added events.
+For now there's only one event: `workspace`.
+
+According to the documentation:
+> This event is sent when the user switches to a different workspace, when a new workspace is initialized or when a workspace is removed (because the last client vanished).
+
+i3-ipc uses [EventMachine][em] to receive and handle these events.
+
+With `i3-ipc`'s interface and EventMachine as its backend it's rather easy to subscribe to this event notifying:
+
+    I3::IPC.subscribe [:workspace] do |em, type, data|
+      # ...
+    end
+
+There are 3 arguments passed to the block:
+
+* `em` is the instance of the EM::Connection class.
+To send data to the socket, you need to use `em.send_data`.
+* `type` is the received message type.
+This could be one of
+  * MESSAGE_REPLY_COMMAND
+  * MESSAGE_REPLY_COMMAND
+  * MESSAGE_REPLY_COMMAND
+  * EVENT_WORKSPACE #_
+* `data` is the received data, already parsed. 
+
+For example you can use the following code to get the actual focused screen:
+
+    I3::IPC.subscribe [:workspace] do |em, type, data|
+      case type
+      when I3::IPC::MESSAGE_REPLY_GET_WORKSPACES
+        data.each do |e|
+          if e["focused"]
+            puts "focused: %s" % e["name"]
+          else
+            puts "unfocused: %s" % e["name"]
+          end
+        end
+      when I3::IPC::EVENT_WORKSPACE
+        em.send_data I3::IPC.format(I3::IPC::MESSAGE_TYPE_GET_WORKSPACES)
+      end
+    end
+
+A full example of how this can be used for the workspace bar can be found in the `examples` directory.
+
+You can use `EM.stop` to stop the connection.
+
+
+What needs to be done?
+----------------------
+
+* cleanup the subscribtion frontend
+* write tests
+* …
+
 Contributing
 ------------
 
 Once you've made your great commits:
 
-1. [Fork][0] the project.
+1. [Fork]() the project.
 2. Create a topic branch - `git checkout -b my_branch`
 3. Push to your branch - `git push origin my_branch`
-4. Create an [Issue][1] with a link to your branch
+4. Create an [Issue]() with a link to your branch
 5. That's it!
 
 Copyright
@@ -41,5 +101,8 @@ Copyright
 Copyright (c) 2010 Jan-Erik Rediger. See LICENSE for details.
 
 [i3]: http://i3.zekjur.net/
-[0]: http://help.github.com/forking/
-[1]: http://github.com/badboy/i3-ipc/issues
+[manpage]: http://badboy.github.com/i3-ipc/
+[3db4890]: http://code.stapelberg.de/git/i3/commit/?h=next&id=3db4890683e87
+[em]: http://github.com/eventmachine/eventmachine
+[fork]: http://help.github.com/forking/
+[issue]: http://github.com/badboy/i3-ipc/issues

data/Rakefile

@@ -1,27 +1,43 @@
 begin
   require 'mg'
   MG.new("i3-ipc.gemspec")
+
+  desc "Build a gem."
+  task :gem => :package
+
+  desc "Push a new version to Gemcutter and publish docs."
+  task :publish => :gemcutter do
+    require File.dirname(__FILE__) + '/lib/i3-ipc/version'
+
+    system "git tag v#{I3::Version}"
+    sh "git push origin master --tags"
+    sh "git clean -fd"
+    exec "rake pages"
+  end
 rescue LoadError
-  nil
+  warn "mg not available."
+  warn "Install it with: gem i mg"
 end
 
 desc "Build standalone script"
-task :build => [ :standalone, :build_man ]
+task :build => [ "build:standalone", "build:man" ]
 
-desc "Build standalone script"
-task :standalone => :load_i3_ipc do
-  require 'i3-ipc/standalone'
-  I3::Standalone.save('i3-ipc')
+desc "Show i3-ipc manual"
+task :man => "build:man" do
+  exec "man man/i3-ipc.1"
 end
 
-desc "Build i3-ipc manual"
-task :build_man do
-  sh "ronn -br5 --organization=badboy --manual='i3-ipc Manual' man/*.ronn"
-end
+namespace :build do
+  desc "Build i3-ipc manual"
+  task :man do
+    sh "ronn -br5 --organization=badboy --manual='i3-ipc Manual' man/*.ronn"
+  end
 
-desc "Show i3-ipc manual"
-task :man => :build_man do
-  exec "man man/i3-ipc.1"
+  desc "Build standalone script"
+  task :standalone => :load_i3_ipc do
+    require 'i3-ipc/standalone'
+    I3::Standalone.save('i3-ipc')
+  end
 end
 
 task :load_i3_ipc do
@@ -39,7 +55,7 @@ end
 Rake.application.remove_task(:install)
 
 desc "Install standalone script and man pages"
-task :install => :standalone do
+task :install => "build:standalone" do
   prefix = ENV['PREFIX'] || ENV['prefix'] || '/usr/local'
 
   FileUtils.mkdir_p "#{prefix}/bin"
@@ -48,3 +64,28 @@ task :install => :standalone do
   FileUtils.mkdir_p "#{prefix}/share/man/man1"
   FileUtils.cp "man/i3-ipc.1", "#{prefix}/share/man/man1"
 end
+
+desc "Publish to GitHub Pages"
+task :pages => [ "build:man" ] do
+  Dir['man/*.html'].each do |f|
+    cp f, File.basename(f).sub('.html', '.newhtml')
+  end
+
+  `git commit -am 'generated manual'`
+  `git checkout gh-pages`
+
+  Dir['*.newhtml'].each do |f|
+    mv f, "index.html"
+  end
+
+  `git add .`
+  `git commit -m updated`
+  `git push origin gh-pages`
+  `git checkout master`
+  puts :done
+end
+
+desc "fire up IRB console"
+task :console do
+  exec "irb -Ilib -ri3-ipc"
+end

data/lib/i3-ipc.rb

@@ -1,54 +1,77 @@
 require 'socket'
 require 'json'
 require 'i3-ipc/runner'
+require 'i3-ipc/subscription'
 require 'i3-ipc/manpage'
 require 'i3-ipc/version'
 
 module I3
   class IPC
     MAGIC_STRING = "i3-ipc"
+    SOCKET_PATH = "/tmp/i3-ipc.sock"
 
-    class WrongAnswer < RuntimeError; end # :nodoc:
+    MESSAGE_TYPE_COMMAND = 0
+    MESSAGE_TYPE_GET_WORKSPACES = 1
+    MESSAGE_TYPE_SUBSCRIBE = 2
+
+    MESSAGE_REPLY_COMMAND = 0
+    MESSAGE_REPLY_GET_WORKSPACES = 1
+    MESSAGE_REPLY_SUBSCRIBE = 2
+
+    EVENT_MASK = (1 << 31)
+    EVENT_WORKSPACE = (EVENT_MASK | 0)
+
+    class WrongMagicCode < RuntimeError; end # :nodoc:
     class WrongType < RuntimeError; end # :nodoc:
 
     # connects to the given i3 ipc interface
     # @param socket_path String the path to i3's socket
     # @param force_connect Boolean connects to the socket if true
-    def initialize(socket_path="/tmp/i3-ipc.sock", force_connect=false)
+    def initialize(socket_path=SOCKET_PATH, force_connect=false)
       @socket_path = socket_path
       connect if connect
     end
 
-    # send a message to i3
+    # shortcut
+    def self.subscribe(list, socket_path=SOCKET_PATH, &blk)
+      Subscription.subscribe(list, socket_path, &blk)
+    end
+
+    # send a command to i3
     #
-    # the message is a command for i3
+    # the payload is a command for i3
     # (like the commands you can bind to keys in the configuration file)
     # and will be executed directly after receiving it.
     #
-    # returns { "success" => true }
-    def message(payload)
-      write format(0, payload)
-      handle_response 0
+    # returns { "success" => true } for now.
+    # i3 does send this reply without checks
+    def command(payload)
+      write format(MESSAGE_TYPE_COMMAND, payload)
+      handle_response MESSAGE_TYPE_COMMAND
     end
 
     # gets the current workspaces.
-    # the reply will be the JSON-encoded list of workspaces
+    # the reply will be the list of workspaces
     # (see the reply section of i3 docu)
     def get_workspace
-      write format(1)
-      handle_response 1
+      write format(MESSAGE_TYPE_GET_WORKSPACES)
+      handle_response MESSAGE_TYPE_GET_WORKSPACES
     end
 
     # reads the reply from the socket
     # and parse the returned json into a ruby object
     #
-    # throws WrongAnswer when magic word is wrong
+    # throws WrongMagicCode when magic word is wrong
     # throws WrongType if returned type does not match expected
+    #
+    # this is a bit duplicated code
+    # but I don't know a way to read the full send reply
+    # without knowing its length
     def handle_response(type)
       # reads 14 bytes
       # length of "i3-ipc" + 4 bytes length + 4 bytes type
       buffer = @socket.read 14
-      raise WrongAnswer unless buffer[0, ("i3-ipc".length)]
+      raise WrongMagicCode unless buffer[0, (MAGIC_STRING.length)] == MAGIC_STRING
 
       len, recv_type = buffer[6..-1].unpack("LL")
       raise WrongType unless recv_type == type
@@ -60,15 +83,40 @@ module I3
     # format the message
     # a typical message looks like
     #   "i3-ipc" <message length> <message type> <payload>
-    def format(type, payload=nil)
+    def self.format(type, payload=nil)
       size = payload ? payload.to_s.bytes.count : 0
-      msg = "i3-ipc%s" % [size, type].pack("LL")
+      msg = MAGIC_STRING + [size, type].pack("LL")
       msg << payload.to_s if payload
       msg
     end
 
+    def format(type, payload=nil)
+      self.class.format(type, payload)
+    end
+
+    # parse a full ipc response
+    # similar to handle_response,
+    # but parses full reply as received by EventMachine
+    #
+    # returns an Array containing the
+    # reply type and the parsed data
+    def self.parse_response(response)
+      if response[0, (MAGIC_STRING.length)] != MAGIC_STRING
+        raise WrongMagicCode
+      end
+
+      len, recv_type = response[6, 8].unpack("LL")
+
+      answer = response[14, len]
+      [recv_type, ::JSON.parse(answer)]
+    end
+
+    def parse_response(response)
+      self.class.parse_response(response)
+    end
+
     # writes message to the socket
-    # if socket is not connected, it calls conenct
+    # if socket is not connected, it connects first
     def write(msg)
       connect if @socket.nil? || closed?
       @last_write_length = @socket.write msg

data/lib/i3-ipc/standalone.rb

@@ -5,13 +5,13 @@ module I3
     PREAMBLE = <<-preamble
 #!/usr/bin/env ruby
 #
-# This file, gist, is generated code.
+# This file, i3-ipc, is generated code.
 # Please DO NOT EDIT or send patches for it.
 #
 # Please take a look at the source from
 # http://github.com/badboy/i3-ipc
 # and submit patches against the individual files
-# that build gist.
+# that build i3-ipc.
 #
 
 preamble
@@ -33,10 +33,16 @@ preamble
 
       standalone = ''
       standalone << PREAMBLE
+      file_dir = File.expand_path(File.dirname(__FILE__))
+      exclude_files = %w(subscription.rb)
+
+      exclude_file_list = exclude_files.map { |file|
+        File.join(file_dir, file)
+      } + [File.expand_path(__FILE__)]
 
       Dir["#{root}/../**/*.rb"].each do |file|
         # skip standalone.rb
-        next if File.expand_path(file) == File.expand_path(__FILE__)
+        next if exclude_file_list.include?(File.expand_path(file))
 
         File.readlines(file).each do |line|
           next if line =~ /^\s*#/

data/lib/i3-ipc/subscription.rb

@@ -0,0 +1,36 @@
+require 'eventmachine'
+
+module I3
+  module Subscription
+    extend self
+
+    class SubscriptionConnection < EM::Connection
+      def self.connect(subscription_list, socket_path=I3::IPC::SOCKET_PATH, &blk)
+        new_klass = Class.new(self)
+        new_klass.send(:define_method, :initialize) do
+          @subscription_list = subscription_list
+          @handler = blk
+        end
+        EM.connect socket_path, new_klass
+      end
+
+      # send subscription to i3
+      def post_init
+        send_data I3::IPC.format(I3::IPC::MESSAGE_TYPE_SUBSCRIBE,
+                                 @subscription_list.to_json)
+      end
+
+      # receive data, parse it and pass on to the user-defined handler
+      def receive_data(data)
+        @handler.call(self, *I3::IPC.parse_response(data)) if @handler
+      end
+    end
+
+    def subscribe(subscription_list, socket_path=I3::IPC::SOCKET_PATH, &blk)
+      EM.run do
+        SubscriptionConnection.connect(subscription_list,
+                                       socket_path, &blk)
+      end
+    end
+  end
+end

data/lib/i3-ipc/version.rb

@@ -1,3 +1,3 @@
 module I3
-  Version = '0.0.2'
+  Version = '0.1.0'
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 2
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors: 
 - Jan-Erik Rediger
@@ -14,10 +14,23 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-12 00:00:00 +01:00
+date: 2010-03-14 00:00:00 +01:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: eventmachine
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 12
+        - 10
+        version: 0.12.10
+  type: :runtime
+  version_requirements: *id001
 description: "  uses the ipc socket of i3 to send commands or get information directly from the window manager. Useful for scripting the window manager.'\n"
 email: badboy@archlinux.us
 executables: 
@@ -30,6 +43,7 @@ files:
 - README.markdown
 - Rakefile
 - LICENSE
+- lib/i3-ipc/subscription.rb
 - lib/i3-ipc/manpage.rb
 - lib/i3-ipc/standalone.rb
 - lib/i3-ipc/version.rb