wlang 0.8.4

data/doc/specification/symbols.wtpl

@@ -0,0 +1,16 @@
+<table class="symbols">
+  <tr>
+    <th class="name">name</th>
+    <th class="symbol">symbol</th>
+    <th class="meaning">meaning</th>
+    <th class="remark">remark</th>
+  </tr>
+  *{spec/symbols as s}{
+  <tr>
+	<td><em>${s/name}</em></td>
+	<td>${s/symbol}</td>
+	<td>${s/meaning}</td>
+	<td>${s/remark}</td>
+  </tr>
+}
+</table>

data/lib/wlang.rb

@@ -0,0 +1,186 @@
+require 'wlang/ruby_extensions'
+require 'stringio'
+require 'wlang/rule'
+require 'wlang/rule_set'
+require 'wlang/encoder_set'
+require 'wlang/dialect'
+require 'wlang/dialect_dsl'
+require 'wlang/dialect_loader'
+require 'wlang/parser'
+require 'wlang/parser_context'
+require 'wlang/intelligent_buffer'
+
+#
+# Main module of the _wlang_ code generator/template engine, providing a facade 
+# on _wlang_ tools. See also the Roadmap section of {README}[link://files/README.html] 
+# to enter the library.
+#
+module WLang
+  
+  # Current version of WLang
+  VERSION = "0.8.4".freeze
+  
+  # Reusable string for building dialect name based regexps  
+  DIALECT_NAME_REGEXP_STR = "[-a-z]+"
+  
+  #
+  # Regular expression for dialect names.
+  #
+  DIALECT_NAME_REGEXP = /^([-a-z]+)*$/
+  
+  # Reusable string for building dialect name based regexps  
+  QUALIFIED_DIALECT_NAME_REGEXP_STR = "[-a-z]+([\/][-a-z]+)*"
+  
+  #
+  # Regular expression for dialect qualified names. Dialect qualified names are 
+  # '/' seperated names, where a name is [-a-z]+. 
+  # Examples: wlang/xhtml/uri, wlang/plain-text, ...
+  #
+  QUALIFIED_DIALECT_NAME_REGEXP = /^[-a-z]+([\/][-a-z]+)*$/
+
+  # Reusable string for building encoder name based regexps  
+  ENCODER_NAME_REGEXP_STR = "[-a-z]+"
+  
+  #
+  # Regular expression for encoder names.
+  #
+  ENCODER_NAME_REGEXP = /^([-a-z]+)*$/
+  
+  #  
+  # Regular expression for encoder qualified names. Encoder qualified names are 
+  # '/' seperated names, where a name is [-a-z]+. 
+  # Examples: xhtml/entities-encoding, sql/single-quoting, ...
+  #
+  QUALIFIED_ENCODER_NAME_REGEXP = /^([-a-z]+)([\/][-a-z]+)*$/
+  
+  # Reusable string for building qualified encoder name based regexps  
+  QUALIFIED_ENCODER_NAME_REGEXP_STR = "[-a-z]+([\/][-a-z]+)*"
+  
+  #
+  # Provides installed {file extension => dialect} mappings. File extensions 
+  # (keys) contain the first dot (like .wtpl, .whtml, ...). Dialects (values) are 
+  # qualified names, not Dialect instances.
+  #
+  FILE_EXTENSIONS = {}
+
+  #
+  # Provides installed {file extension => data loader} mapping. File extensions 
+  # (keys) contain the first dot (like .wtpl, .whtml, ...). Data loades are 
+  # Proc instances that take a single |uri| argument.
+  #
+  DATA_EXTENSIONS = {}
+  
+  #  
+  # Main anonymous dialect. All installed dialects are children of this one, 
+  # which is anonymous because it does not appear in qualified names.
+  #
+  @dialect = Dialect.new("", nil)
+  
+  #
+  # Installs or query a dialect.
+  #
+  # <b>When called with a block</b>, this method installs a _wlang_ dialect under 
+  # _name_ (which cannot be qualified). Extensions can be provided to let _wlang_
+  # automatically recognize files that are expressed in this dialect. The block
+  # is interpreted as code in the dialect DSL (domain specific language, see 
+  # WLang::Dialect::DSL). Returns nil in this case.
+  #
+  # <b>When called without a block</b> this method returns a Dialect instance 
+  # installed under name (which can be a qualified name). Extensions are ignored
+  # in this case. Returns nil if not found, a Dialect instance otherwise.
+  #
+  def self.dialect(name, *extensions, &block)
+    if block_given?
+      raise "Unsupported qualified names in dialect installation"\
+        unless name.index('/').nil?
+      Dialect::DSL.new(@dialect).dialect(name, *extensions, &block).build!
+    else
+      @dialect.dialect(name)
+    end
+  end
+  
+  #
+  # Adds a data loader for file extensions.
+  #
+  def self.data_loader(*exts, &block)
+    raise(ArgumentError, "Block expected") unless block_given?
+    raise(ArgumentError, "Block of arity 1 expected") unless block.arity==1
+    exts.each do |ext|
+      DATA_EXTENSIONS[ext] = block
+    end
+  end
+  
+  #
+  # Loads data from a given URI. If _extension_ is omitted, tries to infer it
+  # from the uri, otherwise use it directly. Returns loaded data. 
+  #
+  def self.load_data(uri, extension=nil)
+    if extension.nil?
+      extension = File.extname(uri)
+      raise("Unable to infer data loader from #{uri}") if extension.nil?
+    end
+    loader = DATA_EXTENSIONS[extension]
+    raise("No data loader for #{extension}") if loader.nil?
+    loader.call(uri) 
+  end
+  
+  # Infers a dialect from a file extension
+  def self.infer_dialect(uri)
+    WLang::FILE_EXTENSIONS[File.extname(uri)]
+  end
+  
+  #
+  # Returns an encoder installed under a qualified name. Returns nil if not 
+  # found.
+  #
+  def self.encoder(name)
+    @dialect.encoder(name)
+  end
+
+  #
+  # Instantiates a template written in some _wlang_ dialect, using a given _context_
+  # (providing instantiation data). Returns instantiatiation as a String. If you want 
+  # to instantiate the template in a specific buffer (a file or console for example), 
+  # use Template. _template_ is expected to be a String and _context_ a Hash. To 
+  # know available dialects, see WLang::StandardDialects. <em>block_symbols</em> 
+  # can be <tt>:braces</tt> ('{' and '}' pairs), <tt>:brackets</tt> ('[' and ']' 
+  # pairs) or <tt>:parentheses</tt> ('(' and ')' pairs). 
+  #
+  # Examples:
+  #   WLang.instantiate "Hello ${who} !", {"who" => "Mr. Jones"}
+  #   WLang.instantiate "SELECT * FROM people WHERE name='{name}'", {"who" => "Mr. O'Neil"}, "wlang/sql"
+  #   WLang.instantiate "Hello $(who) !", {"who" => "Mr. Jones"}, "wlang/active-string", :parentheses
+  #
+  def self.instantiate(template, context=nil, dialect="wlang/active-string", block_symbols = :braces)
+    WLang::Template.new(template, dialect, context, block_symbols).instantiate
+  end
+  
+  #
+  # Instantiates a file written in some _wlang_ dialect, using a given _context_
+  # (providing instantiation data). Outputs instantiation in _buffer_ (any object
+  # responding to <tt><<</tt>, usually a IO; String is supported as well). If
+  # _dialect_ is nil, tries to infer it from the file extension; otherwise _dialect_ 
+  # is expected to be a qualified dialect name. See instantiate about <tt>block_symbols</tt>.
+  # Returns _buffer_.
+  #
+  # Examples:
+  #   Wlang.file_instantiate "template.wtpl", {"who" => "Mr. Jones"}
+  #   Wlang.file_instantiate "template.wtpl", {"who" => "Mr. Jones"}, STDOUT
+  #   Wlang.file_instantiate "template.xxx", {"who" => "Mr. Jones"}, STDOUT, "wlang/xhtml"
+  #
+  def self.file_instantiate(file, context=nil, buffer=nil, dialect=nil, block_symbols = :braces)
+    raise "File '#{file}' does not exists or is unreadable"\
+      unless File.exists?(file) and File.readable?(file)
+    if dialect.nil?
+      dialect = infer_dialect(file) if dialect.nil?
+      raise("No known dialect for file extension '#{File.extname(file)}'\n"\
+            "Known extensions are: " << WLang::FILE_EXTENSIONS.keys.join(", "))\
+        if dialect.nil?
+    end
+    t = WLang::Template.new(File.read(file), dialect, context, block_symbols)
+    t.source_file = file
+    t.instantiate(buffer)
+  end
+  
+end
+require 'wlang/dialects/standard_dialects'

