Class: Nanoc3::ItemRep

Inherits:
Object
  • Object
show all
Includes:
Deprecated, Private
Defined in:
lib/nanoc3/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

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, #type, #write

Methods included from Deprecated

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

Constructor Details

#initialize(item, name) ⇒ ItemRep

Creates a new item representation for the given item.

Parameters:

  • item (Nanoc3::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
 
# File 'lib/nanoc3/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    = {}
  initialize_content

  # Reset flags
  @compiled = false
end

Instance Attribute Details

#binary ⇒ Boolean (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



201
202
203
 
# File 'lib/nanoc3/base/result_data/item_rep.rb', line 201

def binary
  @binary
end

#item ⇒ Nanoc3::Item (readonly)

Returns The item to which this rep belongs.

Returns:



195
196
197
 
# File 'lib/nanoc3/base/result_data/item_rep.rb', line 195

def item
  @item
end

#name ⇒ Symbol (readonly)

Returns The representation’s unique name.

Returns:

  • (Symbol) —

    The representation’s unique name



198
199
200
 
# File 'lib/nanoc3/base/result_data/item_rep.rb', line 198

def name
  @name
end

Instance Method Details

#compiled_content(params = {}) ⇒ String

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)

Raises:



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

def compiled_content(params={})
  # Notify
  Nanoc3::NotificationCenter.post(:visit_started, self.item)
  Nanoc3::NotificationCenter.post(:visit_ended,   self.item)

  # Require compilation
  raise Nanoc3::Errors::UnmetDependency.new(self) if !compiled? && !params[:force]

  # Get name of last pre-layout snapshot
  snapshot_name = params[:snapshot]
  if @content[:pre]
    snapshot_name ||= :pre
  else
    snapshot_name ||= :last
  end

  # Check presence of snapshot
  if @content[snapshot_name].nil?
    warn(('-' * 78 + "\nWARNING: The “#{self.item.identifier}” item (rep “#{self.name}”) does not have the requested snapshot named #{snapshot_name.inspect}.\n\n* Make sure that you are requesting the correct snapshot.\n* It is not possible to request the compiled content of a binary item representation; if this item is marked as binary even though you believe it should be textual, you may need to add the extension of this item to the site configuration’s `text_extensions` array.\n" + '-' * 78).make_compatible_with_env)
  end

  # Get content
  @content[snapshot_name]
end

#filter(filter_name, filter_args = {}) ⇒ void

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:



314
315
316
317
318
319
320
321
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
 
# File 'lib/nanoc3/base/result_data/item_rep.rb', line 314

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

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

  begin
    # Notify start
    Nanoc3::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.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 RuntimeError,
        "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
    Nanoc3::NotificationCenter.post(:filtering_ended, self, filter_name)
  end
end

#has_snapshot?(snapshot_name) ⇒ Boolean

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



268
269
270
 
# File 'lib/nanoc3/base/result_data/item_rep.rb', line 268

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

#inspect ⇒ Object 



464
465
466
 
# File 'lib/nanoc3/base/result_data/item_rep.rb', line 464

def inspect
  "<#{self.class}:0x#{self.object_id.to_s(16)} name=#{self.name} binary=#{self.binary?} raw_path=#{self.raw_path} item.identifier=#{self.item.identifier}>"
end

#is_proxy? ⇒ false

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:



451
452
453
 
# File 'lib/nanoc3/base/result_data/item_rep.rb', line 451

def is_proxy?
  false
end

#layout(layout, filter_name, filter_args) ⇒ void

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 (Nanoc3::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:



376
377
378
379
380
381
382
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
 
# File 'lib/nanoc3/base/result_data/item_rep.rb', line 376

def layout(layout, filter_name, filter_args)
  # Check whether item can be laid out
  raise Nanoc3::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 Nanoc3::Errors::UnknownFilter.new(filter_name) if klass.nil?
  filter = klass.new(assigns.merge({ :layout => layout }))

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

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

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

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

#path(params = {}) ⇒ String

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



293
294
295
296
 
# File 'lib/nanoc3/base/result_data/item_rep.rb', line 293

def path(params={})
  snapshot_name = params[:snapshot] || :last
  @paths[snapshot_name]
end

#raw_path(params = {}) ⇒ String

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



279
280
281
282
 
# File 'lib/nanoc3/base/result_data/item_rep.rb', line 279

def raw_path(params={})
  snapshot_name = params[:snapshot] || :last
  @raw_paths[snapshot_name]
end

#reference ⇒ Object

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



460
461
462
 
# File 'lib/nanoc3/base/result_data/item_rep.rb', line 460

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

#snapshot(snapshot_name, params = {}) ⇒ void

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



420
421
422
423
424
425
426
427
428
429
 
# File 'lib/nanoc3/base/result_data/item_rep.rb', line 420

def snapshot(snapshot_name, params={})
  # Parse params
  params[:final] = true if !params.has_key?(:final)

  # Create snapshot
  @content[snapshot_name] = @content[:last] unless self.binary?

  # Write
  write(snapshot_name) if params[:final]
end

#to_recording_proxy ⇒ Nanoc3::ItemRepRecorderProxy

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:



438
439
440
 
# File 'lib/nanoc3/base/result_data/item_rep.rb', line 438

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