Class: Webgen::Destination

Inherits:
Object
  • Object
show all
Includes:
ExtensionManager
Defined in:
lib/webgen/destination.rb,
lib/webgen/destination/file_system.rb

Overview

Namespace for all classes that are used to write content to a specific destination.

About

This class is used to manage destination classes. A destination class is a class that writes content to a specific destination. For example, the FileSystem class uses the file system to write out the generated content to the file system.

The #register method is used for registering new destination classes.

Since there can only be one destination class per website instance, this manager class hides the implementation details and uses the configuration option “destination” to create a new object from the correct destination class. Use the #write, #read, #exists? and #delete methods on this manager class to perform the equivalent operations on the destination class.

Implementing a destination class

A destination class must respond to the following five methods:

initialize(website, *args)

The website instance is always provided as the first argument and the initialize method can have any number of other parameters.

exists?(path)

Return true if the given path exists.

delete(path)

Delete the given path.

write(path, data)

Write the data to the given path. If path ends with a slash, a directory should be created. The parameter data is either a String with the content or a Webgen::Path object. If it is the latter, use the Webgen::Path#io method for retrieving the IO object.

read(path, mode = ‘rb’)

Return the content of the given path if it exists or raise an error otherwise. The parameter mode specifies the mode in which the path should be opened and defaults to reading in binary mode.

It seems a bit odd that a destination object has to implement reading functionality. However, consider the case where you want webgen to render a website programmatically and use the generated data. In this case you need a way to get the content of the generated files!

Sample destination class

Following is a simple destination class which stores the written content in a hash in memory:

class MemoryDestination

  attr_reader :data

  def initialize(website)
    # the website object is not used in this destination class
    @data = {}
  end

  def exists?(path)
    @data.has_key?(path)
  end

  def delete(path)
    @data.delete(path)
  end

  def write(path, data)
    @data[path] = (data.kind_of?(String) ? data : data.data)
  end

  def read(path, mode = 'rb')
    raise "No such path #{path}" unless @data[path] && path[-1] != ?/
    @data[path]
  end
end

website.ext.destination.register MemoryDestination, :name => 'memory'

Defined Under Namespace

Classes: FileSystem

Instance Method Summary collapse

Methods included from ExtensionManager

#initialize_copy, #registered?, #registered_extensions

Constructor Details

#initialize(website) ⇒ Destination

Create a new Destination object that is associated with the given website.



89
90
91
92
 
# File 'lib/webgen/destination.rb', line 89

def initialize(website)
  super()
  @website = website
end

Instance Method Details

#delete(path) ⇒ Object

Delete the given path



135
136
137
 
# File 'lib/webgen/destination.rb', line 135

def delete(path)
  instance.delete(path)
end

#exists?(path) ⇒ Boolean

Return true if the given path exists.

Returns:

  • (Boolean) 


130
131
132
 
# File 'lib/webgen/destination.rb', line 130

def exists?(path)
  instance.exists?(path)
end

#read(path, mode = 'rb') ⇒ Object

Return the content of the given path which is opened in mode.



145
146
147
 
# File 'lib/webgen/destination.rb', line 145

def read(path, mode = 'rb')
  instance.read(path, mode)
end

#register(klass, options = {}, &block) ⇒ Object

Register a destination class.

The parameter klass has to contain the name of the destination class or the class object itself. If the class is located under this namespace, only the class name without the hierarchy part is needed, otherwise the full class name including parent module/class names is needed.

Options:

:name

The name for the destination class. If not set, it defaults to the snake-case version (i.e. FileSystem → file_system) of the class name (without the hierarchy part). It should only contain letters.

Examples:

destination.register('FileSystem')   # registers Webgen::Destination::FileSystem

destination.register('::FileSystem') # registers FileSystem !!!

destination.register('MyModule::Doit', name: 'doit_now')



115
116
117
 
# File 'lib/webgen/destination.rb', line 115

def register(klass, options={}, &block)
  do_register(klass, options, false, &block)
end

#write(path, data) ⇒ Object

Write the data (either a String or a Webgen::Path object) to the given path.



140
141
142
 
# File 'lib/webgen/destination.rb', line 140

def write(path, data)
  instance.write(path, data) if !@website.config['website.dry_run']
end