Class: Nanoc3::CompilerDSL

Inherits:
Object
  • Object
show all
Defined in:
lib/nanoc3/base/compilation/compiler_dsl.rb

Overview

Contains methods that will be executed by the site’s ‘Rules` file.

Instance Method Summary collapse

Constructor Details

#initialize(rules_collection, config) ⇒ CompilerDSL

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Creates a new compiler DSL for the given collection of rules.

Parameters:

  • rules_collection (Nanoc3::RulesCollection) —

    The collection of rules to modify when loading this DSL

  • config (Hash) —

    The site configuration



16
17
18
19
 
# File 'lib/nanoc3/base/compilation/compiler_dsl.rb', line 16

def initialize(rules_collection, config)
  @rules_collection = rules_collection
  @config = config
end

Instance Method Details

#compile(identifier, params = {}) { ... } ⇒ void

This method returns an undefined value.

Creates a compilation rule for all items whose identifier match the given identifier, which may either be a string containing the * wildcard, or a regular expression.

This rule will be applicable to reps with a name equal to ‘:default`; this can be changed by giving an explicit `:rep` parameter.

An item rep will be compiled by calling the given block and passing the rep as a block argument.

Examples:

Compiling the default rep of the ‘/foo/` item


compile '/foo/' do
  rep.filter :erb
end

Compiling the ‘:raw` rep of the `/bar/` item


compile '/bar/', :rep => :raw do
  # do nothing
end

Parameters:

  • identifier (String) —

    A pattern matching identifiers of items that should be compiled using this rule

  • params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (params):

  • :rep (Symbol) — default: :default —

    The name of the representation that should be compiled using this rule

Yields:

  • The block that will be executed when an item matching this compilation rule needs to be compiled

Raises:

  • (ArgumentError) 


63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/nanoc3/base/compilation/compiler_dsl.rb', line 63

def compile(identifier, params={}, &block)
  # Require block
  raise ArgumentError.new("#compile requires a block") unless block_given?

  # Get rep name
  rep_name = params[:rep] || :default

  # Create rule
  rule = Rule.new(identifier_to_regex(identifier), rep_name, block)
  @rules_collection.add_item_compilation_rule(rule)
end

#layout(identifier, filter_name, params = {}) ⇒ void

This method returns an undefined value.

Creates a layout rule for all layouts whose identifier match the given identifier, which may either be a string containing the * wildcard, or a regular expression. The layouts matching the identifier will be filtered using the filter specified in the second argument. The params hash contains filter arguments that will be passed to the filter.

Examples:

Specifying the filter to use for a layout


layout '/default/', :erb

Using custom filter arguments for a layout


layout '/custom/',  :haml, :format => :html5

Parameters:

  • identifier (String) —

    A pattern matching identifiers of layouts that should be filtered using this rule

  • filter_name (Symbol) —

    The name of the filter that should be run when processing the layout

  • params (Hash) (defaults to: {}) —

    Extra filter arguments that should be passed to the filter when processing the layout (see Filter#run)



144
145
146
 
# File 'lib/nanoc3/base/compilation/compiler_dsl.rb', line 144

def layout(identifier, filter_name, params={})
  @rules_collection.layout_filter_mapping[identifier_to_regex(identifier)] = [ filter_name, params ]
end

#passthrough(identifier, params = {}) ⇒ void

This method returns an undefined value.

Creates a pair of compilation and routing rules that indicate that the specified item(s) should be copied to the output folder as-is. The items are selected using an identifier, which may either be a string containing the ‘*` wildcard, or a regular expression.

This meta-rule will be applicable to reps with a name equal to ‘:default`; this can be changed by giving an explicit `:rep` parameter.

Examples:

Copying the ‘/foo/` item as-is


passthrough '/foo/'

Copying the ‘:raw` rep of the `/bar/` item as-is


passthrough '/bar/', :rep => :raw

Parameters:

  • identifier (String) —

    A pattern matching identifiers of items that should be processed using this meta-rule

  • params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (params):

  • :rep (Symbol) — default: :default —

    The name of the representation that should be routed using this rule

Raises:

  • (ArgumentError)

Since:

  • 3.2.0



173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/nanoc3/base/compilation/compiler_dsl.rb', line 173

def passthrough(identifier, params={})
  # Require no block
  raise ArgumentError.new("#passthrough does not require a block") if block_given?

  # Get rep name
  rep_name = params[:rep] || :default

  # Create compilation rule
  compilation_block = proc { }
  compilation_rule = Rule.new(identifier_to_regex(identifier), rep_name, compilation_block)
  @rules_collection.add_item_compilation_rule(compilation_rule, :before)

  # Create routing rule
  routing_block = proc do
    item.identifier.chop + '.' + item[:extension]
  end
  routing_rule = Rule.new(identifier_to_regex(identifier), rep_name, routing_block)
  @rules_collection.add_item_routing_rule(routing_rule, :before)
end

#preprocess { ... } ⇒ void

This method returns an undefined value.

Creates a preprocessor block that will be executed after all data is loaded, but before the site is compiled.

Yields:

  • The block that will be executed before site compilation starts



27
28
29
 
# File 'lib/nanoc3/base/compilation/compiler_dsl.rb', line 27

def preprocess(&block)
  @rules_collection.preprocessor = block
end

#route(identifier, params = {}) { ... } ⇒ void

This method returns an undefined value.

Creates a routing rule for all items whose identifier match the given identifier, which may either be a string containing the ‘*` wildcard, or a regular expression.

This rule will be applicable to reps with a name equal to ‘:default`; this can be changed by giving an explicit `:rep` parameter.

The path of an item rep will be determined by calling the given block and passing the rep as a block argument.

Examples:

Routing the default rep of the ‘/foo/` item


route '/foo/' do
  item.identifier + 'index.html'
end

Routing the ‘:raw` rep of the `/bar/` item


route '/bar/', :rep => :raw do
  '/raw' + item.identifier + 'index.txt'
end

Parameters:

  • identifier (String) —

    A pattern matching identifiers of items that should be routed using this rule

  • params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (params):

  • :rep (Symbol) — default: :default —

    The name of the representation that should be routed using this rule

Yields:

  • The block that will be executed when an item matching this compilation rule needs to be routed

Raises:

  • (ArgumentError) 


107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/nanoc3/base/compilation/compiler_dsl.rb', line 107

def route(identifier, params={}, &block)
  # Require block
  raise ArgumentError.new("#route requires a block") unless block_given?

  # Get rep name
  rep_name      = params[:rep] || :default
  snapshot_name = params[:snapshot] || :last

  # Create rule
  rule = Rule.new(identifier_to_regex(identifier), rep_name, block, :snapshot_name => snapshot_name)
  @rules_collection.add_item_routing_rule(rule)
end