1  #!/usr/bin/env ruby
   2 
   3  #--
   4  # Copyright 2004 by Jim Weirich (jim@weirichhouse.org).
   5  # All rights reserved.
   6 
   7  # Permission is granted for use, copying, modification, distribution,
   8  # and distribution of modified versions of this work as long as the
   9  # above copyright notice is included.
  10  #++
  11 
  12  require 'builder/xmlmarkup'
  13 
  14  module Builder
  15 
  16    # Create a series of SAX-like XML events (e.g. start_tag, end_tag)
  17    # from the markup code.  XmlEvent objects are used in a way similar
  18    # to XmlMarkup objects, except that a series of events are generated
  19    # and passed to a handler rather than generating character-based
  20    # markup.
  21    #
  22    # Usage:
  23    #   xe = Builder::XmlEvents.new(handler)
  24    #   xe.title("HI")    # Sends start_tag/end_tag/text messages to the handler.
  25    #
  26    # Indentation may also be selected by providing value for the
  27    # indentation size and initial indentation level.
  28    #
  29    #   xe = Builder::XmlEvents.new(handler, indent_size, initial_indent_level)
  30    #
  31    # == XML Event Handler
  32    #
  33    # The handler object must expect the following events.
  34    #
  35    # [<tt>start_tag(tag, attrs)</tt>]
  36    #     Announces that a new tag has been found.  +tag+ is the name of
  37    #     the tag and +attrs+ is a hash of attributes for the tag.
  38    #
  39    # [<tt>end_tag(tag)</tt>]
  40    #     Announces that an end tag for +tag+ has been found.
  41    #
  42    # [<tt>text(text)</tt>]
  43    #     Announces that a string of characters (+text+) has been found.
  44    #     A series of characters may be broken up into more than one
  45    #     +text+ call, so the client cannot assume that a single
  46    #     callback contains all the text data.
  47    #
  48    class XmlEvents < XmlMarkup
  49      def text!(text)
  50        @target.text(text)
  51      end
  52 
  53      def _start_tag(sym, attrs, end_too=false)
  54        @target.start_tag(sym, attrs)
  55        _end_tag(sym) if end_too
  56      end
  57 
  58      def _end_tag(sym)
  59        @target.end_tag(sym)
  60      end
  61    end
  62 
  63  end