Class: Nanoc::CompilerDSL

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

Overview

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

Instance Method Summary (collapse)

Constructor Details

- (CompilerDSL) initialize(rules_collection, config)

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 (Nanoc::RulesCollection)

    The collection of rules to modify when loading this DSL

  • config (Hash)

    The site configuration



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

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

Instance Method Details

- (void) compile(identifier, params = {}) { ... }

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)


68
69
70
71
72
73
74
75
76
77
78
# File 'lib/nanoc/base/compilation/compiler_dsl.rb', line 68

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

- (void) ignore(identifier, params = {})

This method returns an undefined value.

Creates a pair of compilation and routing rules that indicate that the specified item(s) should be ignored, e.g. compiled and routed with an empty rule. 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:

Suppressing compilation and output for all all /foo/* items.


ignore '/foo/*'

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)


221
222
223
224
225
226
227
228
229
230
231
# File 'lib/nanoc/base/compilation/compiler_dsl.rb', line 221

def ignore(identifier, params = {})
  raise ArgumentError.new('#ignore does not require a block') if block_given?

  rep_name = params[:rep] || :default

  compilation_rule = Rule.new(identifier_to_regex(identifier), rep_name, proc {})
  @rules_collection.add_item_compilation_rule(compilation_rule)

  routing_rule = Rule.new(identifier_to_regex(identifier), rep_name, proc {}, :snapshot_name => :last)
  @rules_collection.add_item_routing_rule(routing_rule)
end

- (void) include_rules(name)

This method returns an undefined value.

Includes an additional rules file in the current rules collection.

Examples:

Including two additional rules files, ‘rules/assets.rb’ and

'rules/content.rb'

  include_rules 'rules/assets'
  include_rules 'rules/content'

Parameters:

  • name (String)

    The name of the rules file — an “.rb” extension is implied if not explicitly given

Raises:



245
246
247
248
249
250
# File 'lib/nanoc/base/compilation/compiler_dsl.rb', line 245

def include_rules(name)
  filename = [ "#{name}", "#{name}.rb", "./#{name}", "./#{name}.rb" ].find { |f| File.file?(f) }
  raise Nanoc::Errors::NoRulesFileFound.new if filename.nil?

  instance_eval(File.read(filename), filename)
end

- (void) layout(identifier, filter_name, params = {})

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)



149
150
151
# File 'lib/nanoc/base/compilation/compiler_dsl.rb', line 149

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

- (void) passthrough(identifier, params = {})

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



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
# File 'lib/nanoc/base/compilation/compiler_dsl.rb', line 178

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)

  # Create routing rule
  routing_block = proc do
    # This is a temporary solution until an item can map back to its data
    # source.
    # ATM item[:content_filename] is nil for items coming from the static
    # data source.
    item[:extension].nil? || (item[:content_filename].nil? && item.identifier =~ %r{#{item[:extension]}/$}) ? item.identifier.chop : item.identifier.chop + '.' + item[:extension]
  end
  routing_rule = Rule.new(identifier_to_regex(identifier), rep_name, routing_block, :snapshot_name => :last)
  @rules_collection.add_item_routing_rule(routing_rule)
end

- (void) preprocess { ... }

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
30
31
32
33
34
# File 'lib/nanoc/base/compilation/compiler_dsl.rb', line 27

def preprocess(&block)
  if @rules_collection.preprocessor
    warn 'WARNING: A preprocess block is already defined. Defining ' \
      'another preprocess block overrides the previously one.'
  end

  @rules_collection.preprocessor = block
end

- (void) route(identifier, params = {}) { ... }

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)


112
113
114
115
116
117
118
119
120
121
122
123
# File 'lib/nanoc/base/compilation/compiler_dsl.rb', line 112

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