data/lib/wlang/basic_object.rb

@@ -0,0 +1,19 @@
+module WLang
+  
+  #
+  # Provides an Object with all inherited instance methods removed.
+  #
+  class BasicObject
+
+    # Methods that we keep
+    KEPT_METHODS = ["__send__", "__id__", "instance_eval", "initialize", "object_id",
+                    :__send__, :__id__, :instance_eval, :initialize, :object_id]
+
+    # Removes all methods that are not needed to the class
+    (instance_methods + private_instance_methods).each do |m|
+      undef_method(m) unless KEPT_METHODS.include?(m)
+    end
+    
+  end # class BasicObject
+  
+end

data/lib/wlang/dialect.rb

@@ -0,0 +1,230 @@
+require 'wlang/encoder_set'
+require 'wlang/rule_set'
+module WLang
+
+  #
+  # Implements the _dialect_ abstraction (see {README}[link://files/README.html]).
+  # A dialect instance is a aggregation of encoders and ruleset (through EncoderSet
+  # and RuleSet classes). A dialect is also a node in the dialect tree and has a 
+  # qualified name through this tree. For example <tt>wlang/xhtml</tt> is the 
+  # qualified name of a <tt>xhtml</tt> dialect which is a child dialect of 
+  # <tt>wlang</tt>.
+  #
+  # Users are not intended to use this class directly. Use the Domain Specific 
+  # Language instead (see WLang::Dialect::DSL). 
+  #
+  # === For developers only
+  # In order to avoid having users to install all required gems of all dialects
+  # wlang implements a lazy load design pattern on the dialect tree, through the
+  # WLang::Dialect::DSL and WLang::Dialect::Loader classes. The former only creates
+  # Dialect instances as tree nodes (by chaining dialects through @parent) and 
+  # installs mapping with file extensions. Rules and encoders are not initially 
+  # installed (precisely: WLang::Dialect::DSL#require_ruby is simply ignored). 
+  # When a given dialect is needed by wlang it is first built (through the build!
+  # method and the WLang::Dialect::Loader class). 
+  # 
+  # Standard dialect obtention methods (WLang#dialect as well as WLang::Dialect#dialect)
+  # ensure that returned dialects are built. If you obtain dialects another way, 
+  # be sure that they are built before using them (is_built? and build! are your 
+  # friends to achive that goal).      
+  #
+  # Moreover, child dialects may require tools of their ancestors. The following 
+  # invariant should always be respected: if a dialect is built, all its ancestors
+  # are built as well. This invariant is not enforced by the build! method because 
+  # it is trivially respected by the way WLang::Dialect#dialect is implemented.   
+  #
+  class Dialect
+  
+    # Underlying ruleset
+    attr_reader :ruleset
+  
+    # Underlying encoders
+    attr_reader :encoders
+
+    # Dialect name
+    attr_reader :name
+    
+    # Parent dialect
+    attr_reader :parent
+    
+    #
+    # Creates a dialect instance. _builder_ block is a chunk of code of the DSL
+    # that will be executed twice: once at construction time to create sub dialects
+    # nodes and install file extensions and once at building time to install ruleset
+    # and encoders.
+    #
+    def initialize(name, parent, &builder)
+      @name, @parent = name, parent 
+      @builder, @built = builder, builder.nil?
+      @dialects = nil
+      @encoders = nil
+      @ruleset = nil
+      DSL.new(self).instance_eval(&builder) unless builder.nil?
+    end
+  
+    ### Lazy load mechanism ######################################################
+  
+    #
+    # Force the dialect to be built. Has no effect if it is already built. Invokes
+    # the DSL chunk of code through WLang::DSL::Loader otherwise.
+    #
+    def build!
+      unless is_built?
+        WLang::Dialect::Loader.new(self).instance_eval(&@builder)
+        @built = true
+      end
+      self
+    end
+
+    # Returns true if this dialect is already built, false otherwise.
+    def is_built?
+      return @built
+    end
+
+    
+    ### Installation #############################################################
+  
+    #
+    # Adds a child dialect under _name_. _name_ cannot be qualified and must be a 
+    # valid dialect name according to the wlang specification (see WLang::DIALECT_NAME_REGEXP).
+    # _child_ must be a Dialect instance. 
+    #
+    def add_child_dialect(name, child)
+      raise(ArgumentError, "Invalid dialect name") unless WLang::DIALECT_NAME_REGEXP =~ name
+      raise(ArgumentError, "Dialect expected") unless Dialect===child
+      @dialects = {} if @dialects.nil?
+      @dialects[name] = child
+    end
+  
+    # See EncoderSet#add_encoder
+    def add_encoder(name, &block)
+      @encoders = EncoderSet.new if @encoders.nil?
+      @encoders.add_encoder(name, &block)
+    end
+  
+    # See EncoderSet#add_encoders
+    def add_encoders(mod, pairs)
+      @encoders = EncoderSet.new if @encoders.nil?
+      @encoders.add_encoders(mod, pairs)
+    end
+  
+    # See RuleSet::add_rule
+    def add_rule(name, &block)
+      @ruleset = RuleSet.new if @ruleset.nil?
+      @ruleset.add_rule(name, &block)
+    end
+  
+    # See RuleSet::add_rules
+    def add_rules(mod, pairs)
+      @ruleset = RuleSet.new if @ruleset.nil?
+      @ruleset.add_rules(mod, pairs)
+    end
+  
+    ### Query API ################################################################
+  
+    # Returns qualified name of this dialect
+    def qualified_name
+      parentname = @parent.nil? ? "" : @parent.to_s
+      return ""==parentname ? @name : parentname + '/' + @name 
+    end
+  
+    #
+    # Finds a child dialect by name. _name_ can be a String denoting a qualified 
+    # name as well as an Array of strings, resulting from a qualified name split.
+    # This method should always be invoked on built dialects, it always returns nil
+    # otherwise. When found, returned dialect is automatically built as well as all 
+    # its ancestors. When not found, the method returns nil. 
+    #
+    def dialect(name)
+      # implement argument conventions
+      if String===name
+        raise(ArgumentError, "Invalid dialect name #{name}") unless WLang::QUALIFIED_DIALECT_NAME_REGEXP =~ name
+        name = name.split('/')
+      elsif not(Array===name)
+        raise(ArgumentError,"Invalid dialect name #{name}")
+      end
+    
+      # not built or no child at all
+      return nil if @dialects.nil?
+    
+      # get first child name and find it
+      child_name = name[0]
+      child_dialect = @dialects[child_name]
+    
+      if child_dialect.nil?
+        # unexisting, return nil
+        return nil
+      elsif name.length==1
+        # found and last of qualified name -> build it
+        return child_dialect.build!
+      else
+        # found but not last of qualified name -> build it and delegate
+        child_dialect.build!
+        return child_dialect.dialect(name[1..-1]) 
+      end
+    end
+  
+    #
+    # Finds an encoder by name.
+    #
+    def encoder(name)
+      # implement argument conventions
+      if String===name
+        raise(ArgumentError, "Invalid encoder name #{name}") unless WLang::QUALIFIED_ENCODER_NAME_REGEXP =~ name
+        name = name.split('/')
+      elsif not(Array===name)
+        raise(ArgumentError,"Invalid encoder name #{name}")
+      end
+    
+      # last name in qualified?
+      if name.length==1
+        # delegate to encoders
+        return nil if @encoders.nil?
+        return @encoders.get_encoder(name[0])
+      else
+        # find sub dialect, and delegate
+        child_name = name[0]
+        child_dialect = dialect(child_name)
+        if child_dialect.nil?
+          return nil
+        else
+          return child_dialect.encoder(name[1..-1]) 
+        end
+      end
+    end
+  
+    # Finds a encoder in dialect tree
+    def find_encoder(name)
+      raise(ArgumentError, "Invalid (relative) encoder name #{name}") unless String===name
+      raise(ArgumentError, "Invalid (relative) encoder name #{name}") if name.include?("/")
+      return nil if @encoders.nil?
+      if @encoders.has_encoder?(name)
+        @encoders.get_encoder(name)
+      elsif @parent
+        @parent.find_encoder(name)
+      else
+        nil
+      end
+    end
+  
+    # See RuleSet#pattern.
+    def pattern(block_symbols)
+      return RuleSet.new.pattern(block_symbols) if @ruleset.nil?
+      @ruleset.pattern(block_symbols)
+    end
+  
+    ### Other utilities ##########################################################
+  
+    # Factors a spacing friendly buffer for instantiation in this dialect
+    def factor_buffer
+      IntelligentBuffer.new
+    end
+  
+    # Returns a string representation   
+    def to_s
+      qualified_name
+    end
+   
+  end # class Dialect
+    
+end #module WLang