Parent

Builder::XmlBase

XmlBase is a base class for building XML builders. See Builder::XmlMarkup and Builder::XmlEvents for examples.

Public Class Methods

new(indent=0, initial=0, encoding='utf-8') click to toggle source

Create an XML markup builder.

out

Object receiving the markup. out must respond to <<.

indent

Number of spaces used for indentation (0 implies no indentation and no line breaks).

initial

Level of initial indentation.

encoding

When encoding and $KCODE are set to ‘utf-8’ characters aren’t converted to character entities in the output stream.

    # File lib/builder/xmlbase.rb, line 24
24:     def initialize(indent=0, initial=0, encoding='utf-8')
25:       @indent = indent
26:       @level  = initial
27:       @encoding = encoding.downcase
28:     end

Public Instance Methods

<<(text) click to toggle source

Append text to the output target without escaping any markup. May be used within the markup brackets as:

  builder.p { |x| x << "<br/>HI" }   #=>  <p><br/>HI</p>

This is useful when using non-builder enabled software that generates strings. Just insert the string directly into the builder without changing the inserted markup.

It is also useful for stacking builder objects. Builders only use << to append to the target, so by supporting this method/operation builders can use other builders as their targets.

     # File lib/builder/xmlbase.rb, line 104
104:     def <<(text)
105:       _text(text)
106:     end
method_missing(sym, *args, &block) click to toggle source

Create XML markup based on the name of the method. This method is never invoked directly, but is called for each markup method in the markup block.

    # File lib/builder/xmlbase.rb, line 40
40:     def method_missing(sym, *args, &block)
41:       text = nil
42:       attrs = nil
43:       sym = "#{sym}:#{args.shift}" if args.first.kind_of?(::Symbol)
44:       args.each do |arg|
45:         case arg
46:         when ::Hash
47:           attrs ||= {}
48:           attrs.merge!(arg)
49:         else
50:           text ||= ''
51:           text << arg.to_s
52:         end
53:       end
54:       if block
55:         unless text.nil?
56:           ::Kernel::raise ::ArgumentError,
57:             "XmlMarkup cannot mix a text argument with a block"
58:         end
59:         _indent
60:         _start_tag(sym, attrs)
61:         _newline
62:         begin
63:           _nested_structures(block)
64:         ensure
65:           _indent
66:           _end_tag(sym)
67:           _newline
68:         end
69:       elsif text.nil?
70:         _indent
71:         _start_tag(sym, attrs, true)
72:         _newline
73:       else
74:         _indent
75:         _start_tag(sym, attrs)
76:         text! text
77:         _end_tag(sym)
78:         _newline
79:       end
80:       @target
81:     end
nil?() click to toggle source

For some reason, nil? is sent to the XmlMarkup object. If nil? is not defined and method_missing is invoked, some strange kind of recursion happens. Since nil? won’t ever be an XML tag, it is pretty safe to define it here. (Note: this is an example of cargo cult programming, cf. fishbowl.pastiche.org/2004/10/13/cargo_cult_programming).

     # File lib/builder/xmlbase.rb, line 114
114:     def nil?
115:       false
116:     end
tag!(sym, *args, &block) click to toggle source

Create a tag named sym. Other than the first argument which is the tag name, the arguments are the same as the tags implemented via method_missing.

    # File lib/builder/xmlbase.rb, line 33
33:     def tag!(sym, *args, &block)
34:       method_missing(sym.to_sym, *args, &block)
35:     end
text!(text) click to toggle source

Append text to the output target. Escape any markup. May be used within the markup brackets as:

  builder.p { |b| b.br; b.text! "HI" }   #=>  <p><br/>HI</p>
    # File lib/builder/xmlbase.rb, line 87
87:     def text!(text)
88:       _text(_escape(text))
89:     end

Private Instance Methods

_escape(text) click to toggle source
     # File lib/builder/xmlbase.rb, line 134
134:       def _escape(text)
135:         text.to_xs((@encoding != 'utf-8' or $KCODE != 'UTF8'))
136:       end
_escape(text) click to toggle source
     # File lib/builder/xmlbase.rb, line 122
122:       def _escape(text)
123:         result = XChar.encode(text)
124:         begin
125:           result.encode(@encoding)
126:         rescue
127:           # if the encoding can't be supported, use numeric character references
128:           result.
129:             gsub(/[^\u0000-\u007F]/) {|c| "&##{c.ord};"}.
130:             force_encoding('ascii')
131:         end
132:       end
_escape_quote(text) click to toggle source
     # File lib/builder/xmlbase.rb, line 139
139:     def _escape_quote(text)
140:       _escape(text).gsub(%{"}, '&quot;')  # " WART
141:     end
_indent() click to toggle source
     # File lib/builder/xmlbase.rb, line 148
148:     def _indent
149:       return if @indent == 0 || @level == 0
150:       text!(" " * (@level * @indent))
151:     end
_nested_structures(block) click to toggle source
     # File lib/builder/xmlbase.rb, line 153
153:     def _nested_structures(block)
154:       @level += 1
155:       block.call(self)
156:     ensure
157:       @level -= 1
158:     end
_newline() click to toggle source
     # File lib/builder/xmlbase.rb, line 143
143:     def _newline
144:       return if @indent == 0
145:       text! "\n"
146:     end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.