wlang 0.8.5 → 0.9.1

data/CHANGELOG.rdoc

@@ -0,0 +1,65 @@
+== Changelog
+
+=== Version 0.9.1
+
+==== Bug fixes
+
+- #307, about HashScope.has_key? which returned nil instead of false in some situations
+
+==== Broken features and APIs (by order of importance)
+
+- HostedLanguage::DSL is strictly private and should be reopened. Methods added to this class
+  will never be available in templates. Use HostedLanguage.variable_missing instead. 
+- ::WLang::BasicObject has been removed. HostedLanguage::DSL implements its own strategy, which
+  is spec tested in test/spec/basic_object.spec
+
+==== New features (by order of importance)
+
+- WLang does not requires the rdoc gem by default
+- A new encoder redcloth/xhtml allows using Textile markups easily
+- The wlang/xhtml dialect provides a tag helper for links @{...}{...}
+- The parser class returns friendly messages when a rule is ill-implemented
+
+=== Version 0.9.0
+
+==== Broken features and APIs (by order of importance)
+
+- Major broken API in WLang.instantiate and WLang.file_instantiate which do not allow passing
+  buffers anymore
+- Hash are not methodized by default anymore (major broken feature with 0.8.x versions)
+- Expressions 'a la' PHP w@w (sections/.../.../id) are not supported anymore
+- The default hosted language raises a WLang::UndefinedVariableError when a variable cannot be
+  found in the current template scope (0.8.x versions returned nil in this case)
+- Template.initialize does not take a default context anymore
+- WLang::Parser.context_xxx do not exist anymore. Use branch(...) instead
+- WLang::Parser::Context removed, and WLang::HashScope introduced
+- WLang::Parser instance variables are all made protected
+
+==== New features (by order of importance)
+
+- WLang::HostingLanguage introduced, with a default one for Ruby. The hosting language
+  is the way to provide a main scope, accessible to all templates at once.
+- WLang::HostingLanguage is not sensitive to the difference between symbol keys and strings
+- Buffering and Context rulesets now branch the current parser instead of creating a new one
+- WLang::Error and subclasses propose a backtrace information
+- WLang::Parser refactored to encapsulate the whole state in another class (WLang::Parser::State)
+- WLang facade has been made much more robust as it now checks all its arguments.
+- WLang::dialect may now be used to ensure dialect instances from both Dialect args and qualified names.
+- Introduction of WLang.template and WLang.file_template
+- plain-text dialect proposes new camel-based encoders
+- wlang/active-string dialect has the imperative rule set included
+- sql dialect has been added
+- ruby dialect proposes a method-case encoder
+
+=== Version 0.8.5
+
+- Enhances error messages a lot
+- Some bug fixes for ruby 0.8.7
+
+=== Version 0.8.4
+
+- Migration from svn.chefbe.net to github.com
+
+=== Version 0.8.0
+
+- First public version

data/README.rdoc

@@ -8,25 +8,39 @@ escaping and the like. WLang proposes a generic engine that you can extend to fi
 proposes standard instantiations of this engine for common tasks such as creating SQL queries, 
 instantiating web pages, etc.    
 
-== Roadmap
+=== A collection of typical encoders
 
