wlang 0.8.5 → 0.9.1

data/doc/specification/specification.yml

@@ -1,27 +1,27 @@
 ---
 title: WLang
-version: 0.8.4
+version: 0.9.1
 sections:
-  - id: about
+  - identifier: about
     name: About
     file: about.rdoc
-  - id: overview
+  - identifier: overview
     name: Overview
     file: overview.rdoc
-  - id: rulesets
+  - identifier: rulesets
     name: Rulesets
     file: rulesets.wtpl
     links: 'spec["rulesets"].reverse'
-  - id: dialects
+  - identifier: dialects
     name: Dialects
     file: dialects.wtpl
-  - id: hosting
+  - identifier: hosting
     name: Hosting language
     file: hosting.rdoc
-  - id: glossary
+  - identifier: glossary
     name: Glossary
     file: glossary.wtpl
-  - id: symbols
+  - identifier: symbols
     name: Tag symbols
     file: symbols.wtpl
 glossary:
@@ -289,7 +289,7 @@ rulesets:
       # #={wlang/active-string}{...}{...}
       - name:      "block-assignment<br/>(third block is optional)"
         symbol:    "="
-        signature: "#={wlang/active-string <as x>}{...}{...}"
+        signature: "#={wlang/active-string}{...}{...}"
         definition: |-
           <tt>%={+{@parser.current_dialect} as #1}{#2}{#3}</tt>
       # ^={wlang/active-string as x}{...}{...}

data/doc/specification/symbols.wtpl

@@ -5,12 +5,12 @@
     <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>
-}
+  *{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

@@ -1,4 +1,4 @@
-require 'wlang/ruby_extensions'
+require 'wlang/ext/string'
 require 'stringio'
 require 'wlang/rule'
 require 'wlang/rule_set'
@@ -6,8 +6,10 @@ require 'wlang/encoder_set'
 require 'wlang/dialect'
 require 'wlang/dialect_dsl'
 require 'wlang/dialect_loader'
+require 'wlang/hosted_language'
+require 'wlang/hash_scope'
 require 'wlang/parser'
-require 'wlang/parser_context'
+require 'wlang/parser_state'
 require 'wlang/intelligent_buffer'
 
 #
@@ -18,44 +20,48 @@ require 'wlang/intelligent_buffer'
 module WLang
   
   # Current version of WLang
-  VERSION = "0.8.5".freeze
+  VERSION = "0.9.1".freeze
+
+  ######################################################################## About files and extensions
+  
+  # Regular expression for file extensions
+  FILE_EXTENSION_REGEXP = /^\.[a-zA-Z0-9]+$/
+  
+  # Checks that _ext_ is a valid file extension or raises an ArgumentError
+  def self.check_file_extension(ext)
+    raise ArgumentError, "Invalid file extension #{ext} (/^\.[a-zA-Z-0-9]+$/ expected)", caller\
+      unless FILE_EXTENSION_REGEXP =~ ext
+  end
+  
+  # Raises an ArgumentError unless file is a real readable file
+  def self.check_readable_file(file)
+    raise ArgumentError, "File #{file} is not readable or not a file"\
+      unless File.exists?(file) and File.file?(file) and File.readable?(file)
+  end
+  
+  ######################################################################## About dialects
   
   # 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, ...
   #
+  # 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]+)*"
-  
+  # Checks that _name_ is a valid qualified dialect name or raises an ArgumentError
+  def self.check_qualified_dialect_name(name)
+    raise ArgumentError, "Invalid dialect qualified name #{name} (/^[-a-z]+([\/][-a-z]+)*$/ expected)", caller\
+      unless QUALIFIED_DIALECT_NAME_REGEXP =~ name
+  end
+
   #
   # Provides installed {file extension => dialect} mappings. File extensions 
   # (keys) contain the first dot (like .wtpl, .whtml, ...). Dialects (values) are 
@@ -63,21 +69,66 @@ module WLang
   #
   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)
+
+  # Returns the root of the dialect tree
+  def self.dialect_tree
+    @dialect
+  end
   
   #
