Class: Nanoc::ItemRep

Inherits:
Object
  • Object
show all
Includes:
Deprecated, Private
Defined in:
lib/nanoc/base/result_data/item_rep.rb

Overview

A single representation (rep) of an item (Item). An item can have multiple representations. A representation has its own output file. A single item can therefore have multiple output files, each run through a different set of filters with a different layout.

Defined Under Namespace

Modules: Deprecated, Private

Constant Summary

Constant Summary

Constants included from Private

Private::TMP_TEXT_ITEMS_DIR

Instance Attribute Summary (collapse)

Attributes included from Private

#assigns, #compiled, #content, #paths, #raw_paths, #temporary_filenames

Instance Method Summary (collapse)

Methods included from Private

#forget_progress, #temp_filename, #type, #write

Methods included from Deprecated

#content_at_snapshot, #created, #created?, #modified, #modified?, #path=, #raw_path=, #written, #written?

Constructor Details

- (ItemRep) initialize(item, name)

Creates a new item representation for the given item.

Parameters:

  • item (Nanoc::Item) —

    The item to which the new representation will belong.

  • name (Symbol) —

    The unique name for the new item representation.



210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/nanoc/base/result_data/item_rep.rb', line 210

def initialize(item, name)
  # Set primary attributes
  @item   = item
  @name   = name

  # Set binary
  @binary = @item.binary?

  # Set default attributes
  @raw_paths  = {}
  @paths      = {}
  @assigns    = {}
  @snapshots  = []
  initialize_content

  # Reset flags
  @compiled = false
end

Instance Attribute Details

- (Boolean) binary (readonly) Also known as: binary?

Returns true if this rep is currently binary; false otherwise

Returns:

  • (Boolean) —

    true if this rep is currently binary; false otherwise



196
197
198
 
# File 'lib/nanoc/base/result_data/item_rep.rb', line 196

def binary
  @binary
end

- (Nanoc::Item) item (readonly)

Returns The item to which this rep belongs

Returns:



190
191
192
 
# File 'lib/nanoc/base/result_data/item_rep.rb', line 190

def item
  @item
end

- (Symbol) name (readonly)

Returns The representation’s unique name

Returns:

  • (Symbol) —

    The representation’s unique name



193
194
195
 
# File 'lib/nanoc/base/result_data/item_rep.rb', line 193

def name
  @name
end

- (Array) snapshots

Returns A list of snapshots, represented as arrays where the first element is the snapshot name (a Symbol) and the last element is a Boolean indicating whether the snapshot is final or not

Returns:

  • (Array) —

    A list of snapshots, represented as arrays where the first element is the snapshot name (a Symbol) and the last element is a Boolean indicating whether the snapshot is final or not



202
203
204
 
# File 'lib/nanoc/base/result_data/item_rep.rb', line 202

def snapshots
  @snapshots
end

Instance Method Details

- (String) compiled_content(params = {})

Returns the compiled content from a given snapshot.

Parameters:

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

    a customizable set of options

Options Hash (params):

  • :snapshot (String) —

    The name of the snapshot from which to fetch the compiled content. By default, the returned compiled content will be the content compiled right before the first layout call (if any).

Returns:

  • (String) —

    The compiled content at the given snapshot (or the default snapshot if no snapshot is specified)



238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/nanoc/base/result_data/item_rep.rb', line 238

def compiled_content(params = {})
  # Make sure we're not binary
  if item.binary?
    raise Nanoc::Errors::CannotGetCompiledContentOfBinaryItem.new(self)
  end

  # Notify
  Nanoc::NotificationCenter.post(:visit_started, item)
  Nanoc::NotificationCenter.post(:visit_ended,   item)

  # Get name of last pre-layout snapshot
  snapshot = params.fetch(:snapshot) { @content[:pre] ? :pre : :last }
  is_moving = [ :pre, :post, :last ].include?(snapshot)

  # Check existance of snapshot
  if !is_moving && snapshots.find { |s| s.first == snapshot && s.last == true }.nil?
    raise Nanoc::Errors::NoSuchSnapshot.new(self, snapshot)
  end

  # Require compilation
  if @content[snapshot].nil? || (!self.compiled? && is_moving)
    raise Nanoc::Errors::UnmetDependency.new(self)
  else
    @content[snapshot]
  end