-- For terminology and a quick overview of _wlang_ for generating code, read on.
-- For the current cheatsheet/specification see the file doc/specification/specification.html
-- If you want to learn _wlang_ quickly, see the example directory or read examples
-  in the specification file (if you understand all examples in the specification file, then you 
-  probably master wlang.
-- If you want a killer example (but simple) see the way the specification.html file
-  is generated in doc/specification directory
-- If you want to know which dialects are available (that is, in which target languages 
-  you can generate code), see the specification as well or read the file 
-  lib/wlang/dialects/standard_dialects.rb in the source distribution.
-- If you want to create your own wlang dialect, see WLang::Dialect::DSL
-- If you think that your own dialect is of generic purpose and well-designed, if
-  you have any question or want to contribute join us on {github}[http://github.com/blambeau/wlang].
+The first basic usage of WLang is to provide a collection of text encoders:
+
+  WLang::encode('&',      'xhtml/entities-encoding')      # &
+  WLang::encode("O'Neil", 'sql/single-quoting')           # O\'Neil   
+  WLang::encode("O'Neil", 'sql/sybase/single-quoting')    # O''Neil   
+  ...
+  WLang::encode("hello world",  'plain-text/camel')        # HelloWorld  
+  WLang::encode("hello world",  'plain-text/lower-camel')  # helloWorld  
+  ...
+  WLang::encode("helloWorld",   'ruby/method-case')        # hello_world
+  
+=== A powerful alternative to ruby string interpolation
+
+The second usage is to have shortcuts for using these encoders in typical 
+situations:
+
+  # Hello world!
+  "Hello ${who}!".wlang(:who => 'world')                          
+
+  # Hello cruel & world!
+  "Hello ${who}!".wlang({:who => 'cruel & world'}, 'wlang/xhtml') 
+  
+  # Hello blambeau, llambeau
+  "Hello *{authors as a}{${a}}{, }".wlang(:authors => ['blambeau', 'llambeau'])
   
-== Overview
+  # INSERT INTO people VALUES ('O\'Neil')
+  INSERT INTO people VALUES ('{who}')".wlang(:who => "O'Neil")
+
+=== A powerful templating engine
 
-(for bold words, see terminology later) Basic usage of _wlang_ is as follows: 
+But the main usage of _wlang_ is as follows (for bold words, see terminology later): 
 you have a *template* file (written in a given _wlang_ *dialect*), you have some 
 instantiation *context* (data provided through a Ruby Hash or a yaml file for 
 example) and you would like to instantiate the template with that data.
@@ -46,23 +60,63 @@ the template is straightforward:
 
   require 'wlang'
   context = {"title" => "Hello world in WLang", "who" => "Alice"}
-  WLang.file_instantiate("template.whtml", context, STDOUT)
+  STDOUT << WLang.file_instantiate("template.whtml", context)
   
-=== Seems magic ... but is not!
-
-- first of all, it <b>does not allow XSS attacks</b>: even if _who_ is a value
-  like <tt>'<script>[some javascript code]</script>'</tt>, it will be automatically
-  entities-encoded and will appear for itself, not allowing the browser to interpret
-  it as javascript code.
-- <b>it is not hardcoded</b>, but uses _wlang_ shortcuts: 
-  - as you did not specify the _wlang_ dialect of your template, it has been infered
-    as 'wlang/xhtml' from the file extension.
-  - in this dialect, the wlang rule associated with the tag ${...} (<tt>${who}</tt> 
-    for example) automatically replaces the tag by the context data under 'who' (in
-    the hash), while taking care of applying entities-encoding.
-- <b>${...} is only one available tag</b>. Actuall _wlang_ dialects come with a lot 
-  of useful tags that provide shortuct to common tasks ... entities-encoding is only one ! 
+=== Behind the scene
+
+- WLang helps you avoiding SQL injection and XSS attacks through the same tags reacting differently
+  in different contexts.
+- WLang understands your context (and its dialect) from the template file extension
+- WLang provides a rich collection of pre-defined tags and dialects
+- WLang allows you to create your own encoders, tags and dialects while reusing existing ones
+- WLang may change the current dialect during the template instantiation itself (generating
+  html with embedded javascript is easy and natural)
+- WLang is able to generate wlang code without any perturabation
+
+=== Additional examples (availability of the tags may depend on the dialect)
+
+- Include text files on the fly
 
+    <<{my_file.html}
+
+- Instantiate sub-templates on the fly, passing data as arguments
+
+    <<+{my_sub_template.whtml using who: 'wlang'}
+
+- Load data from yaml or ruby files on the fly
+
+    <<={resources.yaml as resources}{
+      *{resources as r}{ ${r} }
+    }
+
+- WLang instrospection (basic example)
+
+    context = {:varname => 'who', :who => 'wlang'}
+    "Hello ${${varname}}!".wlang(context)                     # => Hello wlang!
+
+- Generate a wlang template and instantiate it after that
+    
+    dialect = 'wlang/active-string'
+    tpl = "Hello $(${varname})!"                              # => Hello $(${varname})
+    tpl = tpl.wlang(:varname => 'who')                        # => Hello $(who)!
+    tpl = tpl.wlang({:who => 'wlang'}, dialect, :parentheses) # => Hello wlang!
+
+== Roadmap
+
+- For terminology and a quick overview of _wlang_ for generating code, read on.
+- For the current cheatsheet/specification see the file doc/specification/specification.html
+- If you want to learn _wlang_ quickly, see the example directory or read examples
+  in the specification file (if you understand all examples in the specification file, then you 
+  probably master wlang.
+- If you want a killer example (but simple) see the way the specification.html file
+  is generated in doc/specification directory
+- If you want to know which dialects are available (that is, in which target languages 
+  you can generate code), see the specification as well or read the file 
+  lib/wlang/dialects/standard_dialects.rb in the source distribution.
+- If you want to create your own wlang dialect, see WLang::Dialect::DSL
+- If you think that your own dialect is of generic purpose and well-designed, if
+  you have any question or want to contribute join us on {github}[http://github.com/blambeau/wlang].
+  
 == Terminology
 
 _wlang_ comes with a well-defined terminology for the underlying abstractions. As 

data/bin/wlang

@@ -6,11 +6,16 @@
 #  Copyright (c) 2009 University of Louvain, Bernard & Louis Lambeau
 #  Released under a MIT or Ruby licence
 #
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'wlang'
 require 'wlang/wlang_command'
 
 begin
   r = WLang::WLangCommand.new
   r.run ARGV
+rescue ::WLang::Error => e
+  $stderr.puts e.message
+  $stderr.puts e.wlang_backtrace.join("\n\t")
 rescue Interrupt => e
   $stderr.puts
   $stderr.puts "Interrupted"

data/doc/specification/dialect.wtpl

@@ -0,0 +1,14 @@
+<div class="dialect">
+  <div style="margin-bottom: 20px">
+    <h3 style="display: inline">${dialect.qualified_name}</h3>
+    ?{dialect.ruleset}{
+      <p style="display: inline">Includes *{dialect.ruleset.reuse as mod}{${mod.name.match(/::([A-Za-z]+)$/)[1]}}{, }</p>
+    }
+  </div>
+  
+  ?{dialect.dialects}{
+    *{dialect.dialects.keys.sort{|k1, k2| k1 <=> k2} as name}{
+      <<+{dialect.wtpl with dialect: dialect.dialects[name]}
+    }
+  }
+</div>

data/doc/specification/dialects.wtpl

@@ -0,0 +1,3 @@
+*{WLang::dialect_tree.dialect('wlang').dialects using each_pair as name, dialect}{
+  <<+{dialect.wtpl with dialect: dialect}
+}

data/doc/specification/glossary.wtpl

@@ -4,11 +4,11 @@
     <th class="definition">definition</th>
     <th class="example">example</th>
   </tr>
-  *{spec/glossary as t}{
+  *{spec.glossary as t}{
   <tr>
-    <td><em>${t/term}</em></td>
-    <td>^{rdoc/nop}{+{t/definition}}</td>
-    <td style="font-size: 90%;">^{rdoc/nop}{+{t/example}}</td>
+    <td><em>${t.term}</em></td>
+    <td>^{rdoc/nop}{+{t.definition}}</td>
+    <td style="font-size: 90%;">^{rdoc/nop}{+{t.example}}</td>
   </tr>
 }
 </table>

data/doc/specification/rulesets.wtpl

@@ -39,25 +39,25 @@ doing so (think at all blocks that expect an expression in the hosting language,
 
 }}
 <<={examples.rb as examples}
-*{spec/rulesets as ruleset}{
-  <h3 id="${ruleset/name}">${ruleset/name}</h3>
-  ^{rdoc/div}{${ruleset/description}}
+*{spec.rulesets as ruleset}{
+  <h3 id="${ruleset.name}">${ruleset.name}</h3>
+  ^{rdoc/div}{${ruleset.description}}
   <table class="ruleset">
     <tr>
       <th class="signature">signature</th>
       <th class="name">name</th>
       <th class="definition">definition</th>
     </tr>
-    *{ruleset/rules as rule}{
+    *{ruleset.rules as rule}{
       <tr>
-        <td class="signature"><tt>${rule/signature}</tt></td>
-        <td class="name">+{rule/name}</td>
-        <td class="definition">^{rdoc/nop}{+{rule/definition}}</td>
+        <td class="signature"><tt>${rule.signature}</tt></td>
+        <td class="name">+{rule.name}</td>
+        <td class="definition">^{rdoc/nop}{+{rule.definition}}</td>
       </tr>
     }
   </table>
   
-  ?{ruleset/examples}{
+  ?{ruleset.examples}{
     <br/>
     <h4>Examples:</h4>
     <table class="examples">
@@ -66,7 +66,7 @@ doing so (think at all blocks that expect an expression in the hosting language,
         <th>wlang expression</th>
         <th>replacement value</th>
       </tr>
-      *{ruleset/examples as example}{
+      *{ruleset.examples as example}{
         <tr>
           <td class="dialect">
             <tt>${example[0]}</tt>

data/doc/specification/specification.css

@@ -50,3 +50,4 @@ table.examples td { border-bottom: 1px dashed black; }
 th.dialect, td.dialect { width: 150px; }
 th.expression, td.expression { width: 350px; }
 th.replacement, td.replacement { width: 350px; }
+div.dialect {padding-left: 20px;}

data/doc/specification/specification.html

@@ -3,7 +3,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-    <title>WLang (version 0.8.4)</title>
+    <title>WLang (version 0.9.1)</title>
     <style type="text/css">
       body {
         font-family: arial, verdana, sans-serif;
@@ -57,7 +57,7 @@
       th.dialect, td.dialect { width: 150px; }
       th.expression, td.expression { width: 350px; }
       th.replacement, td.replacement { width: 350px; }
-
+      div.dialect {padding-left: 20px;}
     </style>
 	  <script type="text/javascript" language="JavaScript"><!-- 
 	    var current = 'about'
@@ -72,7 +72,7 @@
 	  //--></script>
   </head>
   <body onload="show('about')">
-    <h1 id="title">WLang (version 0.8.4)</h1>
+    <h1 id="title">WLang (version 0.9.1)</h1>
     <ul id="tabs">
       <li id="symbolsfocus" onclick="show('symbols')">Tag symbols</li>
       <li id="glossaryfocus" onclick="show('glossary')">Glossary</li>
@@ -863,7 +863,7 @@
                                replacement value.</td>
       </tr>
       <tr>
-        <td class="signature"><tt>#={wlang/active-string &lt;as x&gt;}{...}{...}</tt></td>
+        <td class="signature"><tt>#={wlang/active-string}{...}{...}</tt></td>
         <td class="name">block-assignment<br/>(third block is optional)</td>
         <td class="definition"><tt>%={+{@parser.current_dialect} as #1}{#2}{#3}</tt></td>
       </tr>
@@ -1050,9 +1050,72 @@
     		  
     		  <div class="clear"></div>
     		</div>
-    		
+    		<div class="dialect">
+    <div style="margin-bottom: 20px">
+      <h3 style="display: inline">wlang/uri</h3>
+      <p style="display: inline">Includes Basic</p>
+    
+    </div>
+    
+    
+    </div>
+    <div class="dialect">
+    <div style="margin-bottom: 20px">
+      <h3 style="display: inline">wlang/sql</h3>
+      <p style="display: inline">Includes Basic, Encoding, Imperative, SQL</p>
+    
+    </div>
+    
+    <div class="dialect">
+      <div style="margin-bottom: 20px">
+        <h3 style="display: inline">wlang/sql/sybase</h3>
+        <p style="display: inline">Includes Basic, Encoding, Imperative, SQL</p>
+    
+      </div>
+      
+      
+    </div>
+    
+    
+    </div>
+    <div class="dialect">
+    <div style="margin-bottom: 20px">
+      <h3 style="display: inline">wlang/active-string</h3>
+      <p style="display: inline">Includes Basic, Imperative</p>
+    
+    </div>
+    
+    
+    </div>
+    <div class="dialect">
+    <div style="margin-bottom: 20px">
+      <h3 style="display: inline">wlang/xhtml</h3>
+      <p style="display: inline">Includes Basic, Encoding, Imperative, Buffering, Context, XHtml</p>
+    
+    </div>
+    
+    
+    </div>
+    <div class="dialect">
+    <div style="margin-bottom: 20px">
+      <h3 style="display: inline">wlang/ruby</h3>
+      <p style="display: inline">Includes Basic, Encoding, Imperative, Context, Ruby</p>
     
     </div>
+    
+    
+    </div>
+    <div class="dialect">
+    <div style="margin-bottom: 20px">
+      <h3 style="display: inline">wlang/dummy</h3>
+      
+    </div>
+    
+    
+    </div>
+    
+    
+        </div>
     <div id="hosting" style="display: none;">
     	    <div class="header">
     		  <h2>Hosting language</h2>

data/doc/specification/specification.wtpl

@@ -3,7 +3,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-    <title>${spec/title} (version ${spec/version})</title>
+    <title>${spec.title} (version ${spec.version})</title>
     <style type="text/css">
       <<{specification.css}
     </style>
@@ -12,28 +12,28 @@
 	  //--></script>
   </head>
   <body onload="show('about')">
-    <h1 id="title">${spec/title} (version ${spec/version})</h1>
+    <h1 id="title">${spec.title} (version ${spec.version})</h1>
     <ul id="tabs">
-      *{spec["sections"].reverse as section}{
-        <li id="+{section/id}focus" onclick="show('{section/id}')">${section/name}</li>
+      *{spec.sections.reverse as section}{
+        <li id="+{section.identifier}focus" onclick="show('{section.identifier}')">${section.name}</li>
       }
     </ul>
     <div class="clear"></div>
-    *{spec/sections as section}{
-	  <div id="{section/id}" style="display: none;">
+    *{spec.sections as section}{
+	  <div id="{section.identifier}" style="display: none;">
 	    <div class="header">
-		  <h2>${section/name}</h2>
-		  ?{section/links}{
+		  <h2>${section.name}</h2>
+		  ?{section.links}{
 		    <ul class="links">
-		      *{+{section/links} as link}{<li><a href="#${link/name}">${link/name}</a></li>}
+		      *{+{section.links} as link}{<li><a href="#${link.name}">${link.name}</a></li>}
 		    </ul>
 		  }
 		  <div class="clear"></div>
 		</div>
-		?{/rdoc$/ =~ "{section/file}"}{
-		  ^{rdoc/div}{<<{+{section/file}}}
+		?{/rdoc$/ =~ "{section.file}"}{
+		  ^{rdoc/div}{<<{+{section.file}}}
 		}{
-		  <<+{+{section/file} with spec: spec}
+		  <<+{+{section.file} with spec: spec}
 		}
       </div>
     }