rumai 2.0.2 → 2.1.0

data/lib/rumai.rb

@@ -1,12 +1,20 @@
+#--
+# Copyright 2008 Suraj N. Kurapati
+# See the LICENSE file for details.
+#++
+
 require 'rubygems'
-gem 'inochi', '~> 0'
+gem 'inochi', '~> 1'
 require 'inochi'
 
 Inochi.init :Rumai,
-  :version => '2.0.2',
-  :release => '2009-02-26',
-  :website => 'http://snk.tuxfamily.org/lib/rumai',
-  :tagline => 'Ruby interface to the wmii window manager'
+  :version => '2.1.0',
+  :release => '2009-05-09',
+  :website => 'http://snk.tuxfamily.org/lib/rumai/',
+  :tagline => 'Ruby interface to the wmii window manager',
+  :develop => {
+    :dfect => nil, # for unit testing
+  }
 
 require 'rumai/fs'
 require 'rumai/wm'

data/lib/rumai/fs.rb

@@ -1,4 +1,8 @@
 # File system abstractions over the 9P2000 protocol.
+#--
+# Copyright 2006 Suraj N. Kurapati
+# See the LICENSE file for details.
+#++
 
 require 'rumai/ixp'
 require 'socket'
@@ -6,6 +10,7 @@ require 'socket'
 module Rumai
   # address of the IXP server socket on this machine
   display = ENV['DISPLAY'] || ':0.0'
+
   IXP_SOCK_ADDR = ENV['WMII_ADDRESS'].sub(/.*!/, '') rescue
     "/tmp/ns.#{ENV['USER']}.#{display[/:\d+/]}/wmii"
 
@@ -13,33 +18,40 @@ module Rumai
     # We use a single, global connection to wmii's IXP server.
     IXP_AGENT = IXP::Agent.new UNIXSocket.new(IXP_SOCK_ADDR)
 
-  rescue
-    $!.message << %{
+  rescue => error
+    error.message << %{
       Ensure that (1) the WMII_ADDRESS environment variable is set and that (2)
       it correctly specifies the filesystem path of wmii's IXP socket file,
       which is typically located at "/tmp/ns.$USER.:$DISPLAY/wmii".
     }.gsub(/^ +/, '').gsub(/\A|\z/, "\n")
 
-    raise
+    raise error
   end
 
+  ##
   # An entry in the IXP file system.
+  #
   class Node
     @@cache = Hash.new {|h,k| h[k] = Node.new(k) }
 
     attr_reader :path
 
-    def initialize aPath
-      @path = aPath.to_s.squeeze('/')
+    def initialize path
+      @path = path.to_s.squeeze('/')
     end
 
+    ##
     # Returns file statistics about this node.
+    #
     # See Rumai::IXP::Client#stat for details.
+    #
     def stat
       IXP_AGENT.stat @path
     end
 
+    ##
     # Tests if this node exists on the IXP server.
+    #
     def exist?
       begin
         true if stat
@@ -48,91 +60,122 @@ module Rumai
       end
     end
 
+    ##
     # Tests if this node is a directory.
+    #
     def directory?
       exist? and stat.directory?
     end
 
+    ##
     # Returns the names of all files in this directory.
+    #
     def entries
       IXP_AGENT.entries @path rescue []
     end
 
+    ##
     # Opens this node for I/O access.
+    #
     # See Rumai::IXP::Client#open for details.
-    def open aMode = 'r', &aBlock
-      IXP_AGENT.open @path, aMode, &aBlock
+    #
+    def open mode = 'r', &block
+      IXP_AGENT.open @path, mode, &block
     end
 
+    ##
     # Returns the entire content of this node.
+    #
     # See Rumai::IXP::Client#read for details.
-    def read *aArgs
-      IXP_AGENT.read @path, *aArgs
+    #
+    def read *args
+      IXP_AGENT.read @path, *args
     end
 
+    ##
     # Invokes the given block for every line in the content of this node.
-    def each_line &aBlock #:yields: line
+    #
+    def each_line &block #:yields: line
       open do |file|
         until (chunk = file.read(true)).empty?
-          chunk.each_line(&aBlock)
+          chunk.each_line(&block)
         end
       end
     end
 
+    ##
     # Writes the given content to this node.
-    def write aContent
-      IXP_AGENT.write @path, aContent
+    #
+    def write content
+      IXP_AGENT.write @path, content
     end
 
+    ##
     # Creates a file corresponding to this node on the IXP server.
+    #
     # See Rumai::IXP::Client#create for details.
-    def create *aArgs
-      IXP_AGENT.create @path, *aArgs
+    #
+    def create *args
+      IXP_AGENT.create @path, *args
     end
 
+    ##
     # Deletes the file corresponding to this node on the IXP server.
+    #
     def remove
       IXP_AGENT.remove @path
     end
 
+    ##
     # Returns the given sub-path as a Node object.
-    def [] aSubPath
-      @@cache[ File.join(@path, aSubPath.to_s) ]
+    #
+    def [] sub_path
+      @@cache[ File.join(@path, sub_path.to_s) ]
     end
 
+    ##
     # Returns the parent node of this node.
+    #
     def parent
       @@cache[ File.dirname(@path) ]
     end
 
+    ##
     # Returns all child nodes of this node.
+    #
     def children
       entries.map! {|c| self[c] }
     end
 
     include Enumerable
+
+      ##
       # Iterates through each child of this directory.
-      def each &aBlock
-        children.each(&aBlock)
+      #
+      def each &block
+        children.each(&block)
       end
 
+    ##
     # Deletes all child nodes.
+    #
     def clear
       children.each do |c|
         c.remove
       end
     end
 
+    ##
     # Provides access to child nodes through method calls.
     #
     # :call-seq: node.child -> Node
     #
-    def method_missing aMeth, *aArgs
-      child = self[aMeth]
+    def method_missing meth, *args
+      child = self[meth]
 
       # speed up future accesses
       (class << self; self; end).instance_eval do
-        define_method aMeth do
+        define_method meth do
           child
         end
       end
@@ -141,6 +184,7 @@ module Rumai
     end
   end
 
+  ##
   # Makes instance methods accessible through class
   # methods. This is done to emulate the File class:
   #
@@ -149,10 +193,10 @@ module Rumai
   #
   # Both of the above expressions are equivalent.
   #
-  module ExportInstMethods
-    def self.extended aTarget #:nodoc:
-      aTarget.instance_methods(false).each do |meth|
-        (class << aTarget; self; end).instance_eval do
+  module ExportInstanceMethods
+    def self.extended target #:nodoc:
+      target.instance_methods(false).each do |meth|
+        (class << target; self; end).instance_eval do
           define_method meth do |path, *args|
             new(path).__send__(meth, *args)
           end
@@ -165,5 +209,5 @@ module Rumai
   # that the Externalize* module can do its magic.  If we include()d
   # the module instead before all methods in the class have been
   # defined, then the magic would only apply to SOME of the methods!
-  Node.extend ExportInstMethods
+  Node.extend ExportInstanceMethods
 end

data/lib/rumai/ixp.rb

@@ -1,4 +1,8 @@
 # An interface to wmii's IXP library for Rumai.
+#--
+# Copyright 2007 Suraj N. Kurapati
+# See the LICENSE file for details.
+#++
 
 require 'rumai/ixp/message'
 require 'rumai/ixp/transport'

data/lib/rumai/ixp/message.rb

@@ -1,8 +1,13 @@
 # Primitives for the 9P2000 protocol.
 #
 # See http://cm.bell-labs.com/sys/man/5/INDEX.html
+#
 # See http://swtch.com/plan9port/man/man9/
 #
+#--
+# Copyright 2007 Suraj N. Kurapati
+# See the LICENSE file for details.
+#++
 
 module Rumai
   module IXP
@@ -19,49 +24,67 @@ module Rumai
       const_set "BYTE#{bytes}_MASK", mask
     end
 
+    ##
     # A 9P2000 byte stream.
+    #
     module Stream
       # uchar, ushort, uint32 (all of them little-endian)
       PACKING_FLAGS = { 1 => 'C', 2 => 'v', 4 => 'V' }.freeze
 
+      ##
       # Unpacks the given number of bytes from this 9P2000 byte stream.
-      def read_9p aNumBytes
-        read(aNumBytes).unpack(PACKING_FLAGS[aNumBytes])[0]
+      #
+      def read_9p num_bytes
+        read(num_bytes).unpack(PACKING_FLAGS[num_bytes])[0]
       end
     end
 
+    ##
     # A common container for exceptions concerning IXP.
+    #
     class Error < StandardError
     end
 
+    ##
     # A serializable 9P2000 data structure.
+    #
     module Struct
       attr_reader :fields
 
+      ##
       # Allows field values to be initialized via the constructor.
-      # aFieldValues:: a mapping from field name to field value
-      def initialize aFieldValues = {}
+      #
+      # [field_values]
+      #   a mapping from field name to field value
+      #
+      def initialize field_values = {}
         @fields = self.class.fields
-        @values = aFieldValues
+        @values = field_values
       end
 
+      ##
       # Transforms this object into a string of 9P2000 bytes.
+      #
       def to_9p
         @fields.inject('') {|s,f| s << f.to_9p(@values) }
       end
 
+      ##
       # Populates this object with information
       # from the given 9P2000 byte stream.
-      def load_9p aStream
+      #
+      def load_9p stream
         @fields.each do |f|
-          f.load_9p aStream, @values
+          f.load_9p stream, @values
         end
       end
 
+      ##
       # Provides a convenient DSL (for defining fields)
       # to all objects which *include* this module.
-      def self.included aTarget
-        class << aTarget
+      #
+      def self.included target
+        class << target
           # Returns a list of fields which compose this Struct.
           def fields
             @fields ||=
@@ -72,11 +95,14 @@ module Rumai
               end
           end
 
+          ##
           # Defines a new field in this Struct.
-          # aArgs:: arguments for Field.new()
-          def field aName, aFormat = nil, *aArgs
-            c = Field.factory(aFormat)
-            f = c.new(aName.to_sym, aFormat, *aArgs)
+          #
+          # [args] arguments for Field.new()
+          #
+          def field name, format = nil, *args
+            c = Field.factory(format)
+            f = c.new(name.to_sym, format, *args)
             fields << f # register field as being part of this structure
 
             # provide accessor methods to field values
@@ -85,19 +111,21 @@ module Rumai
                 @values[#{f.name.inspect}]
               end
 
-              def #{f.name}= aValue
-                @values[#{f.name.inspect}] = aValue
+              def #{f.name}= value
+                @values[#{f.name.inspect}] = value
               end
             }
 
             return f
           end
 
+          ##
           # Creates a new instance of this class from the
           # given 9P2000 byte stream and returns the instance.
-          def from_9p aStream, aMsgClass = self
-            msg = aMsgClass.new
-            msg.load_9p(aStream)
+          #
+          def from_9p stream, msg_class = self
+            msg = msg_class.new
+            msg.load_9p(stream)
             msg
           end
         end
@@ -105,48 +133,65 @@ module Rumai
 
       private
 
-      # A field inside a Struct.  A field's value is considered to be:
+      ##
+      # A field inside a Struct.
+      #
+      # A field's value is considered to be either:
       # * array of format when <code>counter && format.is_a? Class</code>
       # * raw byte string when <code>counter && format.nil?</code>
+      #
       class Field
         attr_reader :name, :format, :counter, :countee
 
-        # aName:: unique (among all fields in a struct) name for the field
-        # aFormat:: number of bytes, a class, or nil
-        # aCounter:: field which counts the length of this field's value
-        def initialize aName, aFormat = nil, aCounter = nil
-          @name = aName
-          @format = aFormat
+        ##
+        # [name]
+        #   unique (among all fields in a struct) name for the field
+        #
+        # [format]
+        #   number of bytes, a class, or nil
+        #
+        # [counter]
+        #   field which counts the length of this field's value
+        #
+        def initialize name, format = nil, counter = nil
+          @name = name
+          @format = format
           @countee = nil
-          self.counter = aCounter
+          self.counter = counter
         end
 
+        ##
         # Sets the counter for this field (implying that the
         # length of this field is counted by the given field).
-        def counter= aField
-          if @counter = aField
+        #
+        def counter= field
+          if @counter = field
             extend CounteeField
             @counter.countee = self
           end
         end
 
+        ##
         # Sets the countee for this field (implying that
         # this field counts the length of the given field).
-        def countee= aField
-          if @countee = aField
+        #
+        def countee= field
+          if @countee = field
             extend CounterField
           end
         end
 
+        ##
         # Returns a Field class that best represents the given format.
-        def self.factory aFormat
-          if aFormat == String
+        #
+        def self.factory format
+          if format == String
             StringField
 
-          elsif aFormat.is_a? Class
+          elsif format.is_a? Class
             ClassField
 
-          elsif aFormat == 8
+          elsif format == 8
             Integer8Field
 
           else
@@ -154,42 +199,54 @@ module Rumai
           end
         end
 
+        ##
         # Transforms this object into a string of 9P2000 bytes.
-        def to_9p aFieldValues
-          value_to_9p aFieldValues[@name]
+        #
+        def to_9p field_values
+          value_to_9p field_values[@name]
         end
 
+        ##
         # Populates this object with information
         # taken from the given 9P2000 byte stream.
-        def load_9p aStream, aFieldValues
-          aFieldValues[@name] = value_from_9p aStream
+        #
+        def load_9p stream, field_values
+          field_values[@name] = value_from_9p stream
         end
 
         private
 
+        ##
         # Converts the given value, according to the format
         # of this field, into a string of 9P2000 bytes.
-        def value_to_9p aValue
-          aValue.to_i.to_9p @format.to_i
+        #
+        def value_to_9p value
+          value.to_i.to_9p @format.to_i
         end
 
+        ##
         # Parses a value, according to the format of
         # this field, from the given 9P2000 byte stream.
-        def value_from_9p aStream
-          aStream.read_9p @format.to_i
+        #
+        def value_from_9p stream
+          stream.read_9p @format.to_i
         end
 
+        ##
         # Methods for a field that counts the length of another field.
+        #
         module CounterField
-          def to_9p aFieldValues
-            value_to_9p aFieldValues[@countee.name].length
+          def to_9p field_values
+            value_to_9p field_values[@countee.name].length
           end
         end
 
+        ##
         # Methods for a field whose length is counted by another field.
+        #
         module CounteeField
-          def to_9p aFieldValues
-            value = aFieldValues[@name]
+          def to_9p field_values
+            value = field_values[@name]
 
             if @format
               value.map {|v| value_to_9p v}.join
@@ -198,54 +255,66 @@ module Rumai
             end
           end
 
-          def load_9p aStream, aFieldValues
-            count = aFieldValues[@counter.name].to_i
+          def load_9p stream, field_values
+            count = field_values[@counter.name].to_i
 
-            aFieldValues[@name] =
+            field_values[@name] =
               if @format
-                Array.new(count) { value_from_9p aStream }
+                Array.new(count) { value_from_9p stream }
               else
-                aStream.read(count) # raw byte sequence
+                stream.read(count) # raw byte sequence
               end
           end
         end
       end
 
+      #:stopdoc:
+
+      ##
       # A field whose value knows how to convert itself to and from 9p.
-      class ClassField < Field #:nodoc:
-        def value_to_9p aValue
-          aValue.to_9p
+      #
+      class ClassField < Field
+        def value_to_9p value
+          value.to_9p
         end
 
-        def value_from_9p aStream
-          @format.from_9p aStream
+        def value_from_9p stream
+          @format.from_9p stream
         end
       end
 
+      ##
       # A field whose value is a string.
-      class StringField < ClassField #:nodoc:
-        def value_to_9p aValue
-          aValue.to_s.to_9p
+      #
+      class StringField < ClassField
+        def value_to_9p value
+          value.to_s.to_9p
         end
       end
 
+      ##
       # A field whose value is a 8-byte integer.
-      class Integer8Field < Field #:nodoc:
-        def value_to_9p aValue
-          v = aValue.to_i
+      #
+      class Integer8Field < Field
+        def value_to_9p value
+          v = value.to_i
           (BYTE4_MASK & v).to_9p(4) <<               # lower bytes
           (BYTE4_MASK & (v >> BYTE4_BITS)).to_9p(4)  # higher bytes
         end
 
-        def value_from_9p aStream
-          aStream.read_9p(4) | (aStream.read_9p(4) << BYTE4_BITS)
+        def value_from_9p stream
+          stream.read_9p(4) | (stream.read_9p(4) << BYTE4_BITS)
         end
       end
+
+      #:startdoc:
     end
 
+    ##
     # Holds information about a file being accessed on a 9P2000 server.
     #
     # See http://cm.bell-labs.com/magic/man2html/5/intro
+    #
     class Qid
       include Struct
 
@@ -265,9 +334,11 @@ module Rumai
       QTFILE      = 0x00       # type bits for plain file
     end
 
+    ##
     # Holds information about a file on a 9P2000 server.
     #
     # See http://cm.bell-labs.com/magic/man2html/5/stat
+    #
     class Stat
       include Struct
 
@@ -301,16 +372,20 @@ module Rumai
       DMWRITE     = 0x2        # mode bit for write permission
       DMEXEC      = 0x1        # mode bit for execute permission
 
+      ##
       # Tests if this file is a directory.
+      #
       def directory?
         mode & DMDIR > 0
       end
     end
 
+    ##
     # Fcall is the basic unit of communication in the 9P2000 protocol.
     # It is analogous to a "packet" in the Internetwork Protocol (IP).
     #
     # See http://cm.bell-labs.com/magic/man2html/2/fcall
+    #
     class Fcall
       include Struct
 
@@ -322,7 +397,9 @@ module Rumai
       #
       field   :tag  , 2
 
+      ##
       # Transforms this object into a string of 9P2000 bytes.
+      #
       def to_9p
         data = type.to_9p(1) << super
         size = (data.length + 4).to_9p(4)
@@ -331,19 +408,22 @@ module Rumai
 
       class << self
         alias __from_9p__ from_9p
-      end
-
-      # Creates a new instance of this class from the
-      # given 9P2000 byte stream and returns the instance.
-      def self.from_9p aStream
-        size = aStream.read_9p(4)
-        type = aStream.read_9p(1)
+        undef from_9p
+
+        ##
+        # Creates a new instance of this class from the
+        # given 9P2000 byte stream and returns the instance.
+        #
+        def from_9p stream
+          size = stream.read_9p(4)
+          type = stream.read_9p(1)
+
+          unless fcall = TYPE_TO_CLASS[type]
+            raise Error, "illegal fcall type: #{type}"
+          end
 
-        unless fcall = TYPE_TO_CLASS[type]
-          raise Error, "illegal fcall type: #{type}"
+          __from_9p__ stream, fcall
         end
-
-        __from_9p__ aStream, fcall
       end
 
       NOTAG = BYTE2_MASK # (ushort)
@@ -531,6 +611,9 @@ module Rumai
     class Rwstat < Fcall
     end
 
+    ##
+    # A remote function call (fcall).
+    #
     class Fcall
       CLASS_TO_TYPE = {
         Tversion => 100,
@@ -565,12 +648,16 @@ module Rumai
 
       TYPE_TO_CLASS = CLASS_TO_TYPE.invert.freeze
 
+      ##
       # Returns the value of the 'type' field for this fcall.
+      #
       def self.type
         CLASS_TO_TYPE[self]
       end
 
+      ##
       # Returns the value of the 'type' field for this fcall.
+      #
       def type
         self.class.type
       end
@@ -579,36 +666,46 @@ module Rumai
 end
 
 class Integer
+  ##
   # Transforms this object into a string of 9P2000 bytes.
-  def to_9p aNumBytes
-    [self].pack Rumai::IXP::Stream::PACKING_FLAGS[aNumBytes]
+  #
+  def to_9p num_bytes
+    [self].pack Rumai::IXP::Stream::PACKING_FLAGS[num_bytes]
   end
 end
 
 # count[2] s[count]
 class String
+  ##
   # Transforms this object into a string of 9P2000 bytes.
+  #
   def to_9p
     length.to_9p(2) << self[0, Rumai::IXP::BYTE2_MASK]
   end
 
+  ##
   # Creates a new instance of this class from the
   # given 9P2000 byte stream and returns the instance.
-  def self.from_9p aStream
-    aStream.read(aStream.read_9p(2))
+  #
+  def self.from_9p stream
+    stream.read(stream.read_9p(2))
   end
 end
 
 class Time
+  ##
   # Transforms this object into a string of 9P2000 bytes.
+  #
   def to_9p
     to_i.to_9p(4)
   end
 
+  ##
   # Creates a new instance of this class from the
   # given 9P2000 byte stream and returns the instance.
-  def self.from_9p aStream
-    at aStream.read_9p(4)
+  #
+  def self.from_9p stream
+    at stream.read_9p(4)
   end
 end