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