Class: Nanoc::Core::DataSource Abstract

Inherits:
Object
  • Object
show all
Extended by:
DDPlugin::Plugin
Defined in:
lib/nanoc/core/data_source.rb

Overview

This class is abstract.

Subclasses should at least implement #items and #layouts.

Responsible for loading site data. It is the (abstract) superclass for all data sources. Subclasses must at least implement the data reading methods (#items and #layouts).

Apart from the methods for loading and storing data, there are the #up and #down methods for bringing up and tearing down the connection to the data source. These should be overridden in subclasses. The #loading method wraps #up and #down. #loading is a convenience method for the more low-level methods #use and #unuse, which respectively increment and decrement the reference count; when the reference count goes from 0 to 1, the data source will be loaded (#up will be called) and when the reference count goes from 1 to 0, the data source will be unloaded (#down will be called).

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(site_config, items_root, layouts_root, config) ⇒ DataSource

Returns a new instance of DataSource.



35
36
37
38
39
40
41
42
 
# File 'lib/nanoc/core/data_source.rb', line 35

def initialize(site_config, items_root, layouts_root, config)
  @site_config  = site_config
  @items_root   = items_root
  @layouts_root = layouts_root
  @config       = config || {}

  @references = 0
end

Instance Attribute Details

#config ⇒ Hash (readonly)

Returns The configuration for this data source. For example, online data sources could contain authentication details.

Returns:

  • (Hash) —

    The configuration for this data source. For example, online data sources could contain authentication details.



31
32
33
 
# File 'lib/nanoc/core/data_source.rb', line 31

def config
  @config
end

#items_root ⇒ String (readonly)

Returns The root path where items returned by this data source should be mounted.

Returns:

  • (String) —

    The root path where items returned by this data source should be mounted.



23
24
25
 
# File 'lib/nanoc/core/data_source.rb', line 23

def items_root
  @items_root
end

#layouts_root ⇒ String (readonly)

Returns The root path where layouts returned by this data source should be mounted.

Returns:

  • (String) —

    The root path where layouts returned by this data source should be mounted.



27
28
29
 
# File 'lib/nanoc/core/data_source.rb', line 27

def layouts_root
  @layouts_root
end

Instance Method Details

#down ⇒ void

This method returns an undefined value.

Brings down the connection to the data. This method should undo the effects of the #up method. For example, a database connection established in #up should be closed in this method.

Subclasses may override this method, but are not required to do so; the default implementation simply does nothing.



86
 
# File 'lib/nanoc/core/data_source.rb', line 86

def down; end

#item_changes ⇒ 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. 



103
104
105
106
 
# File 'lib/nanoc/core/data_source.rb', line 103

def item_changes
  warn "Caution: Data source #{self.class.identifier.inspect} does not implement #item_changes; live compilation will not pick up changes in this data source."
  Enumerator.new { |_y| sleep }
end

#items ⇒ Enumerable

Returns the collection of items (represented by Item) in this site. The default implementation simply returns an empty array.

Subclasses should not prepend ‘items_root` to the item’s identifiers, as this will be done automatically.

Subclasses may override this method, but are not required to do so; the default implementation simply does nothing.

Returns:

  • (Enumerable) —

    The collection of items



98
99
100
 
# File 'lib/nanoc/core/data_source.rb', line 98

def items
  []
end

#layout_changes ⇒ 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. 



109
110
111
112
 
# File 'lib/nanoc/core/data_source.rb', line 109

def layout_changes
  warn "Caution: Data source #{self.class.identifier.inspect} does not implement #layout_changes; live compilation will not pick up changes in this data source."
  Enumerator.new { |_y| sleep }
end

#layouts ⇒ Enumerable

Returns the collection of layouts (represented by Layout) in this site. The default implementation simply returns an empty array.

Subclasses should prepend ‘layout_root` to the layout’s identifiers, since this is not done automatically.

Subclasses may override this method, but are not required to do so; the default implementation simply does nothing.

Returns:

  • (Enumerable) —

    The collection of layouts



124
125
126
 
# File 'lib/nanoc/core/data_source.rb', line 124

def layouts
  []
end

#new_item(content, attributes, identifier, binary: false, checksum_data: nil, content_checksum_data: nil, attributes_checksum_data: nil) ⇒ Object

Creates a new in-memory item instance. This is intended for use within the #items method.

Parameters:

  • content (String, Proc) —

    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, Proc) —

    A hash containing this item’s attributes.

  • identifier (String) —

    This item’s identifier.

  • binary (Boolean) (defaults to: false) —

    Whether or not this item is binary

  • checksum_data (String, nil) (defaults to: nil)
  • content_checksum_data (String, nil) (defaults to: nil)
  • attributes_checksum_data (String, nil) (defaults to: nil) 


146
147
148
149
 
# File 'lib/nanoc/core/data_source.rb', line 146

def new_item(content, attributes, identifier, binary: false, checksum_data: nil, content_checksum_data: nil, attributes_checksum_data: nil)
  content = Nanoc::Core::Content.create(content, binary:)
  Nanoc::Core::Item.new(content, attributes, identifier, checksum_data:, content_checksum_data:, attributes_checksum_data:)
end

#new_layout(raw_content, attributes, identifier, checksum_data: nil, content_checksum_data: nil, attributes_checksum_data: nil) ⇒ Object

Creates a new in-memory layout instance. This is intended for use within the #layouts method.

Parameters:

  • raw_content (String) —

    The raw content of this layout.

  • attributes (Hash) —

    A hash containing this layout’s attributes.

  • identifier (String) —

    This layout’s identifier.

  • checksum_data (String, nil) (defaults to: nil)
  • content_checksum_data (String, nil) (defaults to: nil)
  • attributes_checksum_data (String, nil) (defaults to: nil) 


165
166
167
 
# File 'lib/nanoc/core/data_source.rb', line 165

def new_layout(raw_content, attributes, identifier, checksum_data: nil, content_checksum_data: nil, attributes_checksum_data: nil)
  Nanoc::Core::Layout.new(raw_content, attributes, identifier, checksum_data:, content_checksum_data:, attributes_checksum_data:)
end

#unuse ⇒ void

This method returns an undefined value.

Marks the data source as unused by the caller.

Calling this method decreases the internal reference count. When the reference count reaches zero, i.e. when the data source is not used any more, the data source will be unloaded (#down will be called).



63
64
65
66
 
# File 'lib/nanoc/core/data_source.rb', line 63

def unuse
  @references -= 1
  down if @references.zero?
end

#up ⇒ void

This method returns an undefined value.

Brings up the connection to the data. Depending on the way data is stored, this may not be necessary. This is the ideal place to connect to the database, for example.

Subclasses may override this method, but are not required to do so; the default implementation simply does nothing.



76
 
# File 'lib/nanoc/core/data_source.rb', line 76

def up; end

#use ⇒ void

This method returns an undefined value.

Marks the data source as used by the caller.

Calling this method increases the internal reference count. When the data source is used for the first time (first #use call), the data source will be loaded (#up will be called).



51
52
53
54
 
# File 'lib/nanoc/core/data_source.rb', line 51

def use
  up if @references.zero?
  @references += 1
end