-  # Installs or query a dialect.
+  # Maps a file extension to a dialect qualified name.
+  #
+  # Example:
+  #
+  #   # We create an 'example' dialect
+  #   WLang::dialect('example') do
+  #     # see WLang::dialect about creating a dialect
+  #   end
+  #
+  #   # We map .wex file extensions to our new dialect
+  #   WLang::file_extension_map('.wex', 'example')
+  #
+  # This method raises an ArgumentError if the extension or dialect qualified
+  # name is not valid.
+  #
+  def self.file_extension_map(extension, dialect_qname)
+    check_file_extension(extension)
+    check_qualified_dialect_name(dialect_qname)
+    WLang::FILE_EXTENSIONS[extension] = dialect_qname
+  end
+
+  #
+  # Infers a dialect from a file extension. Returns nil if no dialect is currently
+  # mapped to the given extension (see file_extension_map)
+  #
+  # This method never raises errors.
+  #
+  def self.infer_dialect(uri)
+    WLang::FILE_EXTENSIONS[File.extname(uri)]
+  end
+  
+  #
+  # Ensures, installs or query a dialect.
+  #
+  # <b>When name is a Dialect</b>, returns it immediately. This helper is provided
+  # for methods that accept both qualified dialect name and dialect instance 
+  # arguments. Calling <code>WLang::dialect(arg)</code> ensures that the result will
+  # be a Dialect instance in all cases (if the arg is valid).
+  #
+  # Example:
+  #    
+  #   # This methods does something with a wlang dialect. _dialect_ argument may
+  #   # be a Dialect instance or a qualified dialect name.
+  #   def my_method(dialect = 'wlang/active-string')
+  #     # ensures the Dialect instance or raises an ArgumentError if the dialect
+  #     # qualified name is invalid (returns nil otherwise !)
+  #     dialect = WLang::dialect(dialect) 
+  #   end
   #
   # <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_
@@ -85,56 +136,219 @@ module WLang
   # is interpreted as code in the dialect DSL (domain specific language, see 
   # WLang::Dialect::DSL). Returns nil in this case.
   #
+  # Example:
+  #
+  #   # New dialect with 'my_dialect' qualified name and automatically installed
+  #   # to recognize '.wmyd' file extensions
+  #   WLang::dialect("my_dialect", '.wmyd') do
+  #     # see WLang::Dialect::DSL for this part of the code
+  #   end
+  #
   # <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.
   #
+  # Example:
+  #
+  #   # Lookup for the 'wlang/xhtml' dialect
+  #   wxhtml = WLang::dialect('wlang/xhtml')
+  #
+  # This method raises an ArgumentError if
+  # * _name_ is not a valid dialect qualified name
+  # * any of the file extension in _extensions_ is invalid
+  #
   def self.dialect(name, *extensions, &block)
+    # first case, already a dialect
+    return name if Dialect===name
+    
+    # other cases, argument validations
+    check_qualified_dialect_name(name)
+    extensions.each {|ext| check_file_extension(ext)}
+    
     if block_given?
+      # first case, dialect installation
       raise "Unsupported qualified names in dialect installation"\
         unless name.index('/').nil?
-      Dialect::DSL.new(@dialect).dialect(name, *extensions, &block).build!
+      Dialect::DSL.new(@dialect).dialect(name, *extensions, &block)
     else
+      # second case, dialect lookup
       @dialect.dialect(name)
     end
   end
   
