rumai 3.2.0 → 3.2.1

data/lib/rumai.rb

@@ -1,20 +1,3 @@
-#--
-# Copyright protects this work.
-# See LICENSE file for details.
-#++
-
-require 'rubygems'
-gem 'inochi', '~> 1'
-require 'inochi'
-
-Inochi.init :Rumai,
-  :version => '3.2.0',
-  :release => '2009-11-17',
-  :website => 'http://snk.tuxfamily.org/lib/rumai/',
-  :tagline => 'Ruby interface to the wmii window manager',
-  :develop => {
-    :dfect => nil, # for unit testing
-  }
-
+require 'rumai/inochi'
 require 'rumai/fs'
 require 'rumai/wm'

data/lib/rumai/fs.rb

@@ -1,8 +1,4 @@
 # File system abstractions over the 9P2000 protocol.
-#--
-# Copyright protects this work.
-# See LICENSE file for details.
-#++
 
 require 'rumai/ixp'
 require 'socket'
@@ -15,7 +11,7 @@ module Rumai
     "/tmp/ns.#{ENV['USER']}.#{display[/:\d+/]}/wmii"
 
   begin
-    # We use a single, global connection to wmii's IXP server.
+    # we use a single, global connection to wmii's IXP server
     IXP_AGENT = IXP::Agent.new(UNIXSocket.new(IXP_SOCK_ADDR))
 
   rescue => error
@@ -43,7 +39,7 @@ module Rumai
     ##
     # Returns file statistics about this node.
     #
-    # See Rumai::IXP::Client#stat for details.
+    # @see Rumai::IXP::Agent#stat
     #
     def stat
       IXP_AGENT.stat @path
@@ -81,7 +77,7 @@ module Rumai
     ##
     # Opens this node for I/O access.
     #
-    # See Rumai::IXP::Client#open for details.
+    # @see Rumai::IXP::Agent#open
     #
     def open mode = 'r', &block
       IXP_AGENT.open @path, mode, &block
@@ -90,7 +86,7 @@ module Rumai
     ##
     # Returns the entire content of this node.
     #
-    # See Rumai::IXP::Client#read for details.
+    # @see Rumai::IXP::Agent#read
     #
     def read *args
       IXP_AGENT.read @path, *args
@@ -99,7 +95,9 @@ module Rumai
     ##
     # Invokes the given block for every line in the content of this node.
     #
-    def each_line &block #:yields: line
+    # @yieldparam [String] line
+    #
+    def each_line &block
       open do |file|
         until (chunk = file.read(true)).empty?
           chunk.each_line(&block)
@@ -117,7 +115,7 @@ module Rumai
     ##
     # Creates a file corresponding to this node on the IXP server.
     #
-    # See Rumai::IXP::Client#create for details.
+    # @see Rumai::IXP::Agent#create
     #
     def create *args
       IXP_AGENT.create @path, *args
@@ -198,7 +196,7 @@ module Rumai
   # Both of the above expressions are equivalent.
   #
   module ExportInstanceMethods
-    def self.extended target #:nodoc:
+    def self.extended target # @private
       target.instance_methods(false).each do |meth|
         (class << target; self; end).instance_eval do
           define_method meth do |path, *args|
@@ -209,10 +207,12 @@ module Rumai
     end
   end
 
+  ##
   # NOTE: We use extend() **AFTER** all methods have been defined
   #       in the class so that the ExportInstanceMethods module
   #       can do its magic.  If, instead, we include()d the module
   #       before all methods in the class had been defined, then
   #       the magic would only apply to **SOME** of the methods!
+  #
   Node.extend ExportInstanceMethods
 end

data/lib/rumai/inochi.rb

@@ -0,0 +1,48 @@
+module Rumai
+
+  INSTDIR = File.expand_path('../../..', __FILE__)
+
+  # load inochi configuration
+  inochi_file = __FILE__.sub(/rb$/, 'yaml')
+  begin
+
+    configs = File.open(inochi_file) do |f|
+      require 'yaml'
+      YAML.load_stream(f).documents
+    end
+
+    INOCHI = configs.shift.to_hash
+    INOCHI[:runtime] ||= {}
+    INOCHI[:devtime] ||= {}
+
+    INOCHI2 = (configs.shift || {}).to_hash
+
+  rescue => error
+    error.message.insert 0,
+      "Could not load Inochi configuration file: #{inochi_file.inspect}\n"
+    raise error
+  end
+
+  # make values available as constants
+  INOCHI.each do |param, value|
+    const_set param.to_s.upcase, value
+  end
+
+  def self.inspect
+    "#{PROJECT} #{VERSION} (#{RELEASE})"
+  end
+
+  # establish gem version dependencies
+  if respond_to? :gem
+    [:runtime, :devtime].each do |key|
+      INOCHI[key].each do |gem_name, gem_version|
+        begin
+          gem gem_name, *Array(gem_version)
+        rescue LoadError => error
+          warn "#{inspect} #{key}: #{error}"
+        end
+      end
+    end
+  end
+
+end

