rstyx 0.3.1 → 0.3.2

data/lib/rstyx/messages.rb

@@ -24,7 +24,7 @@
 # Copyright:: Copyright (c) 2005,2006 Rafael R. Sevilla
 # License:: GNU Lesser General Public License
 #
-# $Id: messages.rb 229 2007-08-10 08:03:58Z dido $
+# $Id: messages.rb 242 2007-09-13 08:05:57Z dido $
 #
 
 require 'rstyx/errors'
@@ -36,16 +36,25 @@ module RStyx
     # Class representing the server's view of a file.
     #
     class Qid
-      attr_accessor :qtype, :version, :path
+      ##
+      # The type of the file (directory, etc.) represented as a bit vector
+      # corresponding to the high 8 bits of the file's mode word.
+      attr_accessor :qtype
+      ##
+      # Version number for given path
+      attr_accessor :version
+      ##
+      # The file server's unique identification for the file
+      attr_accessor :path
 
       QID_LENGTH = 13           # size of a Qid
 
       ##
       # Create a new Qid object.
       #
-      # +type+:: [Fixnum] the type of file (directory, append only file, etc.)
-      # +version+:: [Fixnum] the version number of the file
-      # +path+:: [Fixnum] a 64-bit integer that should be unique among all
+      # _type_:: [Fixnum] the type of file (directory, append only file, etc.)
+      # _version_:: [Fixnum] the version number of the file
+      # _path_:: [Fixnum] a 64-bit integer that should be unique among all
       #          files being served
       #
       def initialize(type, version, path)
@@ -55,7 +64,7 @@ module RStyx
       end
 
       ##
-      # Equality
+      # Test if two qid's are the same.
       #
       def ==(x)
         return(self.to_bytes == x.to_bytes)
@@ -75,7 +84,7 @@ module RStyx
       ##
       # Decode a serialized Qid from its byte string representation
       #
-      # +msgbytes+:: [String] the byte string representation of the qid
+      # _msgbytes_:: [String] the byte string representation of the qid
       # return value:: [Qid] the Qid represented by the byte string.
       # raises:: StyxException if the string cannot be decoded as a Qid
       #
@@ -105,10 +114,47 @@ module RStyx
     # stat message).  See Inferno man page stat(5) for more details.
     #
     class Stat
-      attr_accessor :size, :dtype, :dev, :qid, :mode, :atime, :mtime
-      attr_accessor :length, :name, :uid, :gid, :muid
+      ##
+      # Total byte count of the following data
+      attr_accessor :size
+      ##
+      # For kernel use
+      attr_accessor :dtype
+      ##
+      # For kernel use
+      attr_accessor :dev
+      ##
+      # The Qid of the file represented by the stat object
+      attr_accessor :qid
+      ##
+      # Permissions and flags
+      attr_accessor :mode
+      ##
+      # Last access time
+      attr_accessor :atime
+      ##
+      # Last modification time
+      attr_accessor :mtime
+      ##
+      # Length of the file in bytes
+      attr_accessor :length
+      ##
+      # File name; must be / if the file is the root directory of the server
+      attr_accessor :name
+      ##
+      # Owner name
+      #
+      attr_accessor :uid
+      ##
+      # Group name
+      attr_accessor :gid
+      ##
+      # Name of the user who last modified the file
+      attr_accessor :muid
 
-      def self.strextract(str, offset)
+      ##
+      # Internal function for extrating strings
+      def self.strextract(str, offset) # :nodoc:
         length = (str[offset..(offset + 1)].unpack("v"))[0]
         if length.nil?
           raise StyxException.new("invalid string, no length found")
@@ -148,10 +194,10 @@ module RStyx
       ##
       # Unserialize a Stat
       #
-      # +bytes+:: [String] serialized string representation of a Stat
+      # _bytes_:: [String] serialized string representation of a Stat
       # return value:: [Stat] the Stat corresponding to the
       #                passed string
-      # raises:: StyxException if +bytes+ cannot be properly decoded as
+      # raises:: StyxException if _bytes_ cannot be properly decoded as
       #          a Stat
       #
       def self.from_bytes(bytes)