+  ######################################################################## About encoders
+  
+  # Reusable string for building encoder name based regexps  
+  ENCODER_NAME_REGEXP_STR = "[-a-z]+"
+  
+  # Regular expression for encoder names.
+  ENCODER_NAME_REGEXP = /^([-a-z]+)*$/
+  
+  # Reusable string for building qualified encoder name based regexps  
+  QUALIFIED_ENCODER_NAME_REGEXP_STR = "[-a-z]+([\/][-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]+)*$/
+  
+  # Checks that _name_ is a valid qualified encoder name or raises an ArgumentError
+  def self.check_qualified_encoder_name(name)
+    raise ArgumentError, "Invalid encoder qualified name #{name} (/^[-a-z]+([\/][-a-z]+)*$/ expected)", caller\
+      unless QUALIFIED_ENCODER_NAME_REGEXP =~ name
+  end
+  
+  #
+  # Returns an encoder installed under a qualified name. Returns nil if not 
+  # found. If name is already an Encoder instance, returns it immediately.
+  #
+  # Example:
+  #
+  #   encoder = WLang::encoder('xhtml/entities-encoding')
+  #   encoder.encode('something that needs html entities escaping')
+  #
+  # This method raises an ArgumentError if _name_ is not a valid encoder qualified 
+  # name.
+  #
+  def self.encoder(name)
+    check_qualified_encoder_name(name)
+    @dialect.encoder(name)
+  end
+  
+  # 
+  # Shortcut for
   #
-  # Adds a data loader for file extensions.
+  #   WLang::encoder(encoder_qname).encode(source, options)
+  #
+  # This method raises an ArgumentError 
+  # * if _source_ is not a String
+  # * if the encoder qualified name is invalid
+  # 
+  # It raises a WLang::Error if the encoder cannot be found
+  #
+  def self.encode(source, encoder_qname, options = {})
+    raise ArgumentError, "String expected for source" unless String===source
+    check_qualified_encoder_name(encoder_qname)
+    encoder = WLang::encoder(encoder_qname)
+    raise WLang::Error, "Unable to find encoder #{encoder_qname}" if encoder.nil?
+    encoder.encode(source, options)
+  end
+
+  ######################################################################## About data loading
+  
+  #
+  # 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 = {}
+  
+  #
+  # Adds a data loader for file extensions. A data loader is a block of arity 1, 
+  # taking a file as parameter and returning data decoded from the file.
+  #
+  # Example:
+  #
+  #   # We have some MyXMLDataLoader class that is able to create a ruby object
+  #   # from things expressed .xml files
+  #   WLang::data_loader('.xml') {|file|
+  #     MyXMLDataLaoder.parse_file(file)
+  #   }
+  #
+  #   # Later in a template (see the buffering ruleset that gives you <<={...})
+  #   <<={resources.xml as resources}
+  #   <html>
+  #     *{resources as r}{
+  #       ...
+  #     }
+  #   </html>
+  #
+  # This method raises an ArgumentError if 
+  # * no block is given or if the block is not of arity 1
+  # * any of the file extensions in _exts_ is invalid
   #
   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
+    raise(ArgumentError, "WLang::data_loader expects a block") unless block_given?
+    raise(ArgumentError, "WLang::data_loader expects a block of arity 1") unless block.arity==1
+    exts.each {|ext| check_file_extension(ext)   }
+    exts.each {|ext| DATA_EXTENSIONS[ext] = block}
   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. 
   #
+  # This method raises a WLang::Error if no data loader is installed for the found 
+  # extension. It raises an ArgumentError if the file extension is invalid.
+  #
   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
+    check_file_extension(extension = extension.nil? ? File.extname(uri) : extension)
     loader = DATA_EXTENSIONS[extension]
