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

  # 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 



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

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



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

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



196
197
198
 
# File 'lib/nanoc3/base/source_data/item.rb', line 196

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



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

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.



241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/nanoc3/base/source_data/item.rb', line 241

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:



121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/nanoc3/base/source_data/item.rb', line 121

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) 


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

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.



227
228
229
230
231
232
233
 
# File 'lib/nanoc3/base/source_data/item.rb', line 227

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

#hash ⇒ Object 



260
261
262
 
# File 'lib/nanoc3/base/source_data/item.rb', line 260

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

#inspect ⇒ Object 



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

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

#marshal_dump ⇒ Object 



272
273
274
275
276
277
278
279
280
 
# File 'lib/nanoc3/base/source_data/item.rb', line 272

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

#marshal_load(source) ⇒ Object 



282
283
284
285
286
287
288
 
# File 'lib/nanoc3/base/source_data/item.rb', line 282

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

#mtime ⇒ Object

Deprecated.

Access the modification time using ‘item` instead.



291
292
293
 
# File 'lib/nanoc3/base/source_data/item.rb', line 291

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)



143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/nanoc3/base/source_data/item.rb', line 143

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



220
221
222
 
# File 'lib/nanoc3/base/source_data/item.rb', line 220

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:



99
100
101
 
# File 'lib/nanoc3/base/source_data/item.rb', line 99

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



211
212
213
 
# File 'lib/nanoc3/base/source_data/item.rb', line 211

def type
  :item
end