@@ -213,14 +259,21 @@ module RStyx
     # Base class of a Styx message.
     #
     class StyxMessage
+      ##
+      # A hash indexed by the field names giving the field values.
+      #
       attr_accessor :fieldvals
+      ##
+      # A Hash indexed by the class of the message and its identifier
+      # number.
+      #
       MESSAGE_IDS = {}
 
       ##
       # Add a field to the StyxMessage.  Used by subclasses to define
-      # the message field.  The +name+ should be a Symbol that gives
+      # the message field.  The _name_ should be a Symbol that gives
       # the name of the field (preferably the canonical name given in the
-      # Inferno manual page intro(5)), and the type may be:
+      # Inferno manual page intro(5)), and the _type_ may be:
       #
       # 1. Any valid format string used by String#unpack or Array#pack.
       # 2. Cstr, which is a UTF-8 string, which will be serialized as
@@ -236,15 +289,21 @@ module RStyx
       #    a standard Ruby string.
       # 4. Qid, which deserializes into a Qid object instance and is
       #    serialized into a 13-byte binary representation.
-      # 5. QidList, which deserializes into an array of Qids and is
-      #    serialized into a two-byte unsigned count of Qids followed
-      #    by the serialized representations of each of the Qids.
+      # 5. QidList, which deserializes into an array of Qid objects and is
+      #    serialized into a two-byte unsigned count of Qid objects followed
+      #    by the serialized representations of each of the Qid objects.
       # 6. ULongLong, which deserializes into a Ruby Fixnum and is
       #    serialized into a 64-bit little-endian value.
       # 7. Stat, which deserializes into a Stat object instance and is
       #    serialized into the stat format described in the Inferno
       #    man page stat(5).  See the Stat class for more details.
       #
+      # This method will cause the (sub)class which uses it to have
+      # its inherited copy of StyxMessage#fields to receive the name
+      # and type declaration, and it will create attribute reader
+      # and writer methods of the form _name_ and _name_= to be added
+      # to the class.
+      #
       def self.add_field(name, type)
         self.fields << [name, type]
 
@@ -260,7 +319,9 @@ module RStyx
       end
 
       ##
-      # The fields of the Styx message.
+      # The fields of the Styx message, which consists of an array of
+      # arrays consisting of the field name and the field type (see
+      # StyxMessage#add_field for more details).
       #
       def self.fields
         # Default fields (excluding the size[4] field)
@@ -270,6 +331,12 @@ module RStyx
       ##
       # Create a new StyxMessage class.  This takes a hash of field
       # names and values, and this is put into a hash.
+      #
+      # _fieldvals_:: A hash of field values.  These values need not be
+      #               only the values of defined, for the message,
+      #               but only the values actually defined may be directly
+      #               accessed and will be serialized.
+      #   
       def initialize(fieldvals={})
         ident = MESSAGE_IDS[self.class]
         @fieldvals = {:ident=>ident}.merge(fieldvals)
@@ -284,14 +351,15 @@ module RStyx
       end
 
       ##
-      # Return the tag of the message
+      # Return the tag of the message.
       #
       def tag
         return(@fieldvals[:tag])
       end
 
       ##
-      # Set the tag of the message
+      # Set the tag of the message.
+      #
       def tag=(t)
         return(@fieldvals[:tag] = t)
       end
@@ -300,6 +368,10 @@ module RStyx
       # Deserialize a byte string into a StyxMessage subclass of some
       # kind.
       #
+      # _str_:: A byte string representing a Styx message
+      # return value:: The StyxMessage subclass instance represented by _str_
+      # raises:: StyxException if there was some error decoding _str_
+      #
       def self.from_bytes(str)
         origlength = str.length
         # get the length, identifier, and the rest of the string
@@ -361,7 +433,10 @@ module RStyx
       end
 
       ##
-      # Serialize a Styx message subclass into a byte string.
+      # Serialize a Styx message subclass instance into a byte string.
+      #
+      # returns:: The serialized String representation of the Styx message
+      #           subclass instance.
       #
       def to_bytes
         str = ""
