1 #!/usr/bin/env ruby
2 #--
3 # Copyright 2004, 2005 by Jim Weirich (jim@weirichhouse.org).
4 # All rights reserved.
5
6 # Permission is granted for use, copying, modification, distribution,
7 # and distribution of modified versions of this work as long as the
8 # above copyright notice is included.
9 #++
10
11 # Provide a flexible and easy to use Builder for creating XML markup.
12 # See XmlBuilder for usage details.
13
14 require 'builder/xmlbase'
15
16 module Builder
17
18 # Create XML markup easily. All (well, almost all) methods sent to
19 # an XmlMarkup object will be translated to the equivalent XML
20 # markup. Any method with a block will be treated as an XML markup
21 # tag with nested markup in the block.
22 #
23 # Examples will demonstrate this easier than words. In the
24 # following, +xm+ is an +XmlMarkup+ object.
25 #
26 # xm.em("emphasized") # => <em>emphasized</em>
27 # xm.em { xmm.b("emp & bold") } # => <em><b>emph & bold</b></em>
28 # xm.a("A Link", "href"=>"http://onestepback.org")
29 # # => <a href="http://onestepback.org">A Link</a>
30 # xm.div { br } # => <div><br/></div>
31 # xm.target("name"=>"compile", "option"=>"fast")
32 # # => <target option="fast" name="compile"\>
33 # # NOTE: order of attributes is not specified.
34 #
35 # xm.instruct! # <?xml version="1.0" encoding="UTF-8"?>
36 # xm.html { # <html>
37 # xm.head { # <head>
38 # xm.title("History") # <title>History</title>
39 # } # </head>
40 # xm.body { # <body>
41 # xm.comment! "HI" # <! -- HI -->
42 # xm.h1("Header") # <h1>Header</h1>
43 # xm.p("paragraph") # <p>paragraph</p>
44 # } # </body>
45 # } # </html>
46 #
47 # == Notes:
48 #
49 # * The order that attributes are inserted in markup tags is
50 # undefined.
51 #
52 # * Sometimes you wish to insert text without enclosing tags. Use
53 # the <tt>text!</tt> method to accomplish this.
54 #
55 # Example:
56 #
57 # xm.div { # <div>
58 # xm.text! "line"; xm.br # line<br/>
59 # xm.text! "another line"; xmbr # another line<br/>
60 # } # </div>
61 #
62 # * The special XML characters <, >, and & are converted to <,
63 # > and & automatically. Use the <tt><<</tt> operation to
64 # insert text without modification.
65 #
66 # * Sometimes tags use special characters not allowed in ruby
67 # identifiers. Use the <tt>tag!</tt> method to handle these
68 # cases.
69 #
70 # Example:
71 #
72 # xml.tag!("SOAP:Envelope") { ... }
73 #
74 # will produce ...
75 #
76 # <SOAP:Envelope> ... </SOAP:Envelope>"
77 #
78 # <tt>tag!</tt> will also take text and attribute arguments (after
79 # the tag name) like normal markup methods. (But see the next
80 # bullet item for a better way to handle XML namespaces).
81 #
82 # * Direct support for XML namespaces is now available. If the
83 # first argument to a tag call is a symbol, it will be joined to
84 # the tag to produce a namespace:tag combination. It is easier to
85 # show this than describe it.
86 #
87 # xml.SOAP :Envelope do ... end
88 #
89 # Just put a space before the colon in a namespace to produce the
90 # right form for builder (e.g. "<tt>SOAP:Envelope</tt>" =>
91 # "<tt>xml.SOAP :Envelope</tt>")
92 #
93 # * XmlMarkup builds the markup in any object (called a _target_)
94 # that accepts the <tt><<</tt> method. If no target is given,
95 # then XmlMarkup defaults to a string target.
96 #
97 # Examples:
98 #
99 # xm = Builder::XmlMarkup.new
100 # result = xm.title("yada")
101 # # result is a string containing the markup.
102 #
103 # buffer = ""
104 # xm = Builder::XmlMarkup.new(buffer)
105 # # The markup is appended to buffer (using <<)
106 #
107 # xm = Builder::XmlMarkup.new(STDOUT)
108 # # The markup is written to STDOUT (using <<)
109 #
110 # xm = Builder::XmlMarkup.new
111 # x2 = Builder::XmlMarkup.new(:target=>xm)
112 # # Markup written to +x2+ will be send to +xm+.
113 #
114 # * Indentation is enabled by providing the number of spaces to
115 # indent for each level as a second argument to XmlBuilder.new.
116 # Initial indentation may be specified using a third parameter.
117 #
118 # Example:
119 #
120 # xm = Builder.new(:indent=>2)
121 # # xm will produce nicely formatted and indented XML.
122 #
123 # xm = Builder.new(:indent=>2, :margin=>4)
124 # # xm will produce nicely formatted and indented XML with 2
125 # # spaces per indent and an over all indentation level of 4.
126 #
127 # builder = Builder::XmlMarkup.new(:target=>$stdout, :indent=>2)
128 # builder.name { |b| b.first("Jim"); b.last("Weirich) }
129 # # prints:
130 # # <name>
131 # # <first>Jim</first>
132 # # <last>Weirich</last>
133 # # </name>
134 #
135 # * The instance_eval implementation which forces self to refer to
136 # the message receiver as self is now obsolete. We now use normal
137 # block calls to execute the markup block. This means that all
138 # markup methods must now be explicitly send to the xml builder.
139 # For instance, instead of
140 #
141 # xml.div { strong("text") }
142 #
143 # you need to write:
144 #
145 # xml.div { xml.strong("text") }
146 #
147 # Although more verbose, the subtle change in semantics within the
148 # block was found to be prone to error. To make this change a
149 # little less cumbersome, the markup block now gets the markup
150 # object sent as an argument, allowing you to use a shorter alias
151 # within the block.
152 #
153 # For example:
154 #
155 # xml_builder = Builder::XmlMarkup.new
156 # xml_builder.div { |xml|
157 # xml.stong("text")
158 # }
159 #
160 class XmlMarkup < XmlBase
161
162 # Create an XML markup builder. Parameters are specified by an
163 # option hash.
164 #
165 # :target=><em>target_object</em>::
166 # Object receiving the markup. +out+ must respond to the
167 # <tt><<</tt> operator. The default is a plain string target.
168 #
169 # :indent=><em>indentation</em>::
170 # Number of spaces used for indentation. The default is no
171 # indentation and no line breaks.
172 #
173 # :margin=><em>initial_indentation_level</em>::
174 # Amount of initial indentation (specified in levels, not
175 # spaces).
176 #
177 # :escape_attrs=><b>OBSOLETE</em>::
178 # The :escape_attrs option is no longer supported by builder
179 # (and will be quietly ignored). String attribute values are
180 # now automatically escaped. If you need unescaped attribute
181 # values (perhaps you are using entities in the attribute
182 # values), then give the value as a Symbol. This allows much
183 # finer control over escaping attribute values.
184 #
185 def initialize(options={})
186 indent = options[:indent] || 0
187 margin = options[:margin] || 0
188 super(indent, margin)
189 @target = options[:target] || ""
190 end
191
192 # Return the target of the builder.
193 def target!
194 @target
195 end
196
197 def comment!(comment_text)
198 _ensure_no_block block_given?
199 _special("<!-- ", " -->", comment_text, nil)
200 end
201
202 # Insert an XML declaration into the XML markup.
203 #
204 # For example:
205 #
206 # xml.declare! :ELEMENT, :blah, "yada"
207 # # => <!ELEMENT blah "yada">
208 def declare!(inst, *args, &block)
209 _indent
210 @target << "<!#{inst}"
211 args.each do |arg|
212 case arg
213 when String
214 @target << %{ "#{arg}"} # " WART
215 when Symbol
216 @target << " #{arg}"
217 end
218 end
219 if block_given?
220 @target << " ["
221 _newline
222 _nested_structures(block)
223 @target << "]"
224 end
225 @target << ">"
226 _newline
227 end
228
229 # Insert a processing instruction into the XML markup. E.g.
230 #
231 # For example:
232 #
233 # xml.instruct!
234 # #=> <?xml version="1.0" encoding="UTF-8"?>
235 # xml.instruct! :aaa, :bbb=>"ccc"
236 # #=> <?aaa bbb="ccc"?>
237 #
238 def instruct!(directive_tag=:xml, attrs={})
239 _ensure_no_block block_given?
240 if directive_tag == :xml
241 a = { :version=>"1.0", :encoding=>"UTF-8" }
242 attrs = a.merge attrs
243 end
244 _special(
245 "<?#{directive_tag}",
246 "?>",
247 nil,
248 attrs,
249 [:version, :encoding, :standalone])
250 end
251
252 # Insert a CDATA section into the XML markup.
253 #
254 # For example:
255 #
256 # xml.cdata!("text to be included in cdata")
257 # #=> <![CDATA[text to be included in cdata]]>
258 #
259 def cdata!(text)
260 _ensure_no_block block_given?
261 _special("<![CDATA[", "]]>", text, nil)
262 end
263
264 private
265
266 # NOTE: All private methods of a builder object are prefixed when
267 # a "_" character to avoid possible conflict with XML tag names.
268
269 # Insert text directly in to the builder's target.
270 def _text(text)
271 @target << text
272 end
273
274 # Insert special instruction.
275 def _special(open, close, data=nil, attrs=nil, order=[])
276 _indent
277 @target << open
278 @target << data if data
279 _insert_attributes(attrs, order) if attrs
280 @target << close
281 _newline
282 end
283
284 # Start an XML tag. If <tt>end_too</tt> is true, then the start
285 # tag is also the end tag (e.g. <br/>
286 def _start_tag(sym, attrs, end_too=false)
287 @target << "<#{sym}"
288 _insert_attributes(attrs)
289 @target << "/" if end_too
290 @target << ">"
291 end
292
293 # Insert an ending tag.
294 def _end_tag(sym)
295 @target << "</#{sym}>"
296 end
297
298 # Insert the attributes (given in the hash).
299 def _insert_attributes(attrs, order=[])
300 return if attrs.nil?
301 order.each do |k|
302 v = attrs[k]
303 @target << %{ #{k}="#{_attr_value(v)}"} if v # " WART
304 end
305 attrs.each do |k, v|
306 @target << %{ #{k}="#{_attr_value(v)}"} unless order.member?(k) # " WART
307 end
308 end
309
310 def _attr_value(value)
311 case value
312 when Symbol
313 value.to_s
314 else
315 _escape_quote(value.to_s)
316 end
317 end
318
319 def _ensure_no_block(got_block)
320 if got_block
321 fail IllegalBlockError,
322 "Blocks are not allowed on XML instructions"
323 end
324 end
325
326 end
327
328 end