data/lib/rumai/inochi.yaml

@@ -0,0 +1,94 @@
+--- # information about your project -----------------------------------------
+
+# Name of your project.
+:project: Rumai
+
+# Name of your project when packaged as a directory.
+:package: rumai
+
+# Name of Ruby module that namespaces your project.
+:library: Rumai
+
+# A short, single-line description of your project.
+:tagline: Ruby interface to the wmii window manager
+
+# Address of your project's published website.
+:website: http://snk.tuxfamily.org/lib/rumai/
+
+# A list of the core developers of your project.
+#
+# :authors:
+#   - An Example <an@example.com>  # with email
+#   - Another Example              # without email
+#
+:authors:
+  - Suraj N. Kurapati <sunaku@gmail.com>
+
+# Number of the current release of your project.
+:version: 3.2.1
+
+# Date of the current release of your project.
+:release: 2010-03-22
+
+# A list of gems required by your project during runtime.
+#
+# :runtime:
+#   # your project needs exactly version 1.2.3 of the "an_example" gem
+#   an_example: 1.2.3
+#
+#   # your project needs at least version 1.2 (but not
+#   # version 1.2.4 or newer) of the "another_example" gem
+#   another_example: [ >= 1.2 , < 1.2.4 ]
+#
+#   # your project needs any version of the "yet_another_example" gem
+#   yet_another_example:
+#
+:runtime:
+
+# A list of gems required by your project during development.
+#
+# :devtime:
+#   # your project needs exactly version 1.2.3 of the "an_example" gem
+#   an_example: 1.2.3
+#
+#   # your project needs at least version 1.2 (but not
+#   # version 1.2.4 or newer) of the "another_example" gem
+#   another_example: [ >= 1.2 , < 1.2.4 ]
+#
+#   # your project needs any version of the "yet_another_example" gem
+#   yet_another_example:
+#
+:devtime:
+  dfect: ~> 2  # for unit testing
+
+--- # parameters for the `inochi` command ------------------------------------
+
+# Location where project documentation will be uploaded by `inochi pub:doc`.
+:pub_doc_target: ~/www/lib/rumai/
+
+# Options for the `rsync` command used to upload your project's documentation.
+:pub_doc_options: --verbose --compress --archive --update --delete
+
+# Path to YAML file containing login information for publishing announcements.
+:pub_ann_logins: ~/.config/inochi/pub_ann_logins.yaml
+
+# Your project's unique identifier in the RAA (Ruby Application Archive).
+:pub_ann_raa_id: rumai
+
+# Arbitrary Ruby code to configure your project's
+# RubyGem, whose Gem::Specification object is made
+# available to the given code in the `gem` variable.
+#
+# :gem_spec_logic: |
+#   # view the Inochi-provided default configuration of your RubyGem
+#   puts gem
+#
+#   # add files that are outside your project directory to your RubyGem
+#   gem.files += FileList['/some/outside/**/*.files']
+#
+#   # omit some files in your project directory from your RubyGem
+#   gem.files.exclude '{some*files,in_your,project/**/directory}'
+#
+#   # and so on...  anything is possible!  use your imagination!
+#
+:gem_spec_logic: |

data/lib/rumai/ixp.rb

@@ -1,8 +1,4 @@
 # An interface to wmii's IXP library for Rumai.
-#--
-# Copyright protects this work.
-# See LICENSE file for details.
-#++
 
 require 'rumai/ixp/message'
 require 'rumai/ixp/transport'

data/lib/rumai/ixp/message.rb

@@ -1,13 +1,7 @@
 # Primitives for the 9P2000 protocol.
 #
 # See http://cm.bell-labs.com/sys/man/5/INDEX.html
-#
 # See http://swtch.com/plan9port/man/man9/
-#
-#--
-# Copyright protects this work.
-# See LICENSE file for details.
-#++
 
 module Rumai
   module IXP
@@ -54,7 +48,7 @@ module Rumai
       ##
       # Allows field values to be initialized via the constructor.
       #
-      # [field_values]
+      # @param field_values
       #   a mapping from field name to field value
       #
       def initialize field_values = {}
@@ -100,7 +94,8 @@ module Rumai
           ##
           # Defines a new field in this Struct.
           #
-          # [args] arguments for Field.new()
+          # @param args
+          #   arguments for {Field.new}
           #
           def field name, format = nil, *args
             klass = Field.factory(format)
@@ -135,8 +130,6 @@ module Rumai
         end
       end
 
-      private
-
       ##
       # A field inside a Struct.
       #
@@ -148,13 +141,13 @@ module Rumai
         attr_reader :name, :format, :counter, :countee
 
         ##
-        # [name]
+        # @param name
         #   unique (among all fields in a struct) name for the field
         #
-        # [format]
+        # @param format
         #   number of bytes, a class, or nil
         #
-        # [counter]
+        # @param [Field] counter
         #   field which counts the length of this field's value
         #
         def initialize name, format = nil, counter = nil
