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.



199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
# File 'lib/nanoc/base/result_data/item_rep.rb', line 199

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



185
186
187
# File 'lib/nanoc/base/result_data/item_rep.rb', line 185

def binary
  @binary
end

- (Nanoc::Item) item (readonly)

Returns The item to which this rep belongs

Returns:



179
180
181
# File 'lib/nanoc/base/result_data/item_rep.rb', line 179

def item
  @item
end

- (Symbol) name (readonly)

Returns The representation’s unique name

Returns:

  • (Symbol)

    The representation’s unique name



182
183
184
# File 'lib/nanoc/base/result_data/item_rep.rb', line 182

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



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

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)



227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
# File 'lib/nanoc/base/result_data/item_rep.rb', line 227

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_name = params.fetch(:snapshot) { @content[:pre] ? :pre : :last }
  is_moving = [:pre, :post, :last].include?(snapshot_name)

  # Check existance of snapshot
  snapshot = snapshots.find { |s| s.first == snapshot_name }
  if !is_moving && (snapshot.nil? || snapshot[-1] == false)
    raise Nanoc::Errors::NoSuchSnapshot.new(self, snapshot_name)
  end

  # Verify snapshot is usable
  is_still_moving =
    case snapshot_name
    when :post, :last
      true
    when :pre
      snapshot.nil? || !snapshot[-1]
    end
  is_usable_snapshot = @content[snapshot_name] && (self.compiled? || !is_still_moving)
  unless is_usable_snapshot
    raise Nanoc::Errors::UnmetDependency.new(self)
  end

  @content[snapshot_name]
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:



322
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
# File 'lib/nanoc/base/result_data/item_rep.rb', line 322

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

- (Object) inspect



475
476
477
# File 'lib/nanoc/base/result_data/item_rep.rb', line 475

def inspect
  "<#{self.class} name=\"#{name}\" binary=#{self.binary?} raw_path=\"#{raw_path}\" item.identifier=\"#{item.identifier}\">"
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:



383
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
# File 'lib/nanoc/base/result_data/item_rep.rb', line 383

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



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

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

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

- (false) proxy? Also known as: 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.



461
462
463
# File 'lib/nanoc/base/result_data/item_rep.rb', line 461

def proxy?
  false
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



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

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



471
472
473
# File 'lib/nanoc/base/result_data/item_rep.rb', line 471

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)



427
428
429
430
431
432
433
434
435
436
437
438
439
# File 'lib/nanoc/base/result_data/item_rep.rb', line 427

def snapshot(snapshot_name, params = {})
  is_final = params.fetch(:final, true)

  unless self.binary?
    @content[snapshot_name] = @content[:last]
  end

  if snapshot_name == :pre && is_final
    snapshots << [:pre, true]
  end

  write(snapshot_name) if is_final
end

- (Boolean) snapshot?(snapshot_name) Also known as: has_snapshot?

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



269
270
271
# File 'lib/nanoc/base/result_data/item_rep.rb', line 269

def snapshot?(snapshot_name)
  !@content[snapshot_name].nil?
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:



448
449
450
# File 'lib/nanoc/base/result_data/item_rep.rb', line 448

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