wlang 0.8.5 → 0.9.1

data/lib/wlang/hosted_language.rb

@@ -0,0 +1,146 @@
+module WLang
+  #
+  # Implements the hosted language abstraction of WLang. The hosted language is
+  # mainly responsible of evaluating expressions (see evaluate). This abstraction
+  # may be implemented by a user's own class, providing that it respected the 
+  # evaluate method specification.
+  #
+  # This default implementation implements the ruby hosted language. It works 
+  # with ::WLang::HostedLanguage::DSL, which uses instance_eval for evaluating
+  # the expression. Calls to missing methods (without parameter and block) are
+  # converted in scope lookups. The DSL class is strictly private, as it uses 
+  # a somewhat complex ruby introspection mechanism to ensure that scoping will
+  # not be perturbated by Kernel methods and Object private methods even if 
+  # additional gems are loaded later.
+  #
+  # If you want to intall low-priority variables and tools available in all wlang
+  # templates (global scoping) you can reopen the HostedLanguage class itself and
+  # override variable_missing. Note that "low-priority" means that these methods
+  # will be hidden if a user installs a variable with the same name in its template.
+  #
+  #   class WLang::HostedLanguage
+  #
+  #     # Low-priority now variable
+  #     def now
+  #       Time.now
+  #     end
+  #
+  #     # Low-priority variables are checked before raising an UndefinedVariableError
+  #     def variable_missing(name)
+  #       case name
+  #         when :who, ...
+  #           self.send(name)
+  #         else
+  #           raise ::WLang::UndefinedVariableError.new(nil, nil, nil, name)
+  #       end
+  #     end 
+  #
+  #   end
+  #
+  # This class is thread safe, meaning that the same hosting language instance may be 
+  # safely shared by concurrent wlang parsers. Extending or re-opening this class and using
+  # instance variables will make it non thread-safe.
+  #
+  class HostedLanguage
+    
+    # The hosted language DSL, interpreting expressions
+    class DSL
+      
+      # Methods that we keep
+      KEPT_METHODS = [ "__send__", "__id__", "instance_eval", "initialize", "object_id", 
+                       "singleton_method_added", "singleton_method_undefined", "method_missing",
+                       "__evaluate__", "knows?"]
+
+      class << self
+        def __clean_scope__
+          # Removes all methods that are not needed to the class
+          (instance_methods + private_instance_methods).each do |m|
+            m_to_s = m.to_s
+            undef_method(m_to_s.to_sym) unless ('__' == m_to_s[0..1]) or KEPT_METHODS.include?(m_to_s)
+          end
+        end
+      end
+      
+      # Creates a DSL instance for a given hosted language and 
+      # parser state
+      def initialize(hosted, parser_state)
+        @hosted, @parser_state = hosted, parser_state
+        class << self
+          __clean_scope__
+        end
+      end
+      
+      # Delegates the missing lookup to the current parser scope or raises an
+      # UndefinedVariableError (calls @hosted.variable_missing precisely)
+      def method_missing(name, *args, &block)
+        if @parser_state and args.empty? and block.nil?
+          if effname = knows?(name)
+            @parser_state.scope[effname]
+          else
+            @hosted.variable_missing(name)
+          end
+        else
+          super(name, *args, &block)
+        end
+      end
+    
+      # Checks if a variable is known in the current parser scope
+      def knows?(name)
+        if @parser_state.scope.has_key?(name)
+          name
+        elsif @parser_state.scope.has_key?(name.to_s) 
+          name.to_s
+        else
+          nil
+        end
+      end
+    
+      # Evaluates an expression
+      def __evaluate__(__expression__)
+        __result__ = instance_eval(__expression__)
+        
+        # backward compatibility with >= 0.8.4 where 'using self'
+        # was allowed. This will be removed in wlang 1.0.0
+        if __result__.object_id == self.object_id
+          Kernel.puts "Warning: using deprecated 'using self' syntax (#{@parser_state.where})\n"\
+                      "will be removed in wlang 1.0.0. Use 'share all', extends "\
+                      "::WLang::HostedLanguage::DSL with useful methods or create your own"\
+                      " hosted language."
+          __result__ = @parser_state.scope.to_h
+        end
+        
+        __result__
+      rescue ::WLang::Error => ex
+        ex.parser_state = @parser_state
+        ex.expression = __expression__ if ex.respond_to?(:expression=)
+        Kernel.raise ex
+      rescue Exception => ex
+        Kernel.raise ::WLang::EvalError.new(ex.message, @parser_state, __expression__, ex)
+      end
+      
+    end # class DSL
+    
+    #
+    # Called when a variable cannot be found (name is a Symbol object). This default
+    # implementation raises an UndefinedVariableError. This method is intended to be 
+    # overriden for handling such a situation more friendly or for installing 
+    # low-priority global variables (see class documentation).
+    #
+    def variable_missing(name)
+      raise ::WLang::UndefinedVariableError.new(nil, nil, nil, name)
+    end
+      
+    #
+    # Evaluates a given expression in the context of a given
+    # parser state.
+    #
+    # This method should always raise 
+    # - an UndefinedVariableError when a given template variable cannot be found.
+    # - an EvalError when something more severe occurs
+    #
+    def evaluate(expression, parser_state)
+      ::WLang::HostedLanguage::DSL.new(self, parser_state).__evaluate__(expression)
+    end
+    
+  end # class HostedLanguage
+end # module WLang