@@ -417,6 +492,8 @@ module RStyx
 
       ##
       # Convert a Styx message into a human-readable string.
+      #
+      # returns:: The Styx message instance converted to a string.
       def to_s
         # First, start with the Styx message class name
         str = "(" + self.class.to_s.split("::")[-1]
@@ -435,16 +512,33 @@ module RStyx
 
     ##
     # Class representing a Tversion message sent by a Styx client.
+    # See Inferno's version(5) for more details.
+    #
+    # === Fields
+    #
+    # _msize_:: The client-suggested message size, that is the maximum
+    #           length in bytes that it will ever generate or expect to
+    #           receive in a single Styx message.
+    # _version_:: The version string identifying the level of the protocol
+    #             supported by the client.
     #
     class Tversion < StyxMessage
       StyxMessage::MESSAGE_IDS[Tversion] = 100
-      # 
       add_field(:msize, 'V')
       add_field(:version, 'Cstr')
     end
 
     ##
     # Class representing an Rversion message sent by a Styx server.
+    # See Inferno's version(5) for more details.
+    #
+    # === Fields
+    #
+    # _msize_:: The server's maximum message size, that is the maximum
+    #           length in bytes that it will ever generate or expect to
+    #           receive in a single Styx message.
+    # _version_:: The version string identifying the level of the protocol
+    #             supported by the server.
     #
     class Rversion < StyxMessage
       StyxMessage::MESSAGE_IDS[Rversion] = 101
@@ -454,6 +548,13 @@ module RStyx
 
     ##
     # Class representing a Tauth message sent by a Styx client.
+    # See Inferno's attach(5) for more details.
+    #
+    # === Fields
+    #
+    # _afid_:: New fid to be established for the authentication protocol
+    # _uname_:: The user name to authenticate as
+    # _aname_:: The file tree to access
     #
     class Tauth < StyxMessage
       StyxMessage::MESSAGE_IDS[Tauth] = 102
@@ -464,6 +565,12 @@ module RStyx
 
     ##
     # Class representing an Rauth message sent by a Styx server.
+    # See Inferno's attach(5) for more details.
+    #
+    # === Fields
+    #
+    # _aqid_:: a Qid defining a file of type QTAUTH that may be read and
+    #          written as per the authentication protocol.
     #
     class Rauth < StyxMessage
       StyxMessage::MESSAGE_IDS[Rauth] = 103
@@ -472,6 +579,14 @@ module RStyx
 
     ##
     # Class representing a Tattach message sent by a Styx client.
+    # See Inferno's attach(5) for more details.
+    #
+    # === Fields
+    #
+    # _fid_:: The fid to establish as the root of the server.
+    # _afid_:: The (optional) afid established by the authentication protocol.
+    # _uname_:: The user name authenticated against
+    # _aname_:: The file tree to access
     #
     class Tattach < StyxMessage
       StyxMessage::MESSAGE_IDS[Tattach] = 104
@@ -483,6 +598,12 @@ module RStyx
 
     ##
     # Class representing an Rattach message sent by a Styx server.
+    # See Inferno's attach(5) for more details.
+    #
+    # === Fields
+    #
+    # _qid_:: The Qid of the root of the file server on a successful
+    #         attach.
     #
     class Rattach < StyxMessage
       StyxMessage::MESSAGE_IDS[Rattach] = 105
@@ -502,6 +623,11 @@ module RStyx
 
     ##
     # Class representing an Rerror message sent by a Styx server.
+    # See Inferno's error(5) for more details.
+    #
+    # === Fields
+    #
+    # _ename_:: The error string describing the failure of the transaction.
     #
     class Rerror < StyxMessage
       StyxMessage::MESSAGE_IDS[Rerror] = 107
@@ -510,6 +636,11 @@ module RStyx
 
     ##
     # Class representing a Tflush message sent by a Styx client.
+    # See Inferno's flush(5) for more details.
+    #
+    # === Fields
+    #
+    # _oldtag_:: the tag of the message to flush
     #
     class Tflush < StyxMessage
       StyxMessage::MESSAGE_IDS[Tflush] = 108
