Class: Nanoc::Item

Inherits:
Object
  • Object
show all
Extended by:
Memoization
Defined in:
lib/nanoc/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

- (Item) initialize(raw_content_or_raw_filename, attributes, identifier, params = nil)

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



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
97
98
# File 'lib/nanoc/base/source_data/item.rb', line 68

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.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_filename = attributes[:content_filename]
    @raw_content  = raw_content_or_raw_filename
  end

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

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

  @parent       = nil
  @children     = []

  @reps         = []
end

Instance Attribute Details

- (Hash) attributes

Returns This item’s attributes

Returns:

  • (Hash)

    This item’s attributes



11
12
13
# File 'lib/nanoc/base/source_data/item.rb', line 11

def attributes
  @attributes
end

- (Array<Nanoc::Item>) children

Returns The child items of this item

Returns:



45
46
47
# File 'lib/nanoc/base/source_data/item.rb', line 45

def children
  @children
end

- (String) identifier

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



24
25
26
# File 'lib/nanoc/base/source_data/item.rb', line 24

def identifier
  @identifier
end

- (Nanoc::Item?) parent

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

Returns:

  • (Nanoc::Item, nil)

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



42
43
44
# File 'lib/nanoc/base/source_data/item.rb', line 42

def parent
  @parent
end

- (String) raw_content (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)



31
32
33
# File 'lib/nanoc/base/source_data/item.rb', line 31

def raw_content
  @raw_content
end

- (String) raw_filename (readonly)

Returns The filename pointing to the file containing this item’s content

Returns:

  • (String)

    The filename pointing to the file containing this item’s content



35
36
37
# File 'lib/nanoc/base/source_data/item.rb', line 35

def raw_filename
  @raw_filename
end

- (Array<Nanoc::ItemRep>) reps (readonly)

Returns This item’s list of item reps

Returns:



27
28
29
# File 'lib/nanoc/base/source_data/item.rb', line 27

def reps
  @reps
end

- (Nanoc::Site) site

Returns The site this item belongs to

Returns:



38
39
40
# File 'lib/nanoc/base/source_data/item.rb', line 38

def site
  @site
end

Instance Method Details

- (Object) ==(other)



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

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

- (Object) [](key)

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



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
194
195
# File 'lib/nanoc/base/source_data/item.rb', line 168

def [](key)
  Nanoc::NotificationCenter.post(:visit_started, self)
  Nanoc::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
    @@_capturing_helper_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 @@_capturing_helper_included
      self.class.send(:include, ::Nanoc::Helpers::Capturing)
      @@_capturing_helper_included = true
    end

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

  @attributes[key]
end

- (Object) []=(key, value)

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



202
203
204
# File 'lib/nanoc/base/source_data/item.rb', line 202

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

- (Boolean) binary?

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



207
208
209
# File 'lib/nanoc/base/source_data/item.rb', line 207

def binary?
  @is_binary
end

- (String) checksum

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.



247
248
249
# File 'lib/nanoc/base/source_data/item.rb', line 247

def checksum
  Nanoc::Checksummer.calc(self)
end

- (String) compiled_content(params = {})

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:



127
128
129
130
131
132
133
134
135
136
137
138
# File 'lib/nanoc/base/source_data/item.rb', line 127

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

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

- (Boolean) eql?(other)

Returns:

  • (Boolean)


256
257
258
# File 'lib/nanoc/base/source_data/item.rb', line 256

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

- (Object) forced_outdated=(bool)

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.



283
284
285
# File 'lib/nanoc/base/source_data/item.rb', line 283

def forced_outdated=(bool)
  @forced_outdated = bool
end

- (Boolean) forced_outdated?

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:

  • (Boolean)


288
289
290
# File 'lib/nanoc/base/source_data/item.rb', line 288

def forced_outdated?
  @forced_outdated || false
end

- (void) freeze

This method returns an undefined value.

Prevents all further modifications to its attributes.



233
234
235
236
237
238
239
# File 'lib/nanoc/base/source_data/item.rb', line 233

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

- (Object) hash



252
253
254
# File 'lib/nanoc/base/source_data/item.rb', line 252

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

- (Object) inspect



241
242
243
# File 'lib/nanoc/base/source_data/item.rb', line 241

def inspect
  "<#{self.class} identifier=\"#{identifier}\" binary?=#{self.binary?}>"
end

- (Object) marshal_dump



264
265
266
267
268
269
270
271
272
# File 'lib/nanoc/base/source_data/item.rb', line 264

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

- (Object) marshal_load(source)



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

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

- (Object) mtime

Deprecated.

Access the modification time using item[:mtime] instead.



293
294
295
# File 'lib/nanoc/base/source_data/item.rb', line 293

def mtime
  self[:mtime]
end

- (String) path(params = {})

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)



149
150
151
152
153
154
155
156
157
158
159
160
161
# File 'lib/nanoc/base/source_data/item.rb', line 149

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

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

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



226
227
228
# File 'lib/nanoc/base/source_data/item.rb', line 226

def reference
  [type, identifier]
end

- (Nanoc::ItemRep) rep_named(rep_name)

Returns the rep with the given name.

Parameters:

  • rep_name (Symbol)

    The name of the representation to return

Returns:



105
106
107
# File 'lib/nanoc/base/source_data/item.rb', line 105

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

- (Symbol) type

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



217
218
219
# File 'lib/nanoc/base/source_data/item.rb', line 217

def type
  :item
end