Class: Nanoc3::ItemRep

A Nanoc3::ItemRep is a single representation (rep) of an item (Nanoc3::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.

An item representation is observable. The following events will be notified:

:compilation_started
:compilation_ended
:filtering_started
:filtering_ended

The compilation-related events have one parameters (the item representation); the filtering-related events have two (the item representation, and a symbol containing the filter class name).

Attributes

Instance Attributes

compiled	[RW]	public	Indicates whether this rep has already been compiled.
Also known as: compiled?
created	[RW]	public	Indicates whether this rep’s output file was created the last time it was compiled.
Also known as: created?
force_outdated	[RW]	public	Indicates whether this rep is forced to be dirty by the user.
item	[R]	public	The item (Nanoc3::Item) to which this representation belongs.
modified	[RW]	public	Indicates whether this rep’s output file has changed the last time it was compiled.
Also known as: modified?
name	[R]	public	This item representation’s unique name.
path	[RW]	public	The item rep’s path, as used when being linked to.
raw_path	[RW]	public	The item rep’s raw path.
written	[R]	public	Indicates whether this rep’s compiled content has been written during the current or last compilation session.
Also known as: written?

Constructor Summary

public initialize(item, name)

Creates a new item representation for the given item.

`item`:	The item (Nanoc3::Item) to which the new representation will belong.
`name`:	The unique name for the new item representation.

[View source]

    
      
        
          

69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
        
        
          # File 'lib/nanoc3/base/item_rep.rb', line 69

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

  # Initialize content
  @content = {
    :raw  => @item.raw_content,
    :last => @item.raw_content,
    :pre  => @item.raw_content
  }

  # Reset flags
  @compiled       = false
  @modified       = false
  @created        = false
  @written        = false
  @force_outdated = false
end

        
      

  

Public Visibility

Public Instance Method Summary

#assigns	Returns the assignments that should be available when compiling the content.
#content_at_snapshot(snapshot = :pre)	Returns the item representation content at the given snapshot.
#filter(filter_name, filter_args = {})	Runs the item content through the given filter with the given arguments.
#inspect
#layout(layout_identifier)	Lays out the item using the given layout.
#outdated?	Returns true if this item rep’s output file is outdated and must be regenerated, false otherwise.
#snapshot(snapshot_name)	Creates a snapshot of the current compiled item content.
#write	Writes the item rep’s compiled content to the rep’s output file.

Public Instance Method Details

assigns

public assigns

Returns the assignments that should be available when compiling the content.

[View source]

    
      
        
          

130
131
132
133
134
135
136
137
138
139
140
        
        
          # File 'lib/nanoc3/base/item_rep.rb', line 130

def assigns
  {
    :content    => @content[:last],
    :item       => self.item,
    :item_rep   => self,
    :items      => self.item.site.items,
    :layouts    => self.item.site.layouts,
    :config     => self.item.site.config,
    :site       => self.item.site
  }
end

        
      

  

content_at_snapshot

public content_at_snapshot(snapshot = :pre)

Returns the item representation content at the given snapshot.

snapshot: The snapshot from which the content should be fetched. To get the raw, uncompiled content, use :raw.

Meta Tags

Raises:

[Nanoc3::Errors::UnmetDependency]

[View source]

    
146
147
148
149
150
151
152
153
154
155
        
          # File 'lib/nanoc3/base/item_rep.rb', line 146

def content_at_snapshot(snapshot=:pre)
  Nanoc3::NotificationCenter.post(:visit_started, self.item)
  Nanoc3::NotificationCenter.post(:visit_ended,   self.item)

  puts "*** Attempting to fetch content for #{self.inspect}" if $DEBUG

  raise Nanoc3::Errors::UnmetDependency.new(self) unless compiled?

  @content[snapshot]
end

filter

public filter(filter_name, filter_args = {})

Runs the item content through the given filter with the given arguments.

Meta Tags

Raises:

[Nanoc3::Errors::UnknownFilter]

[View source]

    
      
        
          

158
159
160
161
162
163
164
165
166
167
168
169
170
171
        
        
          # File 'lib/nanoc3/base/item_rep.rb', line 158

def filter(filter_name, filter_args={})
  # Create filter
  klass = Nanoc3::Filter.named(filter_name)
  raise Nanoc3::Errors::UnknownFilter.new(filter_name) if klass.nil?
  filter = klass.new(assigns)

  # Run filter
  Nanoc3::NotificationCenter.post(:filtering_started, self, filter_name)
  @content[:last] = filter.run(@content[:last], filter_args)
  Nanoc3::NotificationCenter.post(:filtering_ended, self, filter_name)

  # Create snapshot
  snapshot(@content[:post] ? :post : :pre)
end

        
      

  

inspect

public inspect

[View source]

    
230
231
232
        
          # File 'lib/nanoc3/base/item_rep.rb', line 230

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

layout

public layout(layout_identifier)

Lays out the item using the given layout.

Meta Tags

Raises:

[Nanoc3::Errors::UnknownLayout]

[View source]

    
      
        
          

174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
        
        
          # File 'lib/nanoc3/base/item_rep.rb', line 174

def layout(layout_identifier)
  # Get layout
  layout ||= @item.site.layouts.find { |l| l.identifier == layout_identifier.cleaned_identifier }
  raise Nanoc3::Errors::UnknownLayout.new(layout_identifier) if layout.nil?

  # Get filter
  filter_name, filter_args  = @item.site.compiler.filter_for_layout(layout)
  raise Nanoc3::Errors::CannotDetermineFilter.new(layout_identifier) if filter_name.nil?

  # Get filter class
  filter_class = Nanoc3::Filter.named(filter_name)
  raise Nanoc3::Errors::UnknownFilter.new(filter_name) if filter_class.nil?

  # Create filter
  filter = filter_class.new(assigns.merge({ :layout => layout }))

  # Create "pre" snapshot
  snapshot(:pre)

  # Layout
  @item.site.compiler.stack.push(layout)
  Nanoc3::NotificationCenter.post(:filtering_started, self, filter_name)
  @content[:last] = filter.run(layout.raw_content, filter_args)
  Nanoc3::NotificationCenter.post(:filtering_ended,   self, filter_name)
  @item.site.compiler.stack.pop

  # Create "post" snapshot
  snapshot(:post)
end

        
      

  

outdated?

public outdated?

Returns true if this item rep’s output file is outdated and must be regenerated, false otherwise.

[View source]

    
      
        
          

91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
        
        
          # File 'lib/nanoc3/base/item_rep.rb', line 91

def outdated?
  # Outdated if we don't know
  return true if @item.mtime.nil?

  # Outdated if the dependency tracker says so
  return true if @force_outdated

  # Outdated if compiled file doesn't exist
  return true if self.raw_path.nil?
  return true if !File.file?(self.raw_path)

  # Get compiled mtime
  compiled_mtime = File.stat(self.raw_path).mtime

  # Outdated if file too old
  return true if @item.mtime > compiled_mtime

  # Outdated if layouts outdated
  return true if @item.site.layouts.any? do |l|
    l.mtime.nil? || l.mtime > compiled_mtime
  end

  # Outdated if code outdated
  return true if @item.site.code_snippets.any? do |cs|
    cs.mtime.nil? || cs.mtime > compiled_mtime
  end

  # Outdated if config outdated
  return true if @item.site.config_mtime.nil?
  return true if @item.site.config_mtime > compiled_mtime

  # Outdated if rules outdated
  return true if @item.site.rules_mtime.nil?
  return true if @item.site.rules_mtime > compiled_mtime

  return false
end

        
      

  

snapshot

public snapshot(snapshot_name)

Creates a snapshot of the current compiled item content.

[View source]

    
205
206
207
        
          # File 'lib/nanoc3/base/item_rep.rb', line 205

def snapshot(snapshot_name)
  @content[snapshot_name] = @content[:last]
end

write

public write

Writes the item rep’s compiled content to the rep’s output file.

[View source]

    
      
        
          

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

def write
  # Create parent directory
  FileUtils.mkdir_p(File.dirname(self.raw_path))

  # Check if file will be created
  @created = !File.file?(self.raw_path)

  # Remember old content
  if File.file?(self.raw_path)
    old_content = File.read(self.raw_path)
  end

  # Write
  File.open(self.raw_path, 'w') { |io| io.write(@content[:last]) }
  @written = true

  # Check if file was modified
  @modified = File.read(self.raw_path) != old_content
end

        
      

  