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



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
99
100
# File 'lib/nanoc/base/source_data/item.rb', line 70

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



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

def attributes
  @attributes
end

- (Array<Nanoc::Item>) children

Returns The child items of this item

Returns:



47
48
49
# File 'lib/nanoc/base/source_data/item.rb', line 47

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



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

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.



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

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)



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

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



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

def raw_filename
  @raw_filename
end

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

Returns This item’s list of item reps

Returns:



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

def reps
  @reps
end

- (Nanoc::Site) site

Returns The site this item belongs to

Returns:



40
41
42
# File 'lib/nanoc/base/source_data/item.rb', line 40

def site
  @site
end

Instance Method Details

- (Object) ==(other)



262
263
264
# File 'lib/nanoc/base/source_data/item.rb', line 262

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



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
196
197
# File 'lib/nanoc/base/source_data/item.rb', line 170

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
    @@_Nanoc_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 @@_Nanoc_Helpers_Capturing_included
      self.class.send(:include, ::Nanoc::Helpers::Capturing)
      @@_Nanoc_Helpers_Capturing_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



204
205
206
# File 'lib/nanoc/base/source_data/item.rb', line 204

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



209
210
211
# File 'lib/nanoc/base/source_data/item.rb', line 209

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.



249
250
251
# File 'lib/nanoc/base/source_data/item.rb', line 249

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:



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

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)


258
259
260
# File 'lib/nanoc/base/source_data/item.rb', line 258

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.



285
286
287
# File 'lib/nanoc/base/source_data/item.rb', line 285

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)


290
291
292
# File 'lib/nanoc/base/source_data/item.rb', line 290

def forced_outdated?
  @forced_outdated || false
end

- (void) freeze

This method returns an undefined value.

Prevents all further modifications to its attributes.



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

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

- (Object) hash



254
255
256
# File 'lib/nanoc/base/source_data/item.rb', line 254

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

- (Object) inspect



243
244
245
# File 'lib/nanoc/base/source_data/item.rb', line 243

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

- (Object) marshal_dump



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

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

- (Object) marshal_load(source)



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

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.



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

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)



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

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



228
229
230
# File 'lib/nanoc/base/source_data/item.rb', line 228

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:



107
108
109
# File 'lib/nanoc/base/source_data/item.rb', line 107

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



219
220
221
# File 'lib/nanoc/base/source_data/item.rb', line 219

def type
  :item
end