1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
ROXML Ruby Object to XML mapping library.
{<img src="https://travis-ci.org/Empact/roxml.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/Empact/roxml]
For more information visit:
http://rdoc.info/projects/Empact/roxml
http://empact.github.com/roxml/
Please submit bugs here:
http://github.com/Empact/roxml/issues
=Quick Start Guide
This is a short usage example. See ROXML::ClassMethods::Declarations and packaged test cases for more information.
==Basic Mapping
Consider an XML document representing a Library containing a number of Books. You
can map this structure to Ruby classes that provide addition useful behavior. With
ROXML, you can annotate the Ruby classes as follows:
class Book
include ROXML
xml_accessor :isbn, :from => "@ISBN" # attribute with name 'ISBN'
xml_accessor :title
xml_accessor :description, :cdata => true # text node with cdata protection
xml_accessor :author
end
class Library
include ROXML
xml_accessor :name, :from => "NAME", :cdata => true
xml_accessor :books, :as => [Book] # by default roxml searches for books for in <book> child nodes, then, if none are present, in ./books/book children
end
To create a library and put a number of books in it we could run the following code:
book = Book.new
book.isbn = "0201710897"
book.title = "The PickAxe"
book.description = "Best Ruby book out there!"
book.author = "David Thomas, Andrew Hunt, Dave Thomas"
lib = Library.new
lib.name = "Favorite Books"
lib.books = [book]
To save this information to an XML file:
doc = Nokogiri::XML::Document.new
doc.root = lib.to_xml
open("library.xml", 'w') do |file|
file << doc.serialize
end
or
doc = LibXML::XML::Document.new
doc.root = lib.to_xml
doc.save("library.xml")
To later populate the library object from the XML file:
lib = Library.from_xml(File.read("library.xml"))
Similarly, to do a one-to-one mapping between XML objects, such as book and publisher,
you would add a reference to another ROXML class. For example:
<book isbn="0974514055">
<title>Programming Ruby - 2nd Edition</title>
<description>Second edition of the great book.</description>
<publisher>
<name>Pragmatic Bookshelf</name>
</publisher>
</book>
can be mapped using the following code:
class Publisher
include ROXML
xml_accessor :name
# other important functionality
end
class BookWithPublisher
include ROXML
xml_name 'book'
xml_reader :publisher, :as => Publisher
# or, alternatively, if no class is needed to hang functionality on:
# xml_reader :publisher, :from => 'name', :in => 'publisher'
end
Note: In the above example, _xml_name_ annotation tells ROXML to set the element
name to "book" for mapping to XML. The default is XML element name is the class name in lowercase; "bookwithpublisher"
in this case.
=== Namespace Support
Namespaced nodes are supported via the xml_namespace and xml_namespaces declarations and the :from and :namespace attr options. See spec/xml/namespace_spec.rb for usage.
Note that ROXML does not currently support outputting namespaced nodes. This is planned for a future version.
== Manipulation
Extending the above examples, say you want to parse a book's page count and have it available as an Integer.
In such a case, you can extend any object with a block to manipulate it's value at parse time. For example:
class Dog
include ROXML
xml_reader(:age, :from => '@human_years', :as => Integer) {|years| years * 7 }
end
The result of the block above is stored, rather than the actual value parsed from the document.
== Construction
Object life-cycle is as follows: .from_xml is called with a first argument representing the xml
in file, string, or path form, and with optional initialization_args following.
Firt .new and thus #initialize, is called with those same initialization_args, or no args if none
are present. Then the object is populated with the attribute values from xml. Then the
#after_parse callback is called, with no arguments.
In #after_parse you can ensure that your object initialization is complete, including initialization which
requires more than one variable in concert.
E.g.:
class Measurement
include ROXML
xml_reader :units, :from => :attr
xml_reader :value, :from => :content
def initialize(value = 0, units = 'meters')
to_metric
end
private
def after_parse
# xml attributes of self are already valid
to_metric
end
def to_metric
# translate units & value into metric, for example
end
end
One important use of this approach is to make ROXML object which may or may not include an xml backing,
which may be used via _new_ construction as well as _from_xml_ construction.
== Selecting a parser
By default, ROXML will use Nokogiri if it is available, followed by LibXML. If you'd like to
explicitly require one or the other, you may do the following:
module ROXML
XML_PARSER = 'nokogiri' # or 'libxml'
end
require 'roxml'
For more information on available annotations, see ROXML::ClassMethods::Declarations
== Note on Patches/Pull Requests
* Fork the project.
* Make your feature addition or bug fix.
* Add specs for it. This is important so I don't break it in a
future version unintentionally.
* Commit, do not mess with rakefile, version, or history.
(if you want to have your own version, that is fine but
bump version in a commit by itself I can ignore when I pull)
* Send me a pull request. Bonus points for topic branches.
== Copyright
Copyright (c) 2004-2009 Ben Woosley, Zak Mandhro and Anders Engstrom. See LICENSE for details.
|
