lwes 0.8.1 → 0.8.2

data/ChangeLog

@@ -1,3 +1,6 @@
+Version 0.8.2 (erik-s-chang)
+  * 100% RDoc coverage.
+
 Version 0.8.1 (erik-s-chang)
   * fix broken optimization for large (non-sparse) LWES::Structs
 

data/README

@@ -51,26 +51,6 @@ See link:LWES.html
 
 For prototyping and development, it may be easier to not use an ESF
 file.  In those cases, you may skip the TypeDB steps entirely and
-just use an emitter to send Hash objects:
-
-  emitter = LWES::Emitter.new(:address => '224.1.1.11',
-                              :port => 12345,
-                              :heartbeat => 30, # nil to disable
-                              :ttl => 1) # nil for default TTL(3)
-
-  # Since we can't reliably map certain Ruby types to LWES types, you'll
-  # have to specify them explicitly for IP addresses and all Integer
-  # types.
-  event = {
-    :time_sec => [ :int32, Time.now.to_i ],
-    :time_usec => [ :int32, Time.now.tv_usec ],
-    :remote_addr => [ :ip_addr, "192.168.0.1" ],
-  }
-
-  # Strings and Boolean values are easily mapped, however:
-  event[:field1] = "String value"
-  event[:boolean1] = true
-  event[:boolean2] = false
-
-  # finally, we just emit the hash with any given name
-  emitter.emit "Event3", event
+just use an emitter to send Hash objects.
+
+See "NON-ESF USERS" section in link:LWES/Emitter.html

data/ext/lwes_ext/emitter.c

@@ -338,10 +338,10 @@ static VALUE emit_event(VALUE self, VALUE event)
 }
 /*
  * call-seq:
- *   emitter = LWES::Emitter.new
- *   event = EventStruct.new
- *   event.foo = "bar"
  *   emitter << event
+ *
+ * Emits the given +event+ which much be an LWES::Event or
+ * LWES::Struct-derived object
  */
 static VALUE emitter_ltlt(VALUE self, VALUE event)
 {
@@ -356,15 +356,22 @@ static VALUE emitter_ltlt(VALUE self, VALUE event)
 
 /*
  * call-seq:
- *   emitter = LWES::Emitter.new
+ *	emitter.emit("EventName", :foo => "HI")
+ *	emitter.emit("EventName", :foo => [ :int32, 123 ])
+ *	emitter.emit(EventClass, :foo => "HI")
+ *	emitter.emit(event)
  *
- *   emitter.emit("EventName", :foo => "HI")
+ * Emits a hash.  If EventName is given as a string, it will expect a hash
+ * as its second argument and will do its best to serialize a Ruby Hash
+ * to an LWES Event.  If a type is ambiguous, a two-element array may be
+ * specified as its value, including the LWES type information and the
+ * Ruby value.
  *
- *   emitter.emit(EventStruct, :foo => "HI")
+ * If an EventClass is given, the second argument should be a hash with
+ * the values given to the class.   This will emit the event named by
+ * EventClass.
  *
- *   struct = EventStruct.new
- *   struct.foo = "HI"
- *   emitter.emit(struct)
+ * If only one argument is given, it behaves just like LWES::Emitter#<<
  */
 static VALUE emitter_emit(int argc, VALUE *argv, VALUE self)
 {
@@ -412,6 +419,9 @@ static VALUE emitter_emit(int argc, VALUE *argv, VALUE self)
 }
 
 /*
+ * call-seq:
+ *	emitter.close	-> nil
+ *
  * Destroys the associated lwes_emitter and the associated socket.  This
  * method is rarely needed as Ruby garbage collection will take care of
  * closing for you, but may be useful in odd cases when it is desirable
@@ -468,7 +478,7 @@ static VALUE init_copy(VALUE dest, VALUE obj)
 	return dest;
 }
 
-/* should only used internally by #initialize */
+/* :nodoc: should only used internally by #initialize */
 static VALUE _create(VALUE self, VALUE options)
 {
 	struct _rb_lwes_emitter *rle = _rle(self);
@@ -554,5 +564,10 @@ void lwesrb_init_emitter(void)
 	sym_enc = ID2SYM(id_enc);
 
 	ENC = rb_obj_freeze(rb_str_new2(LWES_ENCODING));
+
+	/*
+	 * the key in an LWES::Event to designate the encoding of
+	 * an event, currently "enc"
+	 */
 	rb_define_const(mLWES, "ENCODING", ENC);
 }

data/ext/lwes_ext/event.c

@@ -90,6 +90,14 @@ static char *key2attr(VALUE key)
 	return StringValueCStr(key);
 }
 
