Class: Nanoc3::Item

Inherits:
Object
  • Object
show all
Extended by:
Memoization
Defined in:
lib/nanoc3/base/source_data/item.rb

Overview

Represents a compileable item in a site. It has content and attributes, as well as an identifier (which starts and ends with a slash). It can also store the modification time to speed up compilation.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Memoization

memoize

Constructor Details

#initialize(raw_content_or_raw_filename, attributes, identifier, params = nil) ⇒ Item

Creates a new item with the given content or filename, attributes and identifier.

Parameters:

  • raw_content_or_raw_filename (String) —

    The uncompiled item content (if it is a textual item) or the path to the filename containing the content (if it is a binary item).

  • attributes (Hash) —

    A hash containing this item’s attributes.

  • identifier (String) —

    This item’s identifier.

  • params (Time, Hash) (defaults to: nil) —

    Extra parameters. For backwards compatibility, this can be a Time instance indicating the time when this item was last modified (mtime).

Options Hash (params):

  • :mtime (Time, nil) — default: nil —

    The time when this item was last modified. Deprecated; pass the modification time as the ‘:mtime` attribute instead.

  • :binary (Symbol, nil) — default: true —

    Whether or not this item is binary



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/nanoc3/base/source_data/item.rb', line 67

def initialize(raw_content_or_raw_filename, attributes, identifier, params=nil)
  # Parse params
  params ||= {}
  params = { :mtime => params } if params.is_a?(Time)
  params[:binary] = false unless params.has_key?(:binary)

  if raw_content_or_raw_filename.nil?
    raise "attempted to create an item with no content/filename (identifier #{identifier})"
  end

  # Get type and raw content or raw filename
  @is_binary = params[:binary]
  if @is_binary
    @raw_filename = raw_content_or_raw_filename
  else
    @raw_content  = raw_content_or_raw_filename
  end

  # Get rest of params
  @attributes   = attributes.symbolize_keys
  @identifier   = identifier.cleaned_identifier.freeze

  # Set mtime
  @attributes.merge!(:mtime => params[:mtime]) if params[:mtime]

  @parent       = nil
  @children     = []

  @reps         = []
end

Instance Attribute Details

#attributes ⇒ Hash

Returns This item’s attributes.

Returns:

  • (Hash) —

    This item’s attributes



13
14
15
 
# File 'lib/nanoc3/base/source_data/item.rb', line 13

def attributes
  @attributes
end

#children ⇒ Array<Nanoc3::Item>

Returns The child items of this item.

Returns:



44
45
46
 
# File 'lib/nanoc3/base/source_data/item.rb', line 44

def children
  @children
end

#identifier ⇒ String

A string that uniquely identifies an item in a site.

Identifiers start and end with a slash. They are comparable to paths on the filesystem, with the difference that file system paths usually do not have a trailing slash. The item hierarchy (parent and children of items) is determined by the item identifier.

The root page (the home page) has the identifier “/”, which means that it is the ancestor of all other items.

Returns:

  • (String) —

    This item’s identifier



26
27
28
 
# File 'lib/nanoc3/base/source_data/item.rb', line 26

def identifier
  @identifier
end

#parent ⇒ Nanoc3::Item?

Returns The parent item of this item. This can be nil even for non-root items.

Returns:

  • (Nanoc3::Item, nil) —

    The parent item of this item. This can be nil even for non-root items.



41
42
43
 
# File 'lib/nanoc3/base/source_data/item.rb', line 41

def parent
  @parent
end

#raw_content ⇒ String (readonly)

Returns This item’s raw, uncompiled content of this item (only available for textual items).

Returns:

  • (String) —

    This item’s raw, uncompiled content of this item (only available for textual items)



33
34
35
 
# File 'lib/nanoc3/base/source_data/item.rb', line 33

def raw_content
  @raw_content
end

#raw_filename ⇒ String (readonly)

Returns The filename pointing to the file containing this item’s content (only available for binary items).

Returns:

  • (String) —

    The filename pointing to the file containing this item’s content (only available for binary items)



37
38
39
 
# File 'lib/nanoc3/base/source_data/item.rb', line 37

def raw_filename
  @raw_filename
end

#reps ⇒ Array<Nanoc3::ItemRep> (readonly)

Returns This item’s list of item reps.

Returns:



29
30
31
 
# File 'lib/nanoc3/base/source_data/item.rb', line 29

def reps
  @reps
end

Instance Method Details

#==(other) ⇒ Object 



272
273
274
 
# File 'lib/nanoc3/base/source_data/item.rb', line 272

def ==(other)
  self.eql?(other)
end

#[](key) ⇒ Object

Requests the attribute with the given key.

Parameters:

  • key (Symbol) —

    The name of the attribute to fetch

Returns:

  • (Object) —

    The value of the requested attribute



166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/nanoc3/base/source_data/item.rb', line 166

def [](key)
  Nanoc3::NotificationCenter.post(:visit_started, self)
  Nanoc3::NotificationCenter.post(:visit_ended,   self)

  # Get captured content (hax)
  # TODO [in nanoc 4.0] remove me
  if key.to_s =~ /^content_for_(.*)$/
    @@_content_for_warning_issued ||= false
    @@_Nanoc3_Helpers_Capturing_included ||= false

    # Warn
    unless @@_content_for_warning_issued
      warn 'WARNING: Accessing captured content should happen using the #content_for method defined in the Capturing helper instead of using item[:content_for_something]. The latter way of accessing captured content will be removed in nanoc 4.0.'
      @@_content_for_warning_issued = true
    end

    # Include capturing helper if necessary
    unless @@_Nanoc3_Helpers_Capturing_included
      self.class.send(:include, ::Nanoc3::Helpers::Capturing)
      @@_Nanoc3_Helpers_Capturing_included = true
    end

    # Get content
    return content_for(self, $1.to_sym)
  end

  @attributes[key]
end

#[]=(key, value) ⇒ Object

Sets the attribute with the given key to the given value.

Parameters:

  • key (Symbol) —

    The name of the attribute to set

  • value (Object) —

    The value of the attribute to set



200
201
202
 
# File 'lib/nanoc3/base/source_data/item.rb', line 200

def []=(key, value)
  @attributes[key] = value
end

#binary? ⇒ Boolean

Returns True if the item is binary; false if it is not.

Returns:

  • (Boolean) —

    True if the item is binary; false if it is not



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

def binary?
  !!@is_binary
end

#checksum ⇒ String

Returns The checksum for this object. If its contents change, the checksum will change as well.

Returns:

  • (String) —

    The checksum for this object. If its contents change, the checksum will change as well.



245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
 
# File 'lib/nanoc3/base/source_data/item.rb', line 245

def checksum
  content_checksum = if binary?
    if File.exist?(raw_filename)
      Pathname.new(raw_filename).checksum
    else
      ''.checksum
    end
  else
    @raw_content.checksum
  end

  attributes = @attributes.dup
  attributes.delete(:file)
  attributes_checksum = attributes.checksum

  content_checksum + ',' + attributes_checksum
end

#compiled_content(params = {}) ⇒ String

Returns the compiled content from a given representation and a given snapshot. This is a convenience method that makes fetching compiled content easier.

Parameters:

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

    a customizable set of options

Options Hash (params):

  • :rep (String) — default: :default —

    The name of the representation from which the compiled content should be fetched. By default, the compiled content will be fetched from the default representation.

  • :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 of the given rep (or the default rep if no rep is specified) at the given snapshot (or the default snapshot if no snapshot is specified)

See Also:



125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/nanoc3/base/source_data/item.rb', line 125

def compiled_content(params={})
  # Get rep
  rep_name = params[:rep] || :default
  rep = reps.find { |r| r.name == rep_name }
  if rep.nil?
    raise Nanoc3::Errors::Generic,
      "No rep named #{rep_name.inspect} was found."
  end

  # Get rep's content
  rep.compiled_content(params)
end

#eql?(other) ⇒ Boolean

Returns:

  • (Boolean) 


268
269
270
 
# File 'lib/nanoc3/base/source_data/item.rb', line 268

def eql?(other)
  self.class == other.class && self.identifier == other.identifier
end

#freeze ⇒ void

This method returns an undefined value.

Prevents all further modifications to its attributes.



231
232
233
234
235
236
237
 
# File 'lib/nanoc3/base/source_data/item.rb', line 231

def freeze
  attributes.freeze_recursively
  children.freeze
  identifier.freeze
  raw_filename.freeze if raw_filename
  raw_content.freeze  if raw_content
end

#hash ⇒ Object 



264
265
266
 
# File 'lib/nanoc3/base/source_data/item.rb', line 264

def hash
  self.class.hash ^ self.identifier.hash
end

#inspect ⇒ Object 



239
240
241
 
# File 'lib/nanoc3/base/source_data/item.rb', line 239

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

#marshal_dump ⇒ Object 



276
277
278
279
280
281
282
283
284
 
# File 'lib/nanoc3/base/source_data/item.rb', line 276

def marshal_dump
  [
    @is_binary,
    @raw_filename,
    @raw_content,
    @attributes,
    @identifier
  ]
end

#marshal_load(source) ⇒ Object 



286
287
288
289
290
291
292
 
# File 'lib/nanoc3/base/source_data/item.rb', line 286

def marshal_load(source)
  @is_binary,
  @raw_filename,
  @raw_content,
  @attributes,
  @identifier = *source
end

#mtime ⇒ Object

Deprecated.

Access the modification time using ‘item` instead.