end

- (void) filter(filter_name, filter_args = {})

This method returns an undefined value.

Runs the item content through the given filter with the given arguments. This method will replace the content of the :last snapshot with the filtered content of the last snapshot.

This method is supposed to be called only in a compilation rule block (see CompilerDSL#compile).

Parameters:

  • filter_name (Symbol) —

    The name of the filter to run the item representations’ content through

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

    The filter arguments that should be passed to the filter’s #run method

Raises:

See Also:



323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
 
# File 'lib/nanoc/base/result_data/item_rep.rb', line 323

def filter(filter_name, filter_args = {})
  # Get filter class
  klass = filter_named(filter_name)
  raise Nanoc::Errors::UnknownFilter.new(filter_name) if klass.nil?

  # Check whether filter can be applied
  if klass.from_binary? && !self.binary?
    raise Nanoc::Errors::CannotUseBinaryFilter.new(self, klass)
  elsif !klass.from_binary? && self.binary?
    raise Nanoc::Errors::CannotUseTextualFilter.new(self, klass)
  end

  begin
    # Notify start
    Nanoc::NotificationCenter.post(:filtering_started, self, filter_name)

    # Create filter
    filter = klass.new(assigns)

    # Run filter
    source = self.binary? ? temporary_filenames[:last] : @content[:last]
    result = filter.setup_and_run(source, filter_args)
    if klass.to_binary?
      temporary_filenames[:last] = filter.output_filename
    else
      @content[:last] = result
      @content[:last].freeze
    end
    @binary = klass.to_binary?

    # Check whether file was written
    if self.binary? && !File.file?(filter.output_filename)
      raise "The #{filter_name.inspect} filter did not write anything to the required output file, #{filter.output_filename}."
    end

    # Create snapshot
    snapshot(@content[:post] ? :post : :pre, :final => false) unless self.binary?
  ensure
    # Notify end
    Nanoc::NotificationCenter.post(:filtering_ended, self, filter_name)
  end
end

- (Boolean) has_snapshot?(snapshot_name)

Checks whether content exists at a given snapshot.

Returns:

  • (Boolean) —

    True if content exists for the snapshot with the given name, false otherwise

Since:

  • 3.2.0



271
272
273
 
# File 'lib/nanoc/base/result_data/item_rep.rb', line 271

def has_snapshot?(snapshot_name)
  !@content[snapshot_name].nil?
end

- (Object) inspect 



467
468
469
 
# File 'lib/nanoc/base/result_data/item_rep.rb', line 467

def inspect
  "<#{self.class} name=\"#{name}\" binary=#{self.binary?} raw_path=\"#{raw_path}\" item.identifier=\"#{item.identifier}\">"
end

- (false) is_proxy?

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.

Returns false because this item is not yet a proxy, and therefore does need to be wrapped in a proxy during compilation.

Returns:

  • (false)

See Also:



454
455
456
 
# File 'lib/nanoc/base/result_data/item_rep.rb', line 454

def is_proxy?
  false
end

- (void) layout(layout, filter_name, filter_args)

This method returns an undefined value.

Lays out the item using the given layout. This method will replace the content of the :last snapshot with the laid out content of the last snapshot.

This method is supposed to be called only in a compilation rule block (see CompilerDSL#compile).

Parameters:

  • layout (Nanoc::Layout) —

    The layout to use

  • filter_name (Symbol) —

    The name of the filter to layout the item representations’ content with

  • filter_args (Hash) —

    The filter arguments that should be passed to the filter’s #run method

Raises:

See Also:



384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
 
# File 'lib/nanoc/base/result_data/item_rep.rb', line 384

def layout(layout, filter_name, filter_args)
  # Check whether item can be laid out
  raise Nanoc::Errors::CannotLayoutBinaryItem.new(self) if self.binary?

  # Create "pre" snapshot
  if @content[:post].nil?
    snapshot(:pre, :final => true)
  end

  # Create filter
  klass = filter_named(filter_name)
  raise Nanoc::Errors::UnknownFilter.new(filter_name) if klass.nil?
  filter = klass.new(assigns.merge({ :layout => layout }))

  # Visit
  Nanoc::NotificationCenter.post(:visit_started, layout)
  Nanoc::NotificationCenter.post(:visit_ended,   layout)

  begin
    # Notify start
    Nanoc::NotificationCenter.post(:processing_started, layout)
    Nanoc::NotificationCenter.post(:filtering_started,  self, filter_name)

    # Layout
    @content[:last] = filter.setup_and_run(layout.raw_content, filter_args)

    # Create "post" snapshot
    snapshot(:post, :final => false)
  ensure
    # Notify end
    Nanoc::NotificationCenter.post(:filtering_ended,  self, filter_name)
    Nanoc::NotificationCenter.post(:processing_ended, layout)
  end
end

- (String) path(params = {})

Returns the item rep’s path, as used when being linked to. It starts with a slash and it is relative to the output directory. It does not include the path to the output directory. It will not include the filename if the filename is an index filename.

Parameters:

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

    a customizable set of options

Options Hash (params):

  • :snapshot (Symbol) — default: :last —

    The snapshot for which the path should be returned

Returns:

  • (String) —

    The item rep’s path



299
300
301
302
303
304
305
 
# File 'lib/nanoc/base/result_data/item_rep.rb', line 299

def path(params = {})
  Nanoc3::NotificationCenter.post(:visit_started, item)
  Nanoc3::NotificationCenter.post(:visit_ended,   item)

  snapshot_name = params[:snapshot] || :last
  @paths[snapshot_name]
end

- (String) raw_path(params = {})

Returns the item rep’s raw path. It includes the path to the output directory and the full filename.

Parameters:

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

    a customizable set of options

Options Hash (params):

  • :snapshot (Symbol) — default: :last —

    The snapshot for which the path should be returned

Returns:

  • (String) —

    The item rep’s path



282
283
284
285
286
287
288
 
# File 'lib/nanoc/base/result_data/item_rep.rb', line 282

def raw_path(params = {})
  Nanoc3::NotificationCenter.post(:visit_started, item)
  Nanoc3::NotificationCenter.post(:visit_ended,   item)

  snapshot_name = params[:snapshot] || :last
  @raw_paths[snapshot_name]
end

- (Object) reference

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.

Returns an object that can be used for uniquely identifying objects.

Returns:

  • (Object) —

    An unique reference to this object



463
464
465
 
# File 'lib/nanoc/base/result_data/item_rep.rb', line 463

def reference
  [ type, item.identifier, name ]
end

- (void) snapshot(snapshot_name, params = {})

This method returns an undefined value.

Creates a snapshot of the current compiled item content.

Parameters:

  • snapshot_name (Symbol) —

    The name of the snapshot to create

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

    a customizable set of options

Options Hash (params):

  • :final (Boolean) — default: true —

    True if this is the final time the snapshot will be updated; false if it is a non-final moving snapshot (such as :pre, :post or :last)



428
429
430
431
432
 
# File 'lib/nanoc/base/result_data/item_rep.rb', line 428

def snapshot(snapshot_name, params = {})
  is_final = params.fetch(:final) { true }
  @content[snapshot_name] = @content[:last] unless self.binary?
  write(snapshot_name) if is_final
end

- (Nanoc::ItemRepRecorderProxy) to_recording_proxy

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.

Returns a recording proxy that is used for determining whether the compilation has changed, and thus whether the item rep needs to be recompiled.

Returns:



441
442
443
 
# File 'lib/nanoc/base/result_data/item_rep.rb', line 441

def to_recording_proxy
  Nanoc::ItemRepRecorderProxy.new(self)
end