@@ -518,6 +649,7 @@ module RStyx
 
     ##
     # Class representing an Rflush message sent by a Styx server.
+    # See Inferno's flush(5) for more details.
     #
     class Rflush < StyxMessage
       StyxMessage::MESSAGE_IDS[Rflush] = 109
@@ -525,6 +657,13 @@ module RStyx
 
     ##
     # Class representing a Twalk message sent by a Styx client.
+    # See Inferno's walk(5) for more details.
+    #
+    # === Fields
+    #
+    # _fid_:: The existing fid to start the walk from
+    # _newfid_:: The new fid to assign to the file walked to
+    # _wnames_:: A list of path elements to walk to
     #
     class Twalk < StyxMessage
       StyxMessage::MESSAGE_IDS[Twalk] = 110
@@ -532,10 +671,18 @@ module RStyx
       add_field(:newfid, "V")
       add_field(:wnames, "CstrList")
 
+      ##
+      # Set the _wnames_ field of the Twalk message by specifying
+      # a path name _str_ instead of an array of path elements.
+      #
       def path=(str)
         @fieldvals[:wnames] = str.split(File::SEPARATOR)
       end
 
+      ##
+      # Return the path name representation of the Twalk message's
+      # _wname_s.
+      #
       def path
         return(@fieldvals[:wnames].join(File::SEPARATOR))
       end
@@ -543,6 +690,12 @@ module RStyx
 
     ##
     # Class representing an Rwalk message sent by a Styx server.
+    # See Inferno's walk(5) for more details.
+    #
+    # === Fields
+    #
+    # _qids_:: The qid's corresponding to the path elements walked to
+    #          in response to the Twalk
     #
     class Rwalk < StyxMessage
       StyxMessage::MESSAGE_IDS[Rwalk] = 111
@@ -551,6 +704,12 @@ module RStyx
 
     ##
     # Class representing a Topen message sent by a Styx client.
+    # See Inferno's open(5) for more details.
+    #
+    # === Fields
+    #
+    # _fid_:: The fid of the file to open
+    # _mode_:: The open mode
     #
     class Topen < StyxMessage
       StyxMessage::MESSAGE_IDS[Topen] = 112
@@ -560,6 +719,14 @@ module RStyx
 
     ##
     # Class representing an Ropen message sent by a Styx server.
+    # See Inferno's open(5) for more details.
+    #
+    # === Fields
+    #
+    # _qid_:: The Qid representing the file that was opened
+    # _iounit_:: The maximum number of bytes guaranteed to be read from and
+    #            written to the file without breaking the transfer into
+    #            multiple messages.
     #
     class Ropen < StyxMessage
       StyxMessage::MESSAGE_IDS[Ropen] = 113
@@ -569,6 +736,14 @@ module RStyx
 
     ##
     # Class representing a Tcreate message sent by a Styx client.
+    # See Inferno's open(5) for more details.
+    #
+    # === Fields
+    #
+    # _fid_:: The fid of the file to open
+    # _name_:: The name of the file to create
+    # _perm_:: The permissions bitmask of the file to be created
+    # _mode_:: The open mode after file creation
     #
     class Tcreate < StyxMessage
       StyxMessage::MESSAGE_IDS[Tcreate] = 114
@@ -580,6 +755,14 @@ module RStyx
 
     ##
     # Class representing an Rcreate message sent by a Styx server.
+    # See Inferno's open(5) for more details.
+    #
+    # === Fields
+    #
+    # _qid_:: The Qid representing the file that was created
+    # _iounit_:: The maximum number of bytes guaranteed to be read from and
+    #            written to the file without breaking the transfer into
+    #            multiple messages.
     #
     class Rcreate < StyxMessage
       StyxMessage::MESSAGE_IDS[Rcreate] = 115
@@ -589,6 +772,13 @@ module RStyx
 
     ##
     # Class representing a Tread message sent by a Styx client.
+    # See Inferno's read(5) for more details.
+    #
+    # === Fields
+    #
+    # _fid_:: The fid of the file to read from
+    # _offset_:: The offset into the file to read from
+    # _count_:: The number of bytes to read from the file
     #
     class Tread < StyxMessage
       StyxMessage::MESSAGE_IDS[Tread] = 116