data/lib/wlang/parser.rb

@@ -4,7 +4,6 @@ require 'wlang/rule_set'
 require 'wlang/errors'
 require 'wlang/template'
 module WLang
-
   #
   # Parser for wlang templates.
   #
@@ -13,86 +12,143 @@ module WLang
   # 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)
+    # Initializes a parser instance.
+    def initialize(hosted, template, scope)
+      raise(ArgumentError, "Hosted language is mandatory (a ::WLang::HostedLanguage)") unless ::WLang::HostedLanguage===hosted
+      raise(ArgumentError, "Template is mandatory (a ::WLang::Template)") unless ::WLang::Template===template
+      raise(ArgumentError, "Scope is mandatory (a Hash)") unless ::Hash===scope
+      @state = ::WLang::Parser::State.new(self).branch(
+        :hosted   => hosted,
+        :template => template,
+        :dialect  => template.dialect,
+        :offset   => 0,
+        :shared   => :none,
+        :scope    => scope,
+        :buffer   => template.dialect.factor_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
+    
+    ###################################################################### Facade on the parser state
+    
+    # Returns the current parser state
+    def state(); @state; end
+    
+    # Returns the current template
+    def template() state.template; end
+    
+    # Returns the current buffer
+    def dialect() state.dialect; end
+    
+    # Returns the current template's source text
+    def source_text() state.template.source_text; end
+    
+    # Returns the current offset
+    def offset() state.offset; end
+
+    # Sets the current offset of the parser    
+    def offset=(offset) state.offset = offset; end
+    
+    # Returns the current buffer
+    def buffer() state.buffer; end
+    
+    # Returns the current hosted language
+    def hosted() state.hosted; end
+    
+    # Branches the current parser
+    def branch(opts = {}) 
+      raise ArgumentError, "Parser branching requires a block" unless block_given?
+      @state = @state.branch(opts)
+      result = yield(@state)
+      @state = @state.parent
+      result
     end
     
-    # Factors a specific buffer on the current dialect
-    def factor_buffer
-      @dialect.factor_buffer
+    ###################################################################### Facade on the file system
+    
+    # Resolves an URI throught the current template
+    def file_resolve(uri)
+      # TODO: refactor me to handle absolute URIs
+      template.file_resolve(uri)
     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
+    ###################################################################### Facade on wlang itself
+    
+    # Factors a template instance for a given file
+    def file_template(file, dialect = nil, block_symbols = :braces)
+      WLang::file_template(file, dialect, block_symbols)
+    end
+    
+    # Finds a real dialect instance from an argument (Dialect instance or 
+    # qualified name)
+    def ensure_dialect(dialect)
+      if 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    
+      dialect  
+    end
+    
+    # Finds a real ecoder instance from an argument (Encoder instance or
+    # qualified or unqualified name)
+    def ensure_encoder(encoder)
+      if String===encoder
+        if encoder.include?("/")
+          ename, encoder = encoder, WLang::encoder(encoder)
+          raise(ParseError,"Unknown encoder: #{ename}") if encoder.nil?
+        else
+          ename, encoder = encoder, self.dialect.find_encoder(encoder)
+          raise(ParseError,"Unknown encoder: #{ename}") if encoder.nil?
+        end
+      elsif not(Encoder===encoder)
+        raise(ParseError,"Unknown encoder: #{encoder}")
       end
+      encoder
     end
   
-    # Pushes a given string on the output buffer
-    def <<(str, block)
-      append_buffer(@buffer, str, block)
+    ###################################################################### Main parser methods
+    
+    # Checks the result of a given rule
+    def launch_rule(dialect, rule_symbol, rule, offset)
+      result = rule.start_tag(self, offset)
+      raise WLang::Error, "Bad rule implementation #{dialect.qualified_name} #{rule_symbol}{}\n#{result.inspect}"\
+        unless result.size == 2 and String===result[0] and Integer===result[1]
+      result
     end
-
-    # Parses the text
+  
+    # Parses the template's text and instantiate it
     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
+      # Main variables put in local scope for efficiency:
+      #   - template:     current parsed template
+      #   - source_text:  current template's source text
+      #   - offset:       matching current position
+      #   - pattern:      current dialect's regexp pattern
+      #   - rules:        handlers of '{' currently opened
+      template    = self.template
+      symbols     = self.template.block_symbols
+      source_text = self.source_text
+      dialect     = self.dialect
+      buffer      = self.buffer
+      pattern     = dialect.pattern(template.block_symbols)
+      rules       = []
     
       # we start matching everything in the ruleset
-      while match_at=@source_text.index(pattern,offset)
+      while match_at=source_text.index(pattern, self.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
+        self.<<(source_text[self.offset, match_at-self.offset], false) if match_at>0
       
-        if @source_text[match_at,1]=='\\'           # escaping sequence
+        if source_text[match_at,1]=='\\'           # escaping sequence
           self.<<(match[1..-1], false)
-          offset = match_at + match_length
+          self.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.offset = match_at + match_length
+          if match==Template::BLOCK_SYMBOLS[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
@@ -104,41 +160,35 @@ module WLang
             self.<<(match, false) unless Rule===rules.pop
           end
         
-        elsif match[-1,1]==Template::BLOCK_SYMBOLS[template.block_symbols][0] # opening special tag
+        elsif match[-1,1]==Template::BLOCK_SYMBOLS[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]]     
+          rule_symbol = match[0..-2]
+          rule = dialect.ruleset[rule_symbol]     
           rules << rule
         
+          # Just added to get the last position in case of an error
+          self.offset = match_at + match_length
+
           # 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?
-        
+          replacement, self.offset = launch_rule(dialect, rule_symbol, rule, self.offset)
+      
           # push replacement
           self.<<(replacement, true) unless replacement.empty?
         end
       
       end  # while match_at=...
     
-      # trailing data (end of @template reached only if no 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
+        unexpected_eof(source_text.length, '}') unless rules.empty?
+        self.<<(source_text[self.offset, 1+source_text.length-self.offset], false)
+        self.offset = source_text.length
       end
-      [@buffer, offset-1]
+      [buffer, self.offset-1]
     end
   
-    #
-    # Evaluates a ruby expression on the current context. 
-    # See WLang::Parser::Context#evaluate.
-    #
-    def evaluate(expression)
-      @context.evaluate(expression)
-    rescue Exception => ex
-      raise ::WLang::EvalError, "#{template.where(@offset)} evaluation of '#{expression}' failed", ex.backtrace
-    end
+    ###################################################################### Callbacks for rule sets
   
     #
     # Launches a child parser for instantiation at a given _offset_ in given 
@@ -146,15 +196,11 @@ module WLang
     # _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}")
+      dialect = ensure_dialect(dialect.nil? ? self.dialect : dialect)
+      buffer  = dialect.factor_buffer if buffer.nil?
+      branch(:offset => offset, :dialect => dialect, :buffer => buffer) do
+        instantiate
       end
-      Parser.send(:new, self, @template, dialect, offset, buffer).instantiate 
     end
   
     # 
@@ -164,7 +210,7 @@ module WLang
     # parsing on a '}')
     #
     def has_block?(offset)
-      @source_text[offset,2]=='}{'
+      self.source_text[offset,2]=='}{'
     end
   
     #
@@ -179,6 +225,54 @@ module WLang
       parse(offset+2, dialect, buffer)
     end
   
+    ###################################################################### Facade on the buffer
+  
+    # 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
+
+    ###################################################################### Facade on the scope
+  
+    # Yields the block in a new scope branch, pushing pairing values on it.
+    # Original scope is restored after that. Returns what the yielded block
+    # returned.
+    def branch_scope(pairing = {}, which = :all)
+      raise ArgumentError, "Parser.branch_scope expects a block" unless block_given?
+      branch(:scope => pairing, :shared => which) { yield }
+    end
+    
+    # Adds a key/value pair on the current scope.
+    def scope_define(key, value)
+      state.scope[key] = value
+    end
+
+    ###################################################################### Facade on the hosted language
+  
+    #
+    # Evaluates a ruby expression on the current context. 
+    # See WLang::Parser::Context#evaluate.
+    #
+    def evaluate(expression)
+      hosted.evaluate(expression, state)
+    end
+  
+    ###################################################################### Facade on the dialect
+  
+    # Factors a specific buffer on the current dialect
+    def factor_buffer
+      self.dialect.factor_buffer
+    end
+    
     #
     # Encodes a given text using an encoder, that may be a qualified name or an
     # Encoder instance.
@@ -187,20 +281,11 @@ module WLang
       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)
+      ensure_encoder(encoder).encode(src, options)
     end
   
+    ###################################################################### About errors
+
     # Raises an exception with a friendly message
     def error(offset, message)
       template.error(offset, message)
@@ -229,31 +314,9 @@ module WLang
     def unexpected_eof(offset, expected)
       template.parse_error(offset, "#{expected} expected, EOF found")
     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
+    
+    # Protected methods are...
+    protected :hosted, :offset, :source_text, :buffer, :dialect
+    
   end # class Parser
-
 end # module WLang