wlang 0.8.4

data/lib/wlang/parser_context.rb

@@ -0,0 +1,146 @@
+require 'wlang/basic_object'
+module WLang
+  class Parser
+    
+    #
+    # Execution context of the Parser for <tt>!{wlang/hosted}</tt> and associated 
+    # tags. The execution context defines the semantics of executed code in those 
+    # tags as well as utilities to handle semantical scoping.
+    #
+    # TODO: define context and scoping semantics more precisely and extend the 
+    # documentation
+    #
+    class Context 
+  
+      # Common methods of scope instances
+      class Scope < WLang::BasicObject
+        attr_accessor :__parent
+    
+      end # module Scope
+  
+      # Hash scoping mechanism
+      class HashScope < Scope 
+        attr_reader :__hash
+    
+        # Decorates a hash as a scope.
+        def initialize(hash={}, parent=nil)
+          @__hash = hash
+          @__parent = parent
+        end
+        
+        def nil?
+          false
+        end
+        
+        def dup
+          HashScope.new(@__hash.dup, @__parent)
+        end
+        
+        def __branch(other)
+          HashScope.new(other, self)
+        end
+    
+        # Tries to convert found value to a given variable.
+        def method_missing(symbol, *args)
+          varname = symbol.to_s
+          if @__hash.has_key?(varname) 
+            @__hash[varname]
+          elsif @__parent
+            @__parent.method_missing(symbol, *args)
+          else
+            nil
+          end
+        end
+    
+        # Returns underlying object
+        def __underlying
+          return @__hash
+        end
+    
+        # See Scope#__evaluate
+        def __evaluate(expr)
+          self.instance_eval(expr)
+        end
+    
+        # See Scope#__define
+        def __define(key, value); 
+          @__hash[key]=value; 
+        end
+    
+        def /(symb)
+          s = symb.to_s
+          if  @__hash.has_key?(s)
+            return WLang::Parser::Context.to_scope(@__hash[s])
+          else 
+            return nil
+          end
+        end
+        
+        def inspect
+          "#{__underlying.inspect} with parent #{@__parent.inspect}"  
+        end
+    
+      end # class HashScope
+  
+      # Creates an empty context on an init scope object.
+      def initialize(init=nil)
+        if (Scope===init)
+          @current_scope = init
+        else 
+          @current_scope = HashScope.new
+          push(init) unless init.nil?
+        end
+      end
+  
+      # Evaluates a ruby expression on the current context.
+      def evaluate(expression)
+        if "self" == expression.strip
+          @current_scope
+        elsif /[a-z]+(\/[a-z]+)+/ =~ expression
+          expression = ("self/" + expression).gsub(/\//,"/:")
+          expr = @current_scope.__evaluate(expression)
+          expr = expr.__underlying if Scope===expr
+          return expr
+        else
+          @current_scope.__evaluate(expression)  
+        end
+      rescue Exception => ex
+        puts "Warning, some wlang exception when evaluating the expression\n#{expression}"
+        puts "Message was: #{ex.message}"
+        puts ex.backtrace.join("\n")
+        puts "Current scope was:\n"
+        puts @current_scope.__underlying.inspect
+        return nil
+      end
+  
+      # Pushes a new scope instance.
+      def push(who={})
+        who = WLang::Parser::Context.to_scope(who)
+        who.__parent = @current_scope
+        @current_scope = who
+      end
+  
+      # Pops the last added scope.
+      def pop
+        parent = @current_scope.__parent
+        raise "Bad scope usage, nothing to pop" if parent.nil?
+        @current_scope = parent
+      end
+  
+      # Defines a variable/value mapping in the current scope.
+      def define(key, value)
+        @current_scope.__define(key,value)
+      end
+  
+      # Converts a given instance to a Scope.
+      def self.to_scope(who)
+        return who if Scope===who
+        return who.to_wlang_scope if who.respond_to?(:to_wlang_scope)
+        return HashScope.new(who) if Hash===who
+        return who
+      end
+  
+    end # class Context
+
+  end
+end

data/lib/wlang/ruby_extensions.rb

@@ -0,0 +1,21 @@
+#
+# Installs _wlang_ utility methods on Ruby String. 
+#
+class String
+
+  # Converts the string to a wlang template
+  def wlang_template(dialect="wlang/active-string", context=nil, block_symbols=:braces)
+    WLang::Template.new(self, dialect, context, block_symbols)
+  end
+  
+  #
+  # Instantiates the string as a wlang template using
+  # a context object and a dialect.
+  #
+  def wlang_instantiate(context=nil, dialect="wlang/active-string", block_symbols=:braces)
+    wlang_template(dialect, context, block_symbols).instantiate
+  end
+  alias :wlang :wlang_instantiate
+    
+end
+

data/lib/wlang/rule.rb

@@ -0,0 +1,66 @@
+module WLang
+
+  #
+  # A Rule is designed to perform a replacement job when the special tag associated 
+  # with it is found in a Template. Rules are always installed on a RuleSet (using 
+  # RuleSet#add_rule), which is itself installed on a Dialect. Note that the method 
+  # mentionned previously provides a DRY shortcut, allowing not using this class 
+  # directly.
+  #  
+  # Example:
+  #    # Rule subclassing can be avoided by providing a block to new
+  #    # The following rule job is to upcase the text inside +{...} tags:
+  #    rule = Rule.new do |parser,offset|
+  #      parsed, reached = parser.parse(offset)
+  #      [parsed.upcase, reached]
+  #    end
+  #
+  # Creating a a new rule can be made in two ways: by subclassing this class and
+  # overriding the start_tag method or by passing a block to new. In both cases,
+  # <b>rules should always be stateless</b>, to allow reusable dialects that could
+  # even be used in a multi-threading environment. Implementing a rule correctly 
+  # must be considered non trivial due to the strong protocol between the parser 
+  # and its rules and the stateless convention. Always have a look to helpers 
+  # provided by RuleSet (to create simple rules easily) before deciding to implement
+  # a rule using this class.
+  #
+  # == Detailed API
+  class Rule
+
+    #
+    # Creates a new rule. If no block is given, the invocation of new MUST be made 
+    # on a subclass overriding start_tag. Otherwise, the block is considered as the 
+    # effective stateless implementation of start_tag 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 when the parser has reached an offset matching this rule.
+    #
+    # This method MUST return an array [_replacement_, _offset_] where _replacement_ 
+    # is what replaces the tag itself in the resulting text and _offset_ is the 
+    # new offset reached in the source text (where parsing will continue). 
+    # _offset_ should always be such that <tt>text[offset,1]=='}'</tt> to allow
+    # higher stages to continue their job correctly. Utility methods for parsing 
+    # text parts are provided by the parser itself (see WLang::Parser).
+    #
+    # Arguments:
+    # - parser: WLang parser currently parsing the text.
+    # - offset: offset reached in the text, corresponding to the first character
+    #   of the first block associated with the matching tag.
+    #
+    def start_tag(parser, offset)
+      raise(NotImplementedError) unless @block
+      @block.call(parser, offset)
+    end
+
+  end # class Rule
+
+end # module WLang

data/lib/wlang/rule_set.rb

@@ -0,0 +1,93 @@
+require 'wlang/rule'
+module WLang
+  
+  #
+  # This class allows grouping matching rules together to build a given dialect.
+  # Rules are always added with add_rule, which also allows creating simple rules 
+  # on the fly (that is, without subclassing Rule).
+  #
+  # Examples:
+  #   # we will create a simple dialect with a special tag:
+  #   #   <tt>+{...}</tt> which will uppercase its contents
+  #   upcaser = RuleSet.new
+  #   upcaser.add_rule '+' do |parser,offset|
+  #     parsed, offset = parser.parse(offset)
+  #     [parsed.upcase, offset] 
+  #   end 
+  #
+  # == Detailed API
+  class RuleSet
+
+    #
+    # Creates an new dialect rule set.
+    #    
+    def initialize() @rules, @pattern = {}, nil; end
+
+    #  
+    # Adds a tag matching rule to this rule set. _tag_ must be a String with the
+    # tag associated to the rule (without the '{', that is '$' for the tag ${...}
+    # for example. If rule is ommited and a block is given, a new Rule instance is 
+    # created on the fly with _block_ as implementation (see Rule#new). 
+    # Otherwise rule is expected to be a Rule instance. This method check its 
+    # arguments, raising an ArgumentError if incorrect. 
+    #
+    def add_rule(tag, rule=nil, &block) 
+      if rule.nil? 
+        raise(ArgumentError,"Block required") unless block_given?
+        rule = Rule.new(&block)
+      end
+      raise(ArgumentError, "Rule expected") unless Rule===rule
+      @rules[tag] = rule  
+      @pattern = nil 
+    end
+
+    #
+    # Add rules defined in a given RuleSet module.
+    #
+    def add_rules(mod, pairs=nil)
+      raise(ArgumentError,"Module expected") unless Module===mod
+      pairs = mod::DEFAULT_RULESET if pairs.nil?
+      pairs.each_pair do |symbol,method|
+        meth = mod.method(method)
+        raise(ArgumentError,"No such method: #{method}") if meth.nil?
+        add_rule(symbol, &meth.to_proc)
+      end
+    end
+  
+    #
+    # Returns a Regexp instance with recognizes all tags installed in the rule set.
+    # The returned Regexp is backslashing aware (it matches <tt>\${</tt> for example)
+    # as well as '{' and '}' aware. This pattern is used by WLang::Parser and is
+    # not intended to be used by users themselve.
+    # 
+    def pattern(block_symbols) 
+      build_pattern(block_symbols); 
+    end
+
+    #
+    # Returns the Rule associated with a given tag, _nil_ if no such rule.
+    #
+    def [](tag) @rules[tag];  end
+  
+    
+    ### protected section ######################################################
+    protected
+  
+    # Internal implementation of pattern.
+    def build_pattern(block_symbols)
+      start, stop = WLang::Template::BLOCK_SYMBOLS[block_symbols]
+      start, stop = Regexp.escape(start), Regexp.escape(stop)
+      s = '([\\\\]{0,2}('
+      i=0
+      @rules.each_key do |tag|
+        s << '|' if i>0
+        s << '(' << Regexp.escape(tag) << ')'
+        i += 1
+      end
+      s << ")#{start})|[\\\\]{0,2}#{start}|[\\\\]{0,2}#{stop}"
+      Regexp.new(s)
+    end
+  
+  end # class RuleSet
+
+end # module WLang

data/lib/wlang/rulesets/basic_ruleset.rb

@@ -0,0 +1,75 @@
+require 'wlang/rulesets/ruleset_utils'
+module WLang
+  class RuleSet
+    
+    #
+    # Basic ruleset, commonly included by any wlang dialect (but some tags, like
+    # <tt>${...}</tt> may be overriden). This ruleset is often installed conjointly
+    # with WLang::RuleSet::Encoding which provides interresting overridings of 
+    # <tt>${...}</tt> and <tt>+{...}</tt>. 
+    #
+    # For an overview of this ruleset, see the wlang {specification file}[link://files/specification.html].
+    #
+    module Basic
+      U=WLang::RuleSet::Utils
+  
+      # Default mapping between tag symbols and methods
+      DEFAULT_RULESET = {'!' => :execution, '%' => :modulation, '^' => :encoding,
+                         '+' => :inclusion, '$' => :injection, '%!' => :recursive_application}
+  
+      # Rule implementation of <tt>!{wlang/ruby}</tt>.
+      def self.execution(parser, offset)
+        expression, reached = parser.parse(offset, "wlang/ruby")
+        value = parser.evaluate(expression)
+        result = value.nil? ? "" : value.to_s
+        [result, reached]
+      end
+  
+      # Rule implementation of <tt>%{wlang/active-string}{...}</tt>.
+      def self.modulation(parser, offset)
+        dialect, reached = parser.parse(offset, "wlang/active-string")
+        result, reached = parser.parse_block(reached, dialect)
+        [result, reached]
+      end
+  
+      # Rule implementation of <tt>^{wlang/active-string}{...}</tt>
+      def self.encoding(parser, offset)
+        encoder, reached = parser.parse(offset, "wlang/active-string")
+        result, reached = parser.parse_block(reached)
+        result = parser.encode(result, encoder)
+        [result, reached]
+      end
+    
+      # Rule implementation of <tt>${wlang/ruby}</tt>
+      def self.injection(parser, offset)
+        execution(parser, offset)
+      end
+  
+      # Rule implementation of <tt>+{wlang/ruby}</tt>
+      def self.inclusion(parser, offset)
+        execution(parser, offset)
+      end
+  
+      # Rule implementation of <tt>%!{wlang/ruby using ... with ...}</tt>
+      def self.recursive_application(parser, offset)
+        dialect, reached = parser.parse(offset, "wlang/active-string")
+        text, reached = parser.parse_block(reached)
+    
+        # decode expression
+        decoded = U.expr(:qdialect, 
+                         ["using", :expr, false], 
+                         ["with",  :with, false]).decode(dialect, parser)
+        parser.syntax_error(offset) if decoded.nil?
+    
+        # build context
+        context = U.context_from_using_and_with(decoded)
+    
+        # instantiate
+        instantiated = WLang::instantiate(text, context, decoded[:qdialect])
+        [instantiated, reached]
+      end
+  
+    end  # module Basic
+  
+  end
+end

data/lib/wlang/rulesets/buffering_ruleset.rb

@@ -0,0 +1,103 @@
+require 'wlang/rulesets/ruleset_utils'
+require 'fileutils'
+
+module WLang
+  class RuleSet
+    
+    #
+    # Buffering ruleset, providing special tags to load/instantiate accessible files
+    # and outputting instantiation results in other files. 
+    #
+    # For an overview of this ruleset, see the wlang {specification file}[link://files/specification.html].
+    #
+    module Buffering
+      U=WLang::RuleSet::Utils
+  
+      # Default mapping between tag symbols and methods
+      DEFAULT_RULESET = {'<<' => :input, '>>' => :output,
+                         '<<=' => :data_assignment, '<<+' => :input_inclusion}
+  
+      # Rule implementation of <tt><<{wlang/uri}</tt>
+      def self.input(parser, offset)
+        uri, reached = parser.parse(offset, "wlang/uri")
+        file = parser.template.file_resolve(uri, true)
+        [File.read(file), reached]
+      end
+  
+      # Rule implementation of <tt>>>{wlang/uri}</tt>
+      def self.output(parser, offset)
+        uri, reached = parser.parse(offset, "wlang/uri")
+        file = parser.template.file_resolve(uri, false)
+        dir = File.dirname(file)
+        FileUtils.mkdir_p(dir) unless File.exists?(dir)
+        File.open(file, "w") do |file|
+          text, reached = parser.parse_block(reached, nil, file)
+        end
+        ["", reached]
+      end
+    
+      # Rule implementation of <<={wlang/uri as x}{...}
+      def self.data_assignment(parser, offset)
+        uri, reached = parser.parse(offset, "wlang/uri")
+    
+        # decode expression
+        decoded = U.decode_uri_as(uri)
+        parser.syntax_error(offset) if decoded.nil?
+    
+        file = parser.template.file_resolve(decoded[:uri], true)
+        data = WLang::load_data(file)
+    
+        # handle two different cases
+        if parser.has_block?(reached)
+          parser.context_push(decoded[:variable] => data)
+          text, reached = parser.parse_block(reached)
+          parser.context_pop
+          [text, reached]
+        else
+          parser.context_define(decoded[:variable], data)
+          ["", reached]
+        end
+      end
+
+      # Rule implementation of <<+{wlang/uri with ...}
+      def self.input_inclusion(parser, offset)
+        uri, reached = parser.parse(offset, "wlang/uri")
+    
+        # decode expression
+        decoded = U.expr(:uri,
+                      ["using", :using, false],
+                      ["with",  :with, false]).decode(uri, parser)
+        parser.syntax_error(offset) if decoded.nil?
+        
+        # handle wit
+        context = nil
+        if decoded[:using]
+          raise "<<+ does not support multiple with for now." if decoded[:using].size != 1
+          context = decoded[:using][0]
+          raise "Unexpected nil context when duplicated" if context.nil?
+        else
+          context = {}
+        end
+        
+        # handle using now
+        if decoded[:with]
+          case context
+            when WLang::Parser::Context::HashScope
+              context = context.__branch(decoded[:with]) 
+            when Hash
+              context = context.merge(decoded[:with])
+            else
+              raise "Unexpected context #{context}"
+          end
+        end
+        
+        file = parser.template.file_resolve(decoded[:uri], true)
+        instantiated = WLang::file_instantiate(file, context)
+        [instantiated, reached]
+      end
+  
+
+    end # module Buffering
+    
+  end
+end