wlang 0.8.4

data/lib/wlang/dialects/xhtml_dialect.rb

@@ -0,0 +1,40 @@
+require 'cgi'
+module WLang
+  class EncoderSet
+    
+    # Defines encoders of the whtml dialect
+    module XHtml
+  
+      # Default encoders  
+      DEFAULT_ENCODERS = {"main-encoding"     => :entities_encoding,
+                          "single-quoting"    => :single_quoting,
+                          "double-quoting"    => :double_quoting,
+                          "entities-encoding" => :entities_encoding}
+  
+  
+      # Single-quoting encoding
+      def self.single_quoting(src, options); src.gsub(/([^\\])'/,%q{\1\\\'}); end
+  
+      # Double-quoting encoding
+      def self.double_quoting(src, options); src.gsub('"','\"'); end
+    
+      # Entities-encoding
+      def self.entities_encoding(src, options); 
+        CGI::escapeHTML(src)
+      end
+  
+    end # module XHtml  
+  end
+  class RuleSet
+    
+    # Defines rulset of the wlang/xhtml dialect
+    module XHtml
+    
+      # Default mapping between tag symbols and methods
+      DEFAULT_RULESET = {}
+  
+    end # module XHtml
+    
+  end
+end
+

data/lib/wlang/encoder.rb

@@ -0,0 +1,66 @@
+module WLang
+  
+  # 
+  # Encapsulates some encoding algorithm. This class is to EncoderSet what Rule
+  # is to RuleSet. Encoders are always installed on a EncoderSet (using EncoderSet#add_encoder), 
+  # which is itself installed on a Dialect. Note that the method mentionned previously 
+  # provides a DRY shortcut, allowing not using this class directly.
+  #  
+  # Example:
+  #    # Encoder subclassing can be avoided by providing a block to new
+  #    # The following encoder job is to upcase the text:
+  #    encoder = Encoder.new do |src,options|
+  #      src.upcase
+  #    end
+  #    
+  #    # It is even better to use the DSL
+  #    WLang::dialect("mydialect") do
+  #      # The following encoder job is to upcase the text and will be installed
+  #      # under mydialect/myupcaser qualified name 
+  #      encoder("myupcaser") do |src,options|
+  #        src.upcase
+  #      end
+  #    end
+  #
+  # Creating a a new encoder can be made in two ways: by subclassing this class and
+  # overriding the encoder method or by passing a block to new. In both cases,
+  # <b>encoders should always be stateless</b>, to allow reusable dialects that could
+  # even be used in a multi-threading environment.
+  #
+  # == Detailed API
+  class Encoder
+  
+    #
+    # Creates a new encoder. If no block is given, the invocation of new MUST be made 
+    # on a subclass overriding encoder. Otherwise, the block is considered as the 
+    # effective stateless implementation of encoder and will be called with the 
+    # same arguments. 
+    #
+    def initialize(&block)
+      unless block.nil?
+        raise(ArgumentError, "Expected a rule block of arity 2")\
+          unless block.arity==2
+      end
+      @block = block
+    end
+  
+    #
+    # Fired by the parser when a rule request encoding of some instantiated text.
+    # Typical example is the standard tag <tt>^{encoder/qualified/name}{...}</tt>
+    # (see WLang::RuleSet::Basic) which requires the second block instantiation to
+    # be encoded by the encoder whose qualified name is given by the first block.
+    # This method must simply return the encoded text. 
+    #
+    # Arguments:
+    # - src: source text to encode.
+    # - options: encoding options through a Hash. Available options are documented 
+    #   by encoders themselve. 
+    #
+    def encode(src, options)
+      raise(NotImplementedError) unless @block
+      @block.call(src, options)
+    end
+
+  end # class Encoder
+
+end

data/lib/wlang/encoder_set.rb

@@ -0,0 +1,117 @@
+require 'wlang/encoder'
+module WLang
+
+  #
+  # This class allows grouping encoders together to build a given dialect.
+  # Encoders are always added with add_encoder, which also allows creating simple 
+  # encoders on the fly (that is, without subclassing Encoder).
+  #
+  # Examples:
+  #   # we will create a simple encoder set with two encoders, one for upcasing
+  #   # the other for downcasing.
+  #   encoders = EncoderSet.new
+  #   encoder.add_encoder 'upcaser' do |src,options|
+  #     src.upcase
+  #   end 
+  #   encoder.add_encoder 'downcaser' do |src,options|
+  #     src.downcase
+  #   end 
+  #
+  # == Detailed API
+  class EncoderSet
+  
+    # Creates an empty encoder set.
+    def initialize
+      @encoders = {}
+    end
+  
+    #
+    # Adds an encoder under a specific name. Supported signatures are as follows:
+    # - _name_ is a symbol: _encoder_ and _block_ are ignored and encoder is 
+    #   interpreted as being a method of the String class whose name is the symbol. 
+    # - _name_ is a String and a block is provided: encoder is expected to be 
+    #   implemented by the block which takes |src,options| arguments.
+    # - _name_ is a String and _encoder_ is a Proc: same as if _encoder_ was a
+    #   given block.
+    #
+    # Examples:
+    #   encoders = EncoderSet.new
+    #   # add an encoder by reusing String method
+    #   encoders.add_encoder(:upcase)
+    #
+    #   # add an encoder by providing a block
+    #   encoders.add_encoder("ucase") do |src,options|
+    #     src.upcase
+    #   end
+    #
+    #   # add an encoder by providing a Proc
+    #   upcaser = Proc.new {|src,options| src.upcase}
+    #   encoders.add_encoder("upcase", upcaser) 
+    #
+    def add_encoder(name, encoder=nil, &block)
+      # handle String method through symbol 
+      if Symbol===name 
+        encoder, block = nil, Proc.new {|src,options| src.send(name)}
+        name = name.to_s
+      elsif Proc===encoder
+        encoder, block = nil, encoder
+      end
+    
+      # check arguments
+      if encoder.nil? 
+        raise(ArgumentError,"Block required") if block.nil?
+        encoder = Encoder.new(&block)
+      end
+      raise(ArgumentError, "Encoder expected") unless Encoder===encoder
+        
+      # save encoder
+      @encoders[name] = encoder
+    end
+  
+    #
+    # Adds reusable encoders defined in a Ruby module. _mod_ must be a Module instance.
+    # If _pairs_ is ommitted (nil), all encoders of the module are added, under their
+    # standard names (see DEFAULT_ENCODERS under WLang::EncoderSet::XHtml for example).
+    # Otherwise, _pairs_ is expected to be a Hash providing a mapping between encoder 
+    # names and _mod_ methods (whose names are given by ruby symbols).  
+    #
+    def add_encoders(mod, pairs=nil)
+      raise(ArgumentError,"Module expected",caller) unless Module===mod
+      pairs = mod::DEFAULT_ENCODERS if pairs.nil?
+      pairs.each_pair do |name,method|
+        meth = mod.method(method)
+        raise(ArgumentError,"No such method: #{method} in #{mod}") if meth.nil?
+        add_encoder(name, &meth.to_proc)
+      end
+    end
+
+    # Checks if an encoder is installed under _name.
+    def has_encoder?(name) 
+      @encoders.has_key?(name)
+    end
+  
+    # Returns an encoder by its name, nil if no such encoder.
+    def get_encoder(name)
+      @encoders[name]
+    end
+  
+    #
+    # Shortcut for <tt>get_encoder(encoder).encode(source,options)</tt>
+    # 
+    def encode(encoder, src, options=nil)
+      if String===encoder then 
+        ename, encoder = encoder, get_encoder(encoder) 
+        raise(ArgumentError,"No such encoder: #{ename}") if encoder.nil?
+      end
+      raise(ArgumentError,"Invalid encoder: #{encoder}") unless Encoder===encoder
+      encoder.encode(src, options)
+    end
+
+    # Returns a string with comma separated encoder names. 
+    def to_s
+      @encoders.keys.join(", ")
+    end
+  
+  end # class EncoderSet
+
+end

data/lib/wlang/errors.rb

@@ -0,0 +1,37 @@
+module WLang
+  
+  # Main error of all WLang errors.
+  class Error < StandardError; end
+  
+  # Error raised by a WLang parser instanciation when an error occurs. 
+  class ParseError < StandardError; 
+
+    attr_reader :line, :column
+
+    # Creates an error with offset information
+    def initialize(message, offset=nil, template=nil)
+      @offset = offset
+      @line, @column = parse(template) if template
+      unless template and offset
+        super(message) 
+      else
+        super("ParseError at #{@line}:#{@column} : #{message}")
+      end
+      
+    end
+    
+    # Reparses the template and finds line:column locations
+    def parse(template)
+      template = template[0,@offset]
+      if template =~ /\n/ then
+        lines = template[0,@offset].split(/\n/)
+      else 
+        lines = [template]
+      end
+      line, column = lines.length, lines.last.length
+      return [line, column]
+    end
+    
+  end # class ParseError
+  
+end # module WLang

data/lib/wlang/intelligent_buffer.rb

@@ -0,0 +1,94 @@
+module WLang
+  
+  # Provides an intelligent output buffer
+  class IntelligentBuffer < String
+    
+    # Some string utilities
+    module Methods
+
+      # Aligns _str_ at left offset _n_
+      # Credits: Treetop and Facets 2.0.2
+      def tabto(str, n)
+        if str =~ /^( *)\S/
+          indent(str, n - $1.length)
+        else
+          str
+        end
+      end
+
+      # Positive or negative indentation of _str_
+      # Credits: Treetop and Facets 2.0.2
+      def indent(str, n)
+        if n >= 0
+          str.gsub(/^/, ' ' * n)
+        else
+          str.gsub(/^ {0,#{-n}}/, "")
+        end
+      end
+
+      # Checks if _str_ contains multiple lines
+      def is_multiline?(str)
+        str =~ /\n/ ? true : false
+      end
+    
+      #
+      # Strips a multiline block.
+      #
+      # Example:
+      #   ([\t ]*\n)?
+      #   ([\t ]\n)*
+      #   [\t ]*some text here\n
+      #   [\t ]*  indented also\n?
+      #   [\t ]*
+      #
+      # becomes:
+      #   some text here\n
+      #     indented also\n
+      #
+      def strip_block(str)
+        match = str.match(/\A[\t ]*\n?/)
+        str = match.post_match if match
+        match = str.match(/\n[\t ]*\Z/)
+        str = (match.pre_match << "\n") if match
+        str
+      end
+      
+      # Returns column number of a specific offset
+      # Credits: Treetop and Facets 2.0.2
+      def column_of(str, index)
+        return 1 if index == 0
+        newline_index = str.rindex("\n", index - 1)
+        if newline_index
+          index - newline_index
+        else
+          index + 1
+        end
+      end
+      
+      # Returns the column of the last character
+      def last_column(str)
+        column_of(str, str.length)
+      end
+    
+      # Pushes a string, aligning it first
+      def <<(str, block=false)
+        if block and is_multiline?(str) and stripped = strip_block(str)
+          str = tabto(stripped, last_column(self)-1)
+          str = str.match(/\A[\t ]*/).post_match
+        end
+        super(str)
+      end
+    
+      # WLang explicit appending
+      def wlang_append(str, block)
+        self.<<(str, block)
+      end
+    
+    end
+    
+    # Include utilities
+    include Methods
+    
+  end
+  
+end

data/lib/wlang/parser.rb

@@ -0,0 +1,251 @@
+require 'stringio'
+require 'wlang/rule'
+require 'wlang/rule_set'
+require 'wlang/errors'
+require 'wlang/template'
+module WLang
+
+  #
+  # Parser for wlang templates.
+  #
+  # This class implements the parsing algorithm of wlang, recognizing special tags
+  # and replacing them using installed rules. Instanciating a template is done 
+  # using instantiate. All other methods (parse, parse_block, has_block?) and the 
+  # like are callbacks for rules and should not be used by users themselve.
+  #
+  # Obtaining a parser MUST be made through Parser.instantiator (new is private).
+  #
+  # == Detailed API
+  class Parser
+
+    # Factors a parser instance for a given template and an output buffer. 
+    def self.instantiator(template, buffer=nil)
+      Parser.send(:new, nil, template, nil, 0, buffer)
+    end
+  
+    # Current parsed template
+    attr_reader :template
+  
+    # Current execution context
+    attr_reader :context
+  
+    # Current buffer
+    attr_reader :buffer
+  
+    #
+    # Initializes a parser instance. _parent_ is the Parser instance of the higher
+    # parsing stage. _template_ is the current instantiated template, _offset_ is
+    # where the parsing must start in the template and _buffer_ is the output buffer
+    # where the instantiation result must be pushed.
+    #
+    def initialize(parent, template, dialect, offset, buffer)
+      raise(ArgumentError, "Template is mandatory") unless WLang::Template===template
+      raise(ArgumentError, "Offset is mandatory") unless Integer===offset
+      dialect = template.dialect if dialect.nil?
+      buffer = dialect.factor_buffer if buffer.nil?
+      raise(ArgumentError, "Buffer is mandatory") unless buffer.respond_to?(:<<)
+      @parent = parent
+      @template = template
+      @context = template.context
+      @offset = offset
+      @dialect = dialect
+      @buffer = buffer
+    end
+    
+    # Factors a specific buffer on the current dialect
+    def factor_buffer
+      @dialect.factor_buffer
+    end
+    
+    # Appends on a given buffer
+    def append_buffer(buffer, str, block)
+      if buffer.respond_to?(:wlang_append)
+        buffer.wlang_append(str, block)
+      else
+        buffer << str
+      end
+    end
+  
+    # Pushes a given string on the output buffer
+    def <<(str, block)
+      append_buffer(@buffer, str, block)
+    end
+
+    # Parses the text
+    def instantiate
+      # Main variables:
+      # - offset: matching current position
+      # - rules: handlers of '{' currently opened
+      offset, pattern, rules = @offset, @dialect.pattern(@template.block_symbols), []
+      @source_text = template.source_text
+    
+      # we start matching everything in the ruleset
+      while match_at=@source_text.index(pattern,offset)
+        match, match_length = $~[0], $~[0].length
+      
+        # puts pre_match (we can't use $~.pre_match !)
+        self.<<(@source_text[offset, match_at-offset], false) if match_at>0
+      
+        if @source_text[match_at,1]=='\\'           # escaping sequence
+          self.<<(match[1..-1], false)
+          offset = match_at + match_length
+        
+        elsif match.length==1               # simple '{' or '}' here
+          offset = match_at + match_length
+          if match==Template::BLOCK_SYMBOLS[template.block_symbols][0]
+            self.<<(match, false)  # simple '{' are always pushed
+            # we push '{' in rules to recognize it's associated '}'
+            # that must be pushed on buffer also
+            rules << match   
+          else
+            # end of my job if I can't pop a previous rule
+            break if rules.empty?
+            # otherwise, push '}' only if associated to a simple '{'
+            self.<<(match, false) unless Rule===rules.pop
+          end
+        
+        elsif match[-1,1]==Template::BLOCK_SYMBOLS[template.block_symbols][0] # opening special tag
+          # following line should never return nil as the matching pattern comes 
+          # from the ruleset itself!
+          rule = @dialect.ruleset[match[0..-2]]     
+          rules << rule
+        
+          # lauch that rule, get it's replacement and my new offset
+          replacement, offset = rule.start_tag(self, match_at + match_length)
+          replacement = "" if replacement.nil?
+          raise "Bad implementation of rule #{match[0..-2]}" if offset.nil?
+        
+          # push replacement
+          self.<<(replacement, true) unless replacement.empty?
+        end
+      
+      end  # while match_at=...
+    
+      # trailing data (end of @template reached only if no match_at)
+      unless match_at
+        unexpected_eof(@source_text.length, '}') unless rules.empty?
+        self.<<(@source_text[offset, 1+@source_text.length-offset], false)
+        offset = @source_text.length
+      end
+      [@buffer, offset-1]
+    end
+  
+    #
+    # Evaluates a ruby expression on the current context. 
+    # See WLang::Parser::Context#evaluate.
+    #
+    def evaluate(expression)
+      @context.evaluate(expression)
+    end
+  
+    #
+    # Launches a child parser for instantiation at a given _offset_ in given 
+    # _dialect_ (same dialect than self if dialect is nil) and with an output 
+    # _buffer_.
+    #
+    def parse(offset, dialect=nil, buffer=nil)
+      if dialect.nil?
+        dialect = @dialect
+      elsif String===dialect
+        dname, dialect = dialect, WLang::dialect(dialect)
+        raise(ParseError,"Unknown modulation dialect: #{dname}") if dialect.nil?
+      elsif not(Dialect===dialect)
+        raise(ParseError,"Unknown modulation dialect: #{dialect}")
+      end
+      Parser.send(:new, self, @template, dialect, offset, buffer).instantiate 
+    end
+  
+    # 
+    # Checks if a given offset is a starting block. For easy implementation of rules
+    # the check applied here is that text starting at _offset_ in the template is precisely
+    # '}{' (the reason for that is that instantiate, parse, parse_block always stop 
+    # parsing on a '}')
+    #
+    def has_block?(offset)
+      @source_text[offset,2]=='}{'
+    end
+  
+    #
+    # Parses a given block starting at a given _offset_, expressed in a given 
+    # _dialect_ and using an output _buffer_. This method raises a ParseError if
+    # there is no block at the offset. It implies that we are on a '}{', see 
+    # has_block? for details. Rules may thus force mandatory block parsing without 
+    # having to check anything. Optional blocks must be handled by rules themselve.
+    #
+    def parse_block(offset, dialect=nil, buffer=nil)
+      block_missing_error(offset+2) unless has_block?(offset)
+      parse(offset+2, dialect, buffer)
+    end
+  
+    #
+    # Encodes a given text using an encoder, that may be a qualified name or an
+    # Encoder instance.
+    #
+    def encode(src, encoder, options=nil)
+      options = {} unless options
+      options['_encoder_'] = encoder
+      options['_template_'] = template
+      if String===encoder
+        if encoder.include?("/")
+          ename, encoder = encoder, WLang::encoder(encoder)
+          raise(ParseError,"Unknown encoder: #{ename}") if encoder.nil?
+        else
+          ename, encoder = encoder, @dialect.find_encoder(encoder)
+          raise(ParseError,"Unknown encoder: #{ename}") if encoder.nil?
+        end
+      elsif not(Encoder===encoder)
+        raise(ParseError,"Unknown encoder: #{encoder}")
+      end
+      encoder.encode(src, options)
+    end
+  
+    #
+    # Raises a ParseError at a given offset.
+    #
+    def syntax_error(offset, msg=nil)
+      text = self.parse(offset, "wlang/dummy", "")
+      raise ParseError, "Parse error at #{offset} on '#{text}': #{msg}"
+    end
+  
+    #
+    # Raises a ParseError at a given offset for a missing block
+    #
+    def block_missing_error(offset)
+      raise ParseError.new("Block expected", offset, @source_text)
+    end
+  
+    #
+    # Raises a ParseError at a given offset for a unexpected EOF
+    # specif. the expected character when EOF found
+    #
+    def unexpected_eof(offset, expected)
+      raise ParseError.new("'#{expected}' expected, EOF found.", offset, @source_text)
+    end
+  
+    #
+    # Puts a key/value pair in the current context. See Parser::Context::define
+    # for details.
+    #
+    def context_define(key, value)
+      @context.define(key,value)
+    end
+
+    #    
+    # Pushes a new scope on the current context stack. See Parser::Context::push
+    # for details.
+    #
+    def context_push(context)
+      @context.push(context)
+    end
+
+    #  
+    # Pops the top scope of the context stack. See Parser::Context::pop for details.
+    #
+    def context_pop
+      @context.pop
+    end
+  
+    private_class_method :new
+  end # class Parser
+
+end # module WLang