Class: WLang::Dialect::DSL

Inherits:
Object
  • Object
show all
Defined in:
lib/wlang/dialect_dsl.rb

Overview

Installs the Domain Specific Language allowing to create new dialects easily. Below is a self-explaining example on how to use it.

#
# Starts a new _wlang_ dialect that will have children.
# 
WLang::dialect("wlang") do

  #
  # Starts a _wlang/xhtml_ dialect that will be attached to .wtpl and .whtml
  # file extensions.
  #
  dialect("xhtml", ".wtpl", ".whtm") do 

    # If your dialect needs external gems or files, use ruby_require instead
    # of built-in require: it will allow avoiding all users to have required 
    # dependencies for dialects they don't use.
    ruby_require "somegem", "wlang/rulesets/basic_ruleset", "wlang/dialects/coderay_dialect" do

      # RuleSet defined as Ruby modules can be installed using _rules_.
      # Here: we automatically add the standard Basic ruleset to our dialect.
      rules WLang::RuleSet::Basic

      # You can also install inline rules if they are not designed to be 
      # reusable by others.
      # Here, we add a #{...} rule that replaces all spaces by '#' symbols
      # For rule implementation, see Rule class.
      rule "#" do |parser, offset|
        text, reached = parser.parse(offset)
        text = text.gsub(/\s/, '#')
        [text, reached]
      end 

      # Encoders can be installed the same way(s)
      # Here: we install all coderay encoders defined in a module
      encoders WLang::EncoderSet::CodeRay

      # And inline encoders can be installed as well
      # Encoder below will be allowed as ^{wlang/xhtml/upcase}{...} for example
      encoder 'upcase' do |src, options|
        src.upcase
      end

    end # ruby_require

  end # wlang/xhtml dialect

end # wlang dialect

Instance Method Summary (collapse)

Constructor Details

- (DSL) initialize(dialect)

Initializes dsl with a real dialect instance

Raises:

  • (ArgumentError) 


57
58
59
60
 
# File 'lib/wlang/dialect_dsl.rb', line 57

def initialize(dialect)
  raise(ArgumentError, "Dialect expected") unless WLang::Dialect===dialect
  @dialect = dialect
end

Instance Method Details

- (Object) dialect(name, *extensions, &block)

Starts definition of a sub-dialect of the current one. name is not allowed to be a qualified name. extensions allows wlang to automatically infer dialects used by template files. A block is expected and should contain sub-dialect installation.



79
80
81
82
83
84
85
86
 
# File 'lib/wlang/dialect_dsl.rb', line 79

def dialect(name, *extensions, &block)
  child = WLang::Dialect.new(name, @dialect, &block)
  extensions.each do |ext|
    ext = ('.' << ext) unless ext[0,1]=='.'
    WLang::FILE_EXTENSIONS[ext] = child.qualified_name
  end
  @dialect.add_child_dialect(name, child)
end

- (Object) encoder(name, &block)

Adds a dialect encoder under name. Encoder's code is provided by the block. This block should always take |src, options| arguments: src is the string to encode, options is a Hash instance containing additional encoding options.



99
 
# File 'lib/wlang/dialect_dsl.rb', line 99

def encoder(name, &block) end

- (Object) encoders(mod, pairs = nil)

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).



108
 
# File 'lib/wlang/dialect_dsl.rb', line 108

def encoders(mod, pairs=nil) end

- (Object) extensions(*args) Also known as: extension

Request wlang to associate args files extensions with this dialect. File extensions may also be installed at construction (see dialect).



130
131
132
133
134
135
 
# File 'lib/wlang/dialect_dsl.rb', line 130

def extensions(*args)
  args.each do |ext|
    ext = ('.' << ext) unless ext[0,1]=='.'
    WLang::FILE_EXTENSIONS[ext] = @dialect.qualified_name
  end
end

- (Object) post_transform(transformer = nil, &block)

Sets a transformer to use at end of generation time.



91
 
# File 'lib/wlang/dialect_dsl.rb', line 91

def post_transform(transformer = nil, &block) end

- (Object) ruby_require(*src)

Handles dialect dependencies: all src dependencies will be correctly loaded at dialect building time (dialect are lazy loaded to avoid having all users to have all dependencies of standard dialects).

This method should always be used instead of require. It takes a block that will be executed at building-time. Any code with dependency usage should be part of the block !



71
 
# File 'lib/wlang/dialect_dsl.rb', line 71

def ruby_require(*src) end

- (Object) rule(symbol, &block)

Maps an inline rule with some tag symbols. symbol must be ASCII symbols allowed by the wlang specification. The rule implementation is provided by the block. see Rule class about rule implementation.



115
 
# File 'lib/wlang/dialect_dsl.rb', line 115

def rule(symbol, &block) end

- (Object) rules(mod, pairs = nil)

Adds reusable rules defined in a Ruby module. mod must be a Module instance. If pairs is ommitted (nil), all rules of the module are added, under their standard tag symbols (see DEFAULT_RULESET under WLang::RuleSet::Basic for example). Otherwise, pairs is expected to be a Hash providing a mapping between tag symbols and mod methods (whose names are given by ruby symbols).



124
 
# File 'lib/wlang/dialect_dsl.rb', line 124

def rules(mod, pairs=nil) end