@@ -272,8 +265,6 @@ module Rumai
         end
       end
 
-      #:stopdoc:
-
       ##
       # A field whose value knows how to convert itself to and from 9p.
       #
@@ -310,8 +301,6 @@ module Rumai
           stream.read_9p(4) | (stream.read_9p(4) << BYTE4_BITS)
         end
       end
-
-      #:startdoc:
     end
 
     ##

data/lib/rumai/ixp/transport.rb

@@ -1,8 +1,4 @@
 # Transport layer for 9P2000 protocol.
-#--
-# Copyright protects this work.
-# See LICENSE file for details.
-#++
 
 require 'rumai/ixp/message'
 require 'thread' # for Mutex and Queue
@@ -20,7 +16,7 @@ module Rumai
       attr_reader :msize
 
       ##
-      # [stream]
+      # @param stream
       #   I/O stream on which a 9P2000 server is listening.
       #
       def initialize stream
@@ -105,7 +101,7 @@ module Rumai
       end
 
       ##
-      # Sends the given request (Rumai::IXP::Fcall) and returns
+      # Sends the given request {Rumai::IXP::Fcall} and returns
       # a ticket that you can use later to receive the reply.
       #
       def send request
@@ -119,7 +115,7 @@ module Rumai
 
       ##
       # Returns the reply for the given ticket, which was previously given
-      # to you when you sent the corresponding request (Rumai::IXP::Fcall).
+      # to you when you sent the corresponding request {Rumai::IXP::Fcall}.
       #
       def recv tag
         loop do
@@ -127,17 +123,30 @@ module Rumai
             if @recv_buf.key? tag
               @recv_buf.delete tag
             else
-              # reply was not in the receive buffer, so wait
-              # for the next reply... hoping that it is ours
-              msg = Fcall.from_9p(@stream)
-
-              if msg.tag == tag
-                msg
-              else
-                # we got someone else's reply, so buffer
-                # it (for them to receive) and try again
-                @recv_buf[msg.tag] = msg
-                nil
+              # reply was not in receive buffer, so read
+              # the next reply... hoping that it is ours
+
+              next_reply_available =
+                @recv_buf.empty? || begin
+                  # check (in a non-blocking fashion) if
+                  # the stream has reply for us right now
+                  @stream.ungetc @stream.read_nonblock(1)
+                  true
+                rescue Errno::EAGAIN
+                  # the stream is empty
+                end
+
+              if next_reply_available
+                msg = Fcall.from_9p(@stream)
+
+                if msg.tag == tag
+                  msg
+                else
+                  # we got someone else's reply, so buffer
+                  # it (for them to receive) and try again
+                  @recv_buf[msg.tag] = msg
+                  nil
+                end
               end
             end
           end
@@ -158,7 +167,7 @@ module Rumai
       end
 
       ##
-      # Sends the given request (Rumai::IXP::Fcall) and returns its reply.
+      # Sends the given request {Rumai::IXP::Fcall} and returns its reply.
       #
       def talk request
         tag = send(request)
@@ -190,13 +199,13 @@ module Rumai
       end
 
       ##
-      # Opens the given path for I/O access through a FidStream
+      # Opens the given path for I/O access through a {FidStream}
       # object.  If a block is given, it is invoked with a
-      # FidStream object and the stream is closed afterwards.
+      # {FidStream} object and the stream is closed afterwards.
       #
-      # See File::open in the Ruby documentation.
+      # @see File::open
       #
-      def open path, mode = 'r' # :yields: FidStream
+      def open path, mode = 'r'
         mode = MODES.parse(mode)
 
         # open the file
@@ -224,7 +233,7 @@ module Rumai
       ##
       # Encapsulates I/O access over a file handle (fid).
       #
-      # NOTE: this class is NOT thread safe!
+      # @note this class is NOT thread safe!
       #
       class FidStream
         attr_reader :fid, :stat
@@ -272,17 +281,17 @@ module Rumai
 
         ##
         # Reads some data from this stream at the current position.
+        # If this stream corresponds to a directory, then an Array of
+        # Stat (one for each file in the directory) will be returned.
+        #
+        # @param [Boolean] partial
         #
-        # [partial]
         #   When false, the entire content of
         #   this stream is read and returned.
         #
         #   When true, the maximum amount of content that can fit
         #   inside a single 9P2000 message is read and returned.
         #
-        # If this stream corresponds to a directory, then an Array of
-        # Stat (one for each file in the directory) will be returned.
-        #
         def read partial = false
           raise 'cannot read from a closed stream' if @closed
 
@@ -355,7 +364,7 @@ module Rumai
       # Returns the basenames of all files
       # inside the directory at the given path.
       #
-      # See Dir::entries in the Ruby documentation.
+      # @see Dir::entries
       #
       def entries path
         unless stat(path).directory?
@@ -478,7 +487,7 @@ module Rumai
       ##
       # Invokes the given block with a temporary FID.
       #
-      def with_fid # :yields: fid
+      def with_fid
         begin
           fid = @fid_pool.obtain
           yield fid