srdperu-prawn-format 0.1.1.1

data/lib/prawn/format/lexer.rb

@@ -0,0 +1,240 @@
+# encoding: utf-8
+
+require 'strscan'
+
+module Prawn
+  module Format
+
+    # The Lexer class is used by the formatting subsystem to scan a string
+    # and extract tokens from it. The tokens it looks for are either text,
+    # XML entities, or XML tags.
+    #
+    # Note that the lexer only scans for a subset of XML--it is not a true
+    # XML scanner, and understands just enough to provide a basic markup
+    # language for use in formatting documents.
+    #
+    # The subset includes only XML entities and tags--instructions, comments,
+    # and the like are not supported.
+    class Lexer
+      # When the scanner encounters a state or entity it is not able to
+      # handle, this exception will be raised.
+      class InvalidFormat < RuntimeError; end
+
+      # Controls whether whitespace is lexed verbatim or not. If not,
+      # adjacent whitespace is compressed into a single space character
+      # (this includes newlines).
+      attr_accessor :verbatim
+
+      # Create a new lexer that will scan the given text. The text must be
+      # UTF-8 encoded, and must consist of well-formed XML in the subset
+      # understand by the lexer.
+      def initialize(text)
+        @scanner = StringScanner.new(text)
+        @state = :start
+        @verbatim = false
+      end
+
+      # Returns the next token from the scanner. If the end of the string
+      # has been reached, this will return nil. Otherwise, the token itself
+      # is returned as a hash. The hash will always include a :type key,
+      # identifying the type of the token. It will be one of :text, :open,
+      # or :close.
+      #
+      # For :text tokens, the hash will also contain a :text key, which will
+      # point to an array of strings. Each element of the array contains
+      # either word, whitespace, or some other character at which the line
+      # may be broken.
+      #
+      # For :open tokens, the hash will contain a :tag key which identifies
+      # the name of the tag (as a symbol), and an :options key, which
+      # is another hash that contains the options that were given with the
+      # tag.
+      #
+      # For :close tokens, the hash will contain only a :tag key.
+      def next
+        if @state == :start && @scanner.eos?
+          return nil
+        else
+          scan_next_token
+        end
+      end
+
+      # Iterates over each token in the string, until the end of the string
+      # is reached. Each token is yielded. See #next for a discussion of the
+      # available token types.
+      def each
+        while (token = next_token)
+          yield token
+        end
+      end
+
+      private
+
+        def scan_next_token
+          case @state
+          when :start then scan_start_state
+          when :self_close then scan_self_close_state
+          end
+        end
+
+        if RUBY_VERSION >= "1.9.0"
+          def scan_other_text
+            @scanner.scan(/[^-\xE2\x80\x94\s<&]+/)
+          end
+        else
+          def scan_other_text
+            return nil if @scanner.eos?
+
+            result = @scanner.scan_until(/[-\s<&]|\xE2\x80\x94/)
+            if result
+              @scanner.pos -= @scanner.matched.length
+              return nil if result == "<" || result == "&"
+              return result[0,result.length - @scanner.matched.length]
+            else
+              result = @scanner.rest
+              @scanner.terminate
+              return result
+            end
+          end
+        end
+
+        def scan_text_chunk
+          @scanner.scan(/-/)            || # hyphen
+          @scanner.scan(/\xe2\x80\x94/) || # mdash
+          scan_other_text
+        end
+
+        def scan_verbatim_text_chunk
+          @scanner.scan(/\r\n|\r|\n/) || # newline
+          @scanner.scan(/\t/)         || # tab
+          @scanner.scan(/ +/)         || # spaces
+          scan_text_chunk
+        end
+
+        def scan_nonverbatim_text_chunk
+          (@scanner.scan(/\s+/) && " ") || # whitespace
+          scan_text_chunk
+        end
+
+        def scan_next_text_chunk
+          if @verbatim
+            scan_verbatim_text_chunk
+          else
+            scan_nonverbatim_text_chunk
+          end
+        end
+
+        def scan_start_state
+          if @scanner.scan(/</)
+            if @scanner.scan(%r(/))
+              scan_end_tag
+            else
+              scan_open_tag
+            end
+          elsif @scanner.scan(/&/)
+            scan_entity
+          else
+            pieces = []
+            loop do
+              chunk = scan_next_text_chunk or break
+              pieces << chunk
+            end
+            { :type => :text, :text => pieces }
+          end
+        end
+                  
+        ENTITY_MAP = {
+          "lt"    => "<",
+          "gt"    => ">",
+          "amp"   => "&",
+          "mdash" => "\xE2\x80\x94",
+          "ndash" => "\xE2\x80\x93",
+          "nbsp"  => "\xC2\xA0",
+          "bull"  => "\342\200\242",
+          "quot"  => '"',       
+          "trade"  => '™',     
+          "iexcl"  => '¡',                         
+          "cent"  => '¢',       
+          "pound"  => '£',     
+          "curren"  => '¤',   
+          "copy"  => '©',   
+          "aacute"  => 'á', 
+          "eacute"  => 'é', 
+          "iacute"  => 'í', 
+          "oacute"  => 'ó', 
+          "uacute"  => 'ú',
+          "Aacute"  => 'Á', 
+          "Eacute"  => 'É', 
+          "Iacute"  => 'Í', 
+          "Oacute"  => 'Ó', 
+          "Uacute"  => 'Ú',           
+          "ntilde"  => 'ñ',
+          "Ntilde"  => 'Ñ',                                                                       
+        }
+
+        def scan_entity
+          entity = @scanner.scan(/(?:#x?)?\w+/) or error("bad format for entity")
+          @scanner.scan(/;/) or error("missing semicolon to terminate entity")
+
+          text = case entity
+            when /#(\d+)/ then [$1.to_i].pack("U*")
+            when /#x([0-9a-f]+)/ then [$1.to_i(16)].pack("U*")
+            else
+              result = ENTITY_MAP[entity] or error("unrecognized entity #{entity.inspect}")
+              result.dup
+            end
+
+          { :type => :text, :text => [text] }
+        end
+
+        def scan_open_tag
+          tag = @scanner.scan(/\w+/) or error("'<' without valid tag")
+          tag = tag.downcase.to_sym
+
+          options = {}
+          @scanner.skip(/\s*/)
+          while !@scanner.eos? && @scanner.peek(1) =~ /\w/
+            name = @scanner.scan(/\w+/)
+            @scanner.scan(/\s*=\s*/) or error("expected assigment after option #{name}")
+            if (delim = @scanner.scan(/['"]/))
+              value = @scanner.scan(/[^#{delim}]*/)
+              @scanner.scan(/#{delim}/) or error("expected option value to end with #{delim}")
+            else
+              value = @scanner.scan(/[^\s>]*/)
+            end
+            options[name.downcase.to_sym] = value
+            @scanner.skip(/\s*/)
+          end
+
+          if @scanner.scan(%r(/))
+            @self_close = true
+            @tag = tag
+            @state = :self_close
+          else
+            @self_close = false
+            @state = :start
+          end
+
+          @scanner.scan(/>/) or error("unclosed tag #{tag.inspect}")
+
+          { :type => :open, :tag => tag, :options => options }
+        end
+
+        def scan_end_tag
+          tag = @scanner.scan(/\w+/).to_sym
+          @scanner.skip(/\s*/)
+          @scanner.scan(/>/) or error("unclosed ending tag #{tag.inspect}")
+          { :type => :close, :tag => tag }
+        end
+
+        def scan_self_close_state
+          @state = :start
+          { :type => :close, :tag => @tag }
+        end
+
+        def error(message)
+          raise InvalidFormat, "#{message} at #{@scanner.pos} -> #{@scanner.rest.inspect[0,50]}..."
+        end
+    end
+  end
+end

data/lib/prawn/format/line.rb

@@ -0,0 +1,99 @@
+# encoding: utf-8
+
+module Prawn
+  module Format
+
+    class Line
+      attr_reader :source
+      attr_reader :instructions
+
+      def initialize(instructions, hard_break)
+        # need to remember the "source" instructions, because lines can
+        # pushed back onto the stack en masse when flowing into boxes,
+        # if a line is discovered to not fit. Thus, a line must preserve
+        # all instructions it was originally given.
+
+        @source = instructions
+        @hard_break = hard_break
+      end
+
+      def instructions
+        @instructions ||= begin
+          instructions = source.dup
+
+          # ignore discardable items at the end of lines
+          instructions.pop while instructions.any? && instructions.last.discardable?
+
+          consolidate(instructions)
+        end
+      end
+
+      def spaces
+        @spaces ||= begin
+          spaces = instructions.inject(0) { |sum, instruction| sum + instruction.spaces }
+          [1, spaces].max
+        end
+      end
+
+      def hard_break?
+        @hard_break
+      end
+
+      def width
+        instructions.inject(0) { |sum, instruction| sum + instruction.width }
+      end
+
+      # distance from top of line to baseline
+      def ascent
+        instructions.map { |instruction| instruction.ascent }.max || 0
+      end
+
+      # distance from bottom of line to baseline
+      def descent
+        instructions.map { |instruction| instruction.descent }.min || 0
+      end
+
+      def height(include_blank=false)
+        instructions.map { |instruction| instruction.height(include_blank) }.max
+      end
+
+      def draw_on(document, state, options={})
+        return if instructions.empty?
+
+        format_state = instructions.first.state
+
+        case(options[:align])
+        when :left
+          state[:dx] = 0
+        when :center
+          state[:dx] = (state[:width] - width) / 2.0
+        when :right
+          state[:dx] = state[:width] - width
+        when :justify
+          state[:dx] = 0
+          state[:padding] = hard_break? ? 0 : (state[:width] - width) / spaces
+          state[:text].word_space(state[:padding])
+        end
+
+        state[:dy] -= ascent
+
+        state[:text].move_to(state[:dx], state[:dy])
+        state[:line] = self
+
+        document.save_font do
+          instructions.each { |instruction| instruction.draw(document, state, options) }
+          state[:pending_effects].each { |effect| effect.wrap(document, state) }
+        end
+
+        state[:dy] -= (options[:spacing] || 0) + (height - ascent)
+      end
+
+      private
+
+        def consolidate(list)
+          list.inject([]) { |l,i| i.accumulate(l) }
+        end
+    end
+
+  end
+end

data/lib/prawn/format/parser.rb

@@ -0,0 +1,181 @@
+# encoding: utf-8
+
+require 'prawn/format/instructions/text'
+require 'prawn/format/instructions/tag_open'
+require 'prawn/format/instructions/tag_close'
+require 'prawn/format/lexer'
+require 'prawn/format/line'
+require 'prawn/format/state'
+
+module Prawn
+  module Format
+
+    # The Parser class is used by the formatting subsystem to take
+    # the raw tokens from the Lexer class and wrap them in
+    # "instructions", which are then used by the LayoutBuilder to
+    # determine how each token should be rendered.
+    #
+    # The parser also ensures that tags are opened and closed
+    # consistently. It is not forgiving at all--if you forget to
+    # close a tag, the parser will raise an exception (TagError).
+    # 
+    # It will also raise an exception if a tag is encountered with
+    # no style definition for it.
+    class Parser
+      # This is the exception that gets raised when the parser cannot
+      # process a particular tag.
+      class TagError < RuntimeError; end
+
+      attr_reader :document
+      attr_reader :tags
+      attr_reader :state
+
+      # Creates a new parser associated with the given +document+, and which
+      # will parse the given +text+. The +options+ may include either of two
+      # optional keys:
+      #
+      # * :tags is used to specify the hash of tags and their associated
+      #   styles. Any tag not specified here will not be recognized by the
+      #   parser, and will cause an error if it is encountered in +text+.
+      # * :styles is used to specify the mapping of style classes to their
+      #   definitions. The keys should be symbols, and the values should be
+      #   hashes. The values have the same format as for the :tags map.
+      # * :style is the default style for any text not otherwise wrapped by
+      #   tags.
+      #
+      # Example:
+      #
+      #   parser = Parser.new(@pdf, "<b class='ruby'>hello</b>",
+      #       :tags => { :b => { :font_weight => :bold } },
+      #       :styles => { :ruby => { :color => "red" } },
+      #       :style => { :font_family => "Times-Roman" })
+      #
+      # See Format::State for a description of the supported style options.
+      def initialize(document, text, options={})
+        @document = document
+        @lexer = Lexer.new(text)
+        @tags = options[:tags] || {}
+        @styles = options[:styles] || {}
+
+        @state = State.new(document, :style => options[:style])
+        @lexer.verbatim = (@state.white_space == :pre)
+
+        @action = :start
+
+        @saved = []
+        @tag_stack = []
+      end
+
+      def verbatim?
+        @lexer.verbatim
+      end
+
+      # Returns the next instruction from the stream. If there are no more
+      # instructions in the stream (e.g., the end has been encountered), this
+      # returns +nil+.
+      def next
+        return @saved.pop if @saved.any?
+
+        case @action
+        when :start then start_parse
+        when :text  then text_parse
+        else raise "BUG: unknown parser action: #{@action.inspect}"
+        end
+      end
+
+      # "Ungets" the given +instruction+. This makes it so the next call to
+      # +next+ will return +instruction+. This is useful for backtracking.
+      def push(instruction)
+        @saved.push(instruction)
+      end
+
+      # This is identical to +next+, except it does not consume the
+      # instruction. This means that +peek+ returns the instruction that will
+      # be returned by the next call to +next+. It is useful for testing
+      # the next instruction in the stream without advancing the stream.
+      def peek
+        save = self.next
+        push(save) if save
+        return save
+      end
+
+      # Returns +true+ if the end of the stream has been reached. Subsequent
+      # calls to +peek+ or +next+ will return +nil+.
+      def eos?
+        peek.nil?
+      end
+
+      private
+
+        def start_parse
+          instruction = nil
+          while (@token = @lexer.next)
+            case @token[:type]
+            when :text
+              @position = 0
+              instruction = text_parse
+            when :open
+              instruction = process_open_tag
+            when :close
+              raise TagError, "closing #{@token[:tag]}, but no tags are open" if @tag_stack.empty?
+              raise TagError, "closing #{@tag_stack.last[:tag]} with #{@token[:tag]}" if @tag_stack.last[:tag] != @token[:tag]
+
+              instruction = Instructions::TagClose.new(@state, @tag_stack.pop)
+              @state = @state.previous
+            else
+              raise ArgumentError, "[BUG] unknown token type #{@token[:type].inspect} (#{@token.inspect})"
+            end
+
+            if instruction
+              if instruction.start_verbatim?
+                @lexer.verbatim = true
+              elsif instruction.end_verbatim?
+                @lexer.verbatim = false
+              end
+
+              return instruction
+            end
+          end
+
+          return nil
+        end
+
+        def text_parse
+          if @token[:text][@position]
+            @action = :text
+            @position += 1
+
+            text = @token[:text][@position - 1]
+            if @state.white_space == :pre && text =~ /(?:\r\n|\r|\n)/
+              Instructions::TagClose.new(@state, { :style => { :display => :break }, :options => {} })
+            else
+              Instructions::Text.new(@state, text)
+            end
+          else
+            @action = :start
+            start_parse
+          end
+        end
+
+        def process_open_tag
+          @tag_stack << @token
+          raise TagError, "undefined tag #{@token[:tag]}" unless @tags[@token[:tag]]
+          @token[:style] = @tags[@token[:tag]].dup
+
+          (@token[:options][:class] || "").split(/\s/).each do |name|
+            @token[:style].update(@styles[name.to_sym] || {})
+          end
+
+          if @token[:style][:meta]
+            @token[:style][:meta].each do |key, value|
+              @token[:style][value] = @token[:options][key]
+            end
+          end
+
+          @state = @state.with_style(@token[:style])
+          Instructions::TagOpen.new(@state, @token)
+        end
+    end
+
+  end
+end