-    raise("No data loader for #{extension}") if loader.nil?
+    raise ::WLang::Error("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
+  ######################################################################## About templates and instantiations
   
   #
-  # Returns an encoder installed under a qualified name. Returns nil if not 
-  # found.
+  # Factors a template instance for a given string source, dialect (default to
+  # 'wlang/active-string') and block symbols (default to :braces)
   #
-  def self.encoder(name)
-    @dialect.encoder(name)
+  # Example:
+  #
+  #   # The template source code must be interpreted as wlang/xhtml
+  #   template = WLang::template('<p>Hello ${who}!</p>', 'wlang/xhtml')
+  #   str = template.instantiate(:hello => 'world')
+  #
+  #   # We may also use other block symbols...
+  #   template = WLang::template('<p>Hello $(who)!</p>', 'wlang/xhtml', :parentheses)
+  #   str = template.instantiate(:hello => 'world')
+  #
+  # This method raises an ArgumentError if 
+  # * _source_ is not a String
+  # * _dialect_ is not a valid dialect qualified name or Dialect instance
+  # * _block_symbols_ is not in [:braces, :brackets, :parentheses]
+  #
+  def self.template(source, dialect = 'wlang/active-string', block_symbols = :braces)
+    raise ArgumentError, "String expected for source" unless String===source
+    raise ArgumentError, "Invalid symbols for block #{block_symbols}"\
+      unless ::WLang::Template::BLOCK_SYMBOLS.keys.include?(block_symbols)
+    template = Template.new(source, WLang::dialect(dialect), block_symbols)
+  end
+
+  # 
+  # Factors a template instance for a given file, optional dialect (if nil is 
+  # passed, the dialect is infered from the extension) and block symbols 
+  # (default to :braces)
+  #
+  # Example:
+  #
+  #   # the file index.wtpl is a wlang source code in 'wlang/xhtml' dialect 
+  #   # (automatically infered from file extension)
+  #   template = WLang::template('index.wtpl')
+  #   puts template.instantiate(:who => 'world') # puts 'Hello world!'
+  #
+  # This method raises an ArgumentError
+  # * if _file_ does not exists, is not a file or is not readable
+  # * if _dialect_ is not a valid qualified dialect name, Dialect instance, or nil
+  # * _block_symbols_ is not in [:braces, :brackets, :parentheses]
+  #
+  # It raises a WLang::Error
+  # * if no dialect can be infered from the file extension (if _dialect_ was nil)
+  #
+  def self.file_template(file, dialect = nil, block_symbols = :braces)
+    check_readable_file(file)
+    
+    # Check the dialect
+    dialect = self.infer_dialect(file) if dialect.nil?
+    raise WLang::Error, "No known dialect for file extension '#{File.extname(file)}'\n"\
+                      "Known extensions are: " << WLang::FILE_EXTENSIONS.keys.join(", ") if dialect.nil?
+          
+    # Build the template now
+    template = template(File.read(file), dialect, block_symbols)
+    template.source_file = file
+    template
   end
 
   #
@@ -151,35 +365,43 @@ module WLang
   #   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
+  # This method raises an ArgumentError if 
+  # * _source_ is not a String
+  # * _context_ is not nil or a Hash
+  # * _dialect_ is not a valid dialect qualified name or Dialect instance
+  # * _block_symbols_ is not in [:braces, :brackets, :parentheses]
+  #
+  # It raises a WLang::Error
+  # * something goes wrong during instantiation (see WLang::Error and subclasses)
+  #
+  def self.instantiate(source, context = {}, dialect="wlang/active-string", block_symbols = :braces)
+    raise ArgumentError, "Hash expected for context argument" unless (context.nil? or Hash===context)
+    template(source, dialect, block_symbols).instantiate(context || {}).to_s
   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_.
+  # (providing instantiation data). If _dialect_ is nil, tries to infer it from the file 
+  # extension; otherwise _dialect_ is expected to be a qualified dialect name or a Dialect
+  # instance. See instantiate about <tt>block_symbols</tt>.
   #
   # 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)
+  #   Wlang.file_instantiate "template.xxx", {"who" => "Mr. Jones"}, "wlang/xhtml"
+  #
+  # This method raises an ArgumentError if 
+  # * _file_ is not a readable file
+  # * _context_ is not nil or a Hash
+  # * _dialect_ is not a valid dialect qualified name, Dialect instance or nil
+  # * _block_symbols_ is not in [:braces, :brackets, :parentheses]
+  #
+  # It raises a WLang::Error
+  # * if no dialect can be infered from the file extension (if _dialect_ was nil)
+  # * something goes wrong during instantiation (see WLang::Error and subclasses)
+  #
+  def self.file_instantiate(file, context = nil, dialect = nil, block_symbols = :braces)
+    raise ArgumentError, "Hash expected for context argument" unless (context.nil? or Hash===context)
+    file_template(file, dialect, block_symbols).instantiate(context || {}).to_s
   end
   
 end