Class: Builder::XmlBase

### Home Classes Methods

### In Files

- lib/builder/xmlbase.rb

### Parent

BlankSlate

### Methods

- ::new
- #<<
- #method_missing
- #nil?
- #tag!
- #text!

### Files

- CHANGES
- MIT-LICENSE
- Rakefile
- builder-1.2.4.rdoc
- builder-2.0.0.rdoc
- builder-2.1.1.rdoc

### Class/Module Index

Quicksearch

- Builder
- Builder::BlankSlate
- Builder::IllegalBlockError
- Builder::XmlBase
- Builder::XmlEvents
- Builder::XmlMarkup
- BlankSlate
- Fixnum
- Kernel
- Module
- Object
- String
- Symbol

No matching classes.

# Builder::XmlBase

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

### Attributes

cache_method_calls[RW]

### 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 28
    def initialize(indent=0, initial=0, encoding='utf-8')
      @indent = indent
      @level  = initial
      @encoding = encoding.downcase
    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 112
    def <<(text)
      _text(text)
    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 that isn't cached.

    # File lib/builder/xmlbase.rb, line 86
    def method_missing(sym, *args, &block)
      cache_method_call(sym) if ::Builder::XmlBase.cache_method_calls
      tag!(sym, *args, &block)
    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 122
    def nil?
      false
    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 37
    def tag!(sym, *args, &block)
      text = nil
      attrs = nil
      sym = "#{sym}:#{args.shift}" if args.first.kind_of?(::Symbol)
      sym = sym.to_sym unless sym.class == ::Symbol
      args.each do |arg|
        case arg
        when ::Hash
          attrs ||= {}
          attrs.merge!(arg)
        when nil
          # do nothing
        else
          text ||= ''
          text << arg.to_s
        end
      end
      if block
        unless text.nil?
          ::Kernel::raise ::ArgumentError,
            "XmlMarkup cannot mix a text argument with a block"
        end
        _indent
        _start_tag(sym, attrs)
        _newline
        begin
          _nested_structures(block)
        ensure
          _indent
          _end_tag(sym)
          _newline
        end
      elsif text.nil?
        _indent
        _start_tag(sym, attrs, true)
        _newline
      else
        _indent
        _start_tag(sym, attrs)
        text! text
        _end_tag(sym)
        _newline
      end
      @target
    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 95
    def text!(text)
      _text(_escape(text))
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.