README

   1 --
   2 $Id: README 1 2005-03-26 01:45:38Z tilman $
   3 ++
   4
   5 = ruby-eet -- Ruby bindings for EET
   6
   7 ruby-eet allows you to dump Ruby objects to disk in the EET file format.
   8 Compatibility with EET Data Descriptors, as used in the C API of libeet,
   9 is given.
  10
  11 ruby-eet is maintained by:
  12
  13 :include: AUTHORS
  14
  15 == License
  16
  17 ruby-eet is available under an MIT-style license.
  18
  19 :include: COPYING
  20
  21 == Download
  22
  23 The latest version of ruby-eet can be found at
  24 http://code-monkey.de/projects/ruby-efl.html
  25
  26 == Dependencies
  27
  28 ruby-eet depends on Rake[http://rake.rubyforge.org] 0.5.0 or greater
  29 and EET[http://www.enlightenment.org].
  30
  31 == Installation
  32
  33 Run "rake install" to install ruby-eet.
  34
  35 == Usage
  36
  37 === Basics
  38
  39 Each entry in an EET file consists of an unique key and the data that's
  40 associated with that key.
  41
  42 First, you have to open an EET file by calling Eet::File.open.
  43
  44 Now, you can store arbitrary data in the EET file with Eet::File#write.
  45 To read the data from the EET file, use Eet::File#read.
  46
  47 If you want to store/retrieve image data, see Eet::File#read_image and
  48 Eet::File#write_image.
  49
  50 === Serializing objects
  51
  52 ruby-eet also supports the serialization of objects which uses the same
  53 format as the C API uses for its EET data descriptors.
  54 At the time of this writing, deserialization, i.e. read support, isn't
  55 implemented yet, though.
  56
  57 Example:
  58
  59   class Foo
  60     def initialize
  61       @str = "bar"
  62       @int = 1024
  63     end
  64   end
  65
  66 Now, Foo.new.to_eet will serialize the object into EET format.
  67 All of the objects instance variables will be serialized, and the class
  68 name will be used as the tag.
  69
  70 To override the tag, you just need to implement Foo#to_eet_name:
  71
  72   class Foo
  73     def to_eet_name
  74       "Blah"
  75     end
  76   end
  77
  78 To control what information is stored for an object, override the method
  79 to_eet_properties.
  80
  81 to_eet_properties returns a hash containing keys that are the names of
  82 the stored properties. Each hash value is an array that contains the
  83 value to store at least. Optionally, it can also contain a type specifier
  84 to enforce specific encoding.
  85
  86 ==== Type specifiers
  87
  88 For fixnums and bignums, the valid type specifiers are :char, :short,
  89 :long_long which enforce encoding as 1 byte, 2 byte or 8 byte value
  90 respectively. The default is to encode the value as a 4 byte value.
  91
  92 For floats, the valid type specifier is :double, which enforces encoding
  93 as an 8 byte value. The default is to encode the value as a 4 byte value.