@@ -599,6 +789,11 @@ module RStyx
 
     ##
     # Class representing an Rread message sent by a Styx server.
+    # See Inferno's read(5) for more details.
+    #
+    # === Fields
+    #
+    # _data_:: the data read from the file
     #
     class Rread < StyxMessage
       StyxMessage::MESSAGE_IDS[Rread] = 117
@@ -612,6 +807,14 @@ module RStyx
     ##
     # Class representing a Twrite message sent by a Styx client.
     #
+    # See Inferno's read(5) for more details.
+    #
+    # === Fields
+    #
+    # _fid_:: The fid of the file to write to
+    # _offset_:: The offset into the file to write to
+    # _data_:: The data to be written to that offset
+    #
     class Twrite < StyxMessage
       StyxMessage::MESSAGE_IDS[Twrite] = 118
       add_field(:fid, "V")
@@ -621,6 +824,11 @@ module RStyx
 
     ##
     # Class representing an Rwrite message sent by a Styx server.
+    # See Inferno's read(5) for more details.
+    #
+    # === Fields
+    #
+    # _count_:: The number of bytes successfully written to the file
     #
     class Rwrite < StyxMessage
       StyxMessage::MESSAGE_IDS[Rwrite] = 119
@@ -629,6 +837,11 @@ module RStyx
 
     ##
     # Class representing a Tclunk message sent by a Styx client.
+    # See Inferno's clunk(5) for more details.
+    #
+    # === Fields
+    #
+    # _fid_:: The fid to clunk
     #
     class Tclunk < StyxMessage
       StyxMessage::MESSAGE_IDS[Tclunk] = 120
@@ -637,6 +850,7 @@ module RStyx
 
     ##
     # Class representing an Rclunk message sent by a Styx server.
+    # See Inferno's clunk(5) for more details.
     #
     class Rclunk < StyxMessage
       StyxMessage::MESSAGE_IDS[Rclunk] = 121
@@ -644,6 +858,11 @@ module RStyx
 
     ##
     # Class representing a Tremove message sent by a Styx client.
+    # See Inferno's remove(5) for more details.
+    #
+    # === Fields
+    #
+    # _fid_:: The fid to remove
     #
     class Tremove < StyxMessage
       StyxMessage::MESSAGE_IDS[Tremove] = 122
@@ -652,6 +871,7 @@ module RStyx
 
     ##
     # Class representing an Rremove message sent by a Styx server.
+    # See Inferno's remove(5) for more details.
     #
     class Rremove < StyxMessage
       StyxMessage::MESSAGE_IDS[Rremove] = 123
@@ -659,6 +879,11 @@ module RStyx
 
     ##
     # Class representing a Tstat message sent by a Styx client.
+    # See Inferno's stat(5) for more details.
+    #
+    # === Fields
+    #
+    # _fid_:: The fid to receive stat information
     #
     class Tstat < StyxMessage
       StyxMessage::MESSAGE_IDS[Tstat] = 124
@@ -667,6 +892,11 @@ module RStyx
 
     ##
     # Class representing an Rstat message sent by a Styx server.
+    # See Inferno's stat(5) for more details.
+    #
+    # === Fields
+    #
+    # _stat_:: the Stat corresponding to the file queried
     #
     class Rstat < StyxMessage
       StyxMessage::MESSAGE_IDS[Rstat] = 125
@@ -675,6 +905,12 @@ module RStyx
 
     ##
     # Class representing a Twstat message sent by a Styx client.
+    # See Inferno's stat(5) for more details.
+    #
+    # === Fields
+    #
+    # _fid_:: The fid to change stat information
+    # _stat_:: the Stat information to write to the file
     #
     class Twstat < StyxMessage
       StyxMessage::MESSAGE_IDS[Twstat] = 126
@@ -684,6 +920,7 @@ module RStyx
 
     ##
     # Class representing an Rwstat message sent by a Styx server.
+    # See Inferno's stat(5) for more details.
     #
     class Rwstat < StyxMessage
       StyxMessage::MESSAGE_IDS[Rwstat] = 127