+/*
+ * call-seq:
+ *
+ *	event[key]	-> value
+ *
+ * Returns the +value+ stored with the +key+.  This will return +nil+ if
+ * +key+ does not exist.  +key+ must be a Symbol or String object
+ */
 static VALUE event_aref(VALUE self, VALUE key)
 {
 	char *attr = key2attr(key);
@@ -100,6 +108,14 @@ static VALUE event_aref(VALUE self, VALUE key)
 	return eattr ? lwesrb_attr_to_value(eattr) : Qnil;
 }
 
+/*
+ * call-seq:
+ *
+ *	event[key] = value
+ *
+ * Assigns +value+ to be stored in the event given by +key+.
+ * +key+ must be a String or Symbol object.
+ */
 static VALUE event_aset(VALUE self, VALUE key, VALUE val)
 {
 	char *attr = key2attr(key);
@@ -174,7 +190,13 @@ static VALUE lwesrb_attr_to_value(struct lwes_event_attribute *attr)
 }
 
 /*
- * Returns an LWES::Event object as a plain Ruby hash
+ * call-seq:
+ *
+ *	event.to_hash	-> Hash
+ *
+ * Returns an LWES::Event object as a plain Ruby hash.  Useful for
+ * interoperating with existing Ruby code and also when you don't
+ * have Event Specification Files finalized (or available).
  */
 static VALUE to_hash(VALUE self)
 {
@@ -227,13 +249,9 @@ VALUE lwesrb_wrap_event(VALUE klass, struct lwes_event *e)
 /*
  * call-seq:
  *
- *	receiver = UDPSocket.new
- *	receiver.bind(nil, 12345)
- *	buf, addr = receiver.recvfrom(65536)
- *	parsed = LWES::Event.parse(buf)
- *	parsed.to_hash -> hash
+ *	LWES::Event.parse(buffer)	-> LWES::Event
  *
- * Parses a string +buf+ and returns a new LWES::Event object
+ * Parses a string +buffer+ and returns a new LWES::Event object
  */
 static VALUE parse(VALUE self, VALUE buf)
 {

data/ext/lwes_ext/type_db.c

@@ -15,6 +15,13 @@ static VALUE tdb_alloc(VALUE klass)
 	return Data_Wrap_Struct(klass, NULL, tdb_free, NULL);
 }
 
+/*
+ * call-seq:
+ *
+ *	LWES::TypeDB.new("events.esf") -> LWES::TypeDB
+ *
+ * Initializes a new TypeDB object based on the path to a given ESF file.
+ */
 static VALUE tdb_init(VALUE self, VALUE path)
 {
 	struct lwes_event_type_db *db = DATA_PTR(self);
@@ -101,6 +108,7 @@ struct lwes_event_type_db * lwesrb_get_type_db(VALUE self)
 	return db;
 }
 
+/* :nodoc: */
 static VALUE tdb_to_hash(VALUE self)
 {
 	struct lwes_event_type_db *db = DATA_PTR(self);

data/lib/lwes.rb

@@ -36,8 +36,8 @@
 #    emitter.emit MyApp::Event2, :field1 => value1, :field2 => value2 # ...
 #
 module LWES
-  # version of our library, currently 0.8.0pre1
-  VERSION = "0.8.0pre1"
+  # version of our library, currently 0.8.2
+  VERSION = "0.8.2"
 
   autoload :ClassMaker, "lwes/class_maker"
   autoload :TypeDB, "lwes/type_db"

data/lib/lwes/emitter.rb

@@ -1,19 +1,52 @@
-module LWES
-  class Emitter
+# The LWES::Emitter is used for emitting LWES events to a multicast
+# network or a single host.  It can emit LWES::Event objects, LWES::Struct
+# objects, and even plain Ruby hashes.
+#
+# It is non-blocking and does not guarantee delivery.
+#
+#
+#    emitter = LWES::Emitter.new(:address => '224.1.1.11',
+#                                :port => 12345,
+#                                :heartbeat => 30, # nil to disable
+#                                :ttl => 1) # nil for default TTL(3)
+#    event = MyEvent.new
+#    event.foo = "bar"
+#
+#    emitter << event
+#
+# === NON-ESF USERS
+#
+# Since we can't reliably map certain Ruby types to LWES types, you'll
+# have to specify them explicitly for IP addresses and all Integer
+# types.
+#
+#    event = {
+#      :time_sec => [ :int32, Time.now.to_i ],
+#      :time_usec => [ :int32, Time.now.tv_usec ],
+#      :remote_addr => [ :ip_addr, "192.168.0.1" ],
+#    }
+#
+#    # Strings and Boolean values are easily mapped, however:
+#    event[:field1] = "String value"
+#    event[:boolean1] = true
+#    event[:boolean2] = false
+#
+#    # finally, we just emit the hash with any given name
+#    emitter.emit "Event3", event
+class LWES::Emitter
 
-    # creates a new Emitter object which may be used for the lifetime
-    # of the process:
-    #
-    #   LWES::Emitter.new(:address => '224.1.1.11',
-    #                     :iface => '0.0.0.0',
-    #                     :port => 12345,
-    #                     :heartbeat => false, # Integer for frequency
-    #                     :ttl => 60, # nil for no ttl)
-    #
-    def initialize(options = {}, &block)
-      options[:iface] ||= '0.0.0.0'
-      _create(options)
-      block_given?
-    end
+  # creates a new Emitter object which may be used for the lifetime
+  # of the process:
+  #
+  #   LWES::Emitter.new(:address => '224.1.1.11',
+  #                     :iface => '0.0.0.0',
+  #                     :port => 12345,
+  #                     :heartbeat => false, # Integer for frequency
+  #                     :ttl => 60, # nil for no ttl)
+  #
+  def initialize(options = {}, &block)
+    options[:iface] ||= '0.0.0.0'
+    _create(options)
+    block_given?
   end
 end

data/lib/lwes/event.rb

@@ -2,7 +2,17 @@
 # LWES::Event-derived classes are more memory efficient if your event
 # definitions have many unused fields.
 #
-# LWES::TypeDB.create_classes! with +:sparse+ set to +true+
+# LWES::TypeDB.create_classes! with +:sparse+ set to +true+ will create
+# classes subclassed from LWES::Event instead of LWES::Struct.
+#
+# For users unable to use LWES::Listener, LWES::Event.parse may also be
+# used with UDPSocket (distributed with Ruby) to parse events:
+#
+#   receiver = UDPSocket.new
+#   receiver.bind(nil, port)
+#   buffer, addr = receiver.recvfrom(65536)
+#   event = LWES::Event.parse(buffer)
+
 class LWES::Event
   SYM2ATTR = Hash.new { |h,k| h[k] = k.to_s.freeze } # :nodoc:
 
@@ -10,6 +20,10 @@ class LWES::Event
   CLASSES = {} # :nodoc:
   extend LWES::ClassMaker
 
+  # There is no need to call this method directly.  use
+  # LWES::TypeDB.create_classes! with the +:sparse+ flag set to +true+.
+  #
+  # This takes the same options as LWES::Struct.new.
   def self.subclass(options, &block)
     db = type_db(options)
     dump = db.to_hash
@@ -29,6 +43,7 @@ class LWES::Event
     CLASSES[name] = tmp
   end
 
+  # returns a human-readable representation of the event
   def inspect
     klass = self.class
     if LWES::Event == klass
@@ -38,6 +53,7 @@ class LWES::Event
     end
   end
 
+  # overwrites the values of the existing event with those given in +src+
   def merge! src
     src.to_hash.each { |k,v| self[k] = v }
     self
@@ -45,12 +61,16 @@ class LWES::Event
 
   alias_method :initialize_copy, :merge!
 
+  # duplicates the given event and overwrites the copy with values given
+  # in +src+
   def merge src
     dup.merge! src
   end
 
 private
 
+  # Initializes a new LWES::Event.  If +src+ is given, it must be an
+  # LWES::Event or hash which the new event takes initial values from
   def initialize(src = nil)
     src and merge! src
   end

data/lib/lwes/listener.rb

@@ -15,7 +15,8 @@ class LWES::Listener
 
   alias clone dup
 
-  # process each LWES::Event object as it is received
+  # processes each LWES::Event object as it is received, yielding
+  # the LWES::Event to a given block
   def each
     begin
       yield recv

data/lib/lwes/struct.rb

@@ -3,11 +3,18 @@
 #
 # LWES::Struct is may be more memory-efficient and faster if your application
 # uses all or most of the fields in the event definition.  LWES::Event should
-# be used in cases where many event fields are unused in a definition.
+# be used in cases where many event fields are unused in an event definition.
+#
+# LWES::Struct is created by LWES::TypeDB#create_classes! by default
+# where the +:sparse+ flag is +false+.  There is little need to use this
+# class directly.
 class LWES::Struct
   extend LWES::ClassMaker
 
-  # creates a new Struct-based class, takes the following
+  # There is usually no need to use this method,
+  # LWES::TypeDB.create_classes! will call this for you
+  #
+  # Creates a new Struct-based class, takes the following
   # options hash:
   #
   #   :db       - pre-created LWES::TypeDB object

data/lib/lwes/type_db.rb

@@ -1,3 +1,6 @@
+# This class may be used to load an ESF (event specification files)
+# and automatically create Ruby classes based on the ESF.
+
 class LWES::TypeDB
 
   # create LWES::Struct-derived classes based on the contents
@@ -8,19 +11,23 @@ class LWES::TypeDB
   #   module MyEvents; end
   #
   #   type_db = LWES::TypeDB.new("my_events.esf")
-  #   type_db.create_classes!(:parent => MyEvents)
-  #   type_db.create_classes!(:sparse => true)
+  #   type_db.create_classes!(:parent => MyEvents, :sparse => true)
   #
   # Assuming you had "Event1" and "Event2" defined in your "my_events.esf"
   # file, then the classes MyEvents::Event1 and MyEvents::Event2 should
   # now be accessible.
   #
-  #   :parent   - parent class or module, the default is 'Object' putting
-  #               the new class in the global namespace.  May be +nil+ for
-  #               creating anonymous classes.
-  #   :sparse   - If +true+, this will subclass from LWES::Event instead of
-  #               :Struct for better memory efficiency when dealing with
-  #               events with many unused fields.  Default is +false+.
+  # [ :parent => class or nil ]
+  #
+  #   Parent class or module, the default is 'Object' putting
+  #   the new class in the global namespace.  May be +nil+ for
+  #   creating anonymous classes.
+  #
+  # [ :sparse => true or false ]
+  #
+  #   If +true+, this will subclass from LWES::Event instead of
+  #   Struct for better memory efficiency when dealing with
+  #   events with many unused fields.  Default is +false+.
   def create_classes!(options = {})
     classes = to_hash.keys - [ :MetaEventInfo ]
     classes.sort { |a,b| a.to_s.size <=> b.to_s.size }.map! do |klass|

data/lwes.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = %q{lwes}
-  s.version = "0.8.1"
+  s.version = "0.8.2"
   s.date = Time.now
   s.authors = ["Erik S. Chang", "Frank Maritato"]
   s.email = %q{lwes-devel@lists.sourceforge.net}

metadata

@@ -2,7 +2,7 @@
 name: lwes
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.8.1
+  version: 0.8.2
 platform: ruby
 authors: 
 - Erik S. Chang
@@ -11,7 +11,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-15 00:00:00 +00:00
+date: 2011-04-28 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency