= What is _wlang_ ? _wlang_ is a simple, powerful, robust and secure code generation/templating engine (at least, authors hope so ;-) Motivation for it can be found at http://www.revision-zero.org/wlang. It's main aim is to help you creating web pages, sql queries, ruby code (that is, generating code in general) without having to worry too much about html entities encoding, sql back quoting, string escaping and the like. WLang proposes a generic engine that you can extend to fit your needs. It also proposes standard instantiations of this engine for common tasks such as creating SQL queries, instantiating web pages, etc. == 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]. == Overview (for bold words, see terminology later) Basic usage of _wlang_ is as follows: 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. Example: a template.whtml as follows ${title}

Hello ${who} !

Instantiation data is a hash containing values for _title_ and _who_. Instantiating the template is straightforward: require 'wlang' context = {"title" => "Hello world in WLang", "who" => "Alice"} WLang.file_instantiate("template.whtml", context, STDOUT) === Seems magic ... but is not! - first of all, it does not allow XSS attacks: even if _who_ is a value like '', it will be automatically entities-encoded and will appear for itself, not allowing the browser to interpret it as javascript code. - it is not hardcoded, 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 ${...} (${who} for example) automatically replaces the tag by the context data under 'who' (in the hash), while taking care of applying entities-encoding. - ${...} is only one available tag. Actuall _wlang_ dialects come with a lot of useful tags that provide shortuct to common tasks ... entities-encoding is only one ! == Terminology _wlang_ comes with a well-defined terminology for the underlying abstractions. As the documentation uses it, you'll probably be happy to learn about the main abstractions and associated terms. [template] Source code respecting the wlang grammar, and attached to a given wlang dialect. Asbtraction implemented by WLang::Template. [dialect] Basically, dialect is used as a synonym for (programming) language. However _wlang_ uses a tree of dialects, allowing specializations: sql/sybase for example is the qualified name of a sub-dialect 'sybase' of the 'sql' dialect. Dialects come with associated _encoders_. Abstraction implemented by WLang::Dialect. [wlang dialect] When we talk about a wlang dialect, we are actually refering to some specialization of the wlang tag-based grammar: wlang/xhtml for example is the templating language _wlang_ proposes to generate xhtml pages. An example of source code in that dialect has been shown before. In addition to its encoders a wlang dialect comes with its sets of _tags_ and associated _rules_. Abstraction implemented by WLang::Dialect as well as WLang::EncoderSet and WLang::RuleSet. [encoder set] Reusable set of encoders, attached to a dialect. Abstraction implemented by WLang::EncoderSet. [encoder] Text transformation (algorithm) applying some encoding conventions of a portion of a the target language generated by a dialect. HTML entities-encoding, SQL's back-quoting are examples of encoders. Encoders are accessible through their qualified name: xhtml/entities-encoding and sql/back-quoting in the examples. Abstraction implemented by WLang::Encoder. [ruleset] Reusable set of tags associated to rules. Abstraction implemented by WLang::RuleSet. [wlang tag] Special tags in the template, starting with wlang symbols and a number of wlang blocks. A tag is associated with a wlang rule. Examples: ${...} is a tag with only one block, while ?{...}{...}{...} is another tag but with three blocks. [rule] Transformation semantics of a given tag. When wlang instantiates a template it simply replaces wlang tags by some replacement value (which is always a string). This value is computed by the rule attached to the tag. Rule definition explicitly describes the number of blocks it expects, in which dialect they are parsed and instantiated and the way the replacement value is computed. Example: ^{wlang/active-string}{...} (also known as 'encoding') instantiates #1, looking for an encoder qualified name. Instantiates #2 in the current dialect. Encode #2's instantiation using encoder found in (#1) [context] Some rules allow code to be executed in the hosting language (the definition explicitly announce it by putting wlang/hosted in the corresponding block). When doing so, this code is in fact executed in a given context that provides the execution semantics. Abstraction implemented in WLang::Parser::Context. [hosting language] language (or framework) that executes wlang. In this case, it will be ruby.