wlang 0.10.2 → 2.0.0.beta

data/lib/wlang/encoder.rb

@@ -1,62 +0,0 @@
-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)
-      @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

@@ -1,122 +0,0 @@
-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
-  
-    # Yields the block with name, encoder pairs
-    def each
-      @encoders.each_pair{|name,encoder| yield(name, encoder)}
-    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

@@ -1,80 +0,0 @@
-module WLang
-  
-  # Main error of all WLang errors.
-  class Error < StandardError
-    
-    # The parser state whe this error has been raised
-    attr_accessor :parser_state
-    
-    # Optional cause (other lower level exception)
-    attr_accessor :cause
-    
-    # Creates an error instance with a given parser state
-    def initialize(msg = nil, parser_state = nil, cause = nil)
-      raise ArgumentError, "msg expected to be nil or a String" unless (msg.nil? or String===msg)
-      raise ArgumentError, "parser_state expected to be nil or a State"\
-        unless (parser_state.nil? or ::WLang::Parser::State===parser_state)
-      super(msg)
-      @parser_state = parser_state
-      @cause = cause
-    end
-    
-    # Returns a friendly wlang backtrace
-    def wlang_backtrace
-      parser_state ? parser_state.backtrace : ["no backtrace information, sorry"]
-    end
-    
-  end # class Error
-  
-  #
-  # Raised by hosted languages when something fails during 
-  # evaluation.
-  #
-  class EvalError < ::WLang::Error
-    
-    # The expression whose evaluation failed
-    attr_accessor :expression
-    
-    # Creates an error instance with an optional expression that
-    # failed
-    def initialize(msg = nil, parser_state = nil, expression = nil, cause = nil)
-      super(msg, parser_state, cause)
-      @expression = expression
-    end
-    
-    def to_s
-      "Evaluation of #{@expression} failed, #{@cause ? @cause.message : ''}"
-    end
-    
-  end # class EvalError
-  
-  #
-  # Raised when a variable may not be found in the current 
-  # parser scope
-  #
-  class UndefinedVariableError < ::WLang::EvalError
-    
-    # Name of the variable that could not be found
-    attr_accessor :variable
-    
-    # Creates an error instance with an optional variable name
-    def initialize(msg = nil, parser_state = nil, expression = nil, variable = nil)
-      super(msg, parser_state, expression)
-      @variable = variable
-    end
-    
-    def to_s
-      "Unable to find variable #{@variable}"
-    end
-    
-  end # class UndefinedVariableError
-  
-  # Error raised by a WLang parser instanciation when an error occurs. 
-  class ParseError < ::WLang::Error
-    
-    # Where did the parsing failed
-    attr_accessor :line, :column
-    
-  end # class ParseError
-  
-end # module WLang

data/lib/wlang/ext/hash_methodize.rb

@@ -1,13 +0,0 @@
-class Hash
-  
-  # Allows using hash.key as a synonym for hash[:key] and
-  # hash['key']
-  def method_missing(name, *args, &block)
-    if args.empty? and block.nil?
-      self[name] || self[name.to_s]
-    else
-      super(name, *args, &block)
-    end
-  end
-  
-end

data/lib/wlang/ext/string.rb

@@ -1,44 +0,0 @@
-#
-# Installs _wlang_ utility methods on Ruby String. 
-#
-class String
-
-  # Converts the string to a wlang template
-  def wlang_template(dialect = "wlang/active-string", block_symbols = :braces)
-    WLang::template(self, dialect, 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::instantiate(self, context, dialect, block_symbols)
-  end
-  alias :wlang :wlang_instantiate
-  
-  # Computes the column number for a given offset in 
-  # this string
-  def __wlang_column_of(index)
-    return 1 if index == 0
-    newline_index = rindex("\n", index - 1)
-    if newline_index
-      index - newline_index
-    else
-      index + 1
-    end
-  end
-  
-  # Computes the line number for a given offset in 
-  # this string
-  def __wlang_line_of(index)
-    self[0...index].count("\n") + 1
-  end
-  
-  def __wlang_realign(offset, strip_first = false)
-    s = gsub(/^/, ' ' * offset)
-    strip_first ? s.gsub(/\A\s*/, "") : s
-  end
-  
-end
-       

data/lib/wlang/hash_scope.rb

@@ -1,89 +0,0 @@
-require 'delegate'
-module WLang
-  #
-  # Implements a scoping mechanism on top of a ruby hash (accessible through pairing). 
-  # Such a scope mimics hashses for has_key?, [] and []= methods. A scope has an 
-  # accessible parent. Scopes form a tree, the root being accessible using its 
-  # natural accessor. Scope lookup (has_key? and []) uses the hierarchy to find
-  # accessible variables.
-  #
-  # Branching a scope allows installing new variables that hide variables with the 
-  # same name in the parent scope. Branching is made easy through the branch methods
-  # that accepts a block, passing the child as first argument:
-  #
-  #   scope = HashScope.new(:name => 'wlang')
-  #   puts scope[:name]    # prints 'wlang'
-  #   scope.branch(:name => 'other') do |child|
-  #     puts child[:name]  # prints 'other'
-  #   end
-  #   puts scope[:name]    # prints 'wlang'
-  #
-  # This branching mechanism is intended to be used to keep a current scope as instance
-  # variable of a using class:
-  # 
-  #   # We create an initial scope at construction
-  #   def initialize
-  #     @scope = HashScope.new
-  #   end
-  #
-  #   # Appends the current scope with new key/value pairs. Yields the block
-  #   # with the new scope and restore the original one after that.
-  #   def do_something_with_a_new_scope(hash = {})
-  #     @scope = @scope.branch(:name => 'other')
-  #       yield if block_given?
-  #     @scope = @scope.parent
-  #   end
-  #
-  class HashScope
-    
-    # The parent scope, or nil if no such parent
-    attr_reader :parent
-    
-    # The key/value pairing inside this scope
-    attr_reader :pairing
-    
-    # Creates a scope instance with a parent and initial 
-    # pairing through a Hash
-    def initialize(pairing = nil, parent = nil)
-      raise ArgumentError, "Hash expected for pairing #{pairing.class} received" unless (pairing.nil? or Hash===pairing)
-      @pairing = pairing || {}
-      @parent = parent
-    end
-        
-    # Returns the root scope
-    def root
-      @root ||= (parent ? parent.root : self)
-    end
-    
-    # Checks if a key exists in this scope, delegating to
-    # parent if not found and allowed
-    def has_key?(key, delegate = true)
-      pairing.has_key?(key) || (!delegate.nil? && !parent.nil? && parent.has_key?(key))
-    end
-    
-    # Returns the value associated to a key, delegating to parent
-    # if not found and allowed
-    def [](key, delegate = true)
-      pairing.has_key?(key) ? pairing[key] : (delegate && parent && parent[key])
-    end
-    
-    # Associates a key to a value inside this scope
-    def []=(key, value)
-      pairing[key] = value
-    end
-    
-    # Creates a new child scope and returns it. If a block is given,
-    # yields the block with the child scope
-    def branch(pairing = nil)
-      child = HashScope.new(pairing, self)
-      yield child if block_given?
-      child
-    end
-    
-    # Converts this scope to a full hash with all variables
-    def to_h
-      parent ? parent.to_h.merge(pairing) : pairing.dup
-    end
-    
-  end # class HashScope
-end # module WLang

data/lib/wlang/hosted_language.rb

@@ -1,146 +0,0 @@
-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