295
296
297
 
# File 'lib/nanoc3/base/source_data/item.rb', line 295

def mtime
  self[:mtime]
end

#path(params = {}) ⇒ String

Returns the path from a given representation. This is a convenience method that makes fetching the path of a rep easier.

Parameters:

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

    a customizable set of options

Options Hash (params):

  • :rep (String) — default: :default —

    The name of the representation from which the path should be fetched. By default, the path will be fetched from the default representation.

Returns:

  • (String) —

    The path of the given rep ( or the default rep if no rep is specified)



147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/nanoc3/base/source_data/item.rb', line 147

def path(params={})
  rep_name = params[:rep] || :default

  # Get rep
  rep = reps.find { |r| r.name == rep_name }
  if rep.nil?
    raise Nanoc3::Errors::Generic,
      "No rep named #{rep_name.inspect} was found."
  end

  # Get rep's path
  rep.path
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



224
225
226
 
# File 'lib/nanoc3/base/source_data/item.rb', line 224

def reference
  [ type, self.identifier ]
end

#rep_named(rep_name) ⇒ Nanoc3::ItemRep

Returns the rep with the given name.

Parameters:

  • rep_name (Symbol) —

    The name of the representation to return

Returns:



103
104
105
 
# File 'lib/nanoc3/base/source_data/item.rb', line 103

def rep_named(rep_name)
  @reps.find { |r| r.name == rep_name }
end

#type ⇒ Symbol

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 the type of this object. Will always return ‘:item`, because this is an item. For layouts, this method returns `:layout`.

Returns:

  • (Symbol) —

    :item



215
216
217
 
# File 'lib/nanoc3/base/source_data/item.rb', line 215

def type
  :item
end