Home DocumentationReferenceAPIWebgen ↴

class Webgen::Path

About ↑

A Path object provides information about a path that is used to create one or more nodes as well as methods for accessing/modifying the path's content. Path objects are created by Source classes but can also be created during the rendering phase (see PathHandler#create_secondary_nodes).

So a Path object always refers to a path from which nodes are created! In contrast, destination paths are just strings and specify the location where a specific node should be written to (see Node#destination_path).

A Path object can represent one of three different things: a directory, a file or a fragment. If the path ends with a slash character, then the path object represents a directory, if the path contains a hash character anywhere, then the path object represents a fragment and else it represents a file. Have a look at the user documentation to see the exact format that can be used for a path string!

Utility methods ↑

The Path class also provides some general methods for working with path strings which are also used, for example, by the Node class:

Attributes

path[R]

The original path string from which this Path object was created.

Public Class Methods

absolute?(uri)

Return true if the given URI is an absolute one, i.e. if it include a scheme.

append(base, path)

Append the path to the base path.

  • The base parameter has to be an acn/alcn/absolute path (i.e. starting with a slash).

  • If base represents a directory, it needs to have a trailing slash!

  • The path parameter doesn't need to be absolute and may contain path patterns.

lcn(cn, lang)

Construct a localized canonical name from a given canonical name and a language.

matches_pattern?(path, pattern, options = File::FNM_DOTMATCH|File::FNM_CASEFOLD|File::FNM_PATHNAME)

Return true if the given path string matches the given non-empty path pattern.

If a fragment path (i.e. one which has a hash character somewhere) should be matched, the pattern needs to have a hash character as well.

For information on which patterns are supported, have a look at the API documentation of File.fnmatch.

new(path, meta_info = {}, &ioblock)

Create a new Path object for path (a string).

The optional block needs to return an IO object for getting the content of the path (see io and data).

The path string needs to be in a well defined format which can be looked up in the webgen user documentation.

url(path, make_absolute = true)

Construct an internal URL for the given path.

If the parameter make_absolute is true, then the path will be made absolute by prepending the special URL 'webgen://lh'

Public Instance Methods

<=>(other)

Compare the path of this object to 'other.path'.

==(other)

Equality – Return true if other is a Path object with the same path or if other is a String equal to the path. Else return false.

Also aliased as: eql?
[](key)

Get the value of the meta information key.

This method has to be used to get meta information without triggering analyzation of the path string!

[]=(key, value)

Set the meta information key to value.

This method has to be used to set meta information without triggering analyzation of the path string!

acn()

The absolute canonical name of this path.

Triggers analyzation of the path if invoked.

alcn()

The absolute localized canonical name of this path.

Triggers analyzation of the path if invoked.

basename()

The canonical name of the path without the extension.

Triggers analyzation of the path if invoked.

cn()

The canonical name created from the path (namely from the parts basename and extension as well as the meta information version).

Triggers analyzation of the path if invoked.

data(mode = nil)

Return the content of the IO object of the path as string.

For a description of the parameter mode see io.

An error is raised, if no IO object is associated with the Path instance.

eql?(other)
Alias for: ==
ext()

The extension of the path.

Triggers analyzation of the path if invoked.

ext=(value)

Set the extension of the path.

Triggers analyzation of the path if invoked.

io(mode = 'r') { |io| ... }

Provide access to the IO object of the path by yielding it.

After the method block returns, the IO object is automatically closed. An error is raised, if no IO object is associated with the Path instance.

The parameter mode specifies the mode in which the IO object should be opened. This can be used, for example, to specify a certain input encoding or to use binary mode.

lcn()

The localized canonical name created from the path.

Triggers analyzation of the path if invoked.

meta_info()

Meta information about the path.

Triggers analyzation of the path if invoked. See []= to setting meta information without triggering analyzation.

mount_at(mp, prefix = nil)

Mount this path at the mount point mp, optionally stripping prefix from the parent path, and return the new Path object.

The parameters mp and prefix have to be absolute directory paths, ie. they have to start and end with a slash and must not contain any hash characters!

Also note that mounting a path is not possible once it is fully initialized, i.e. once some information extracted from the path string is accessed.

parent_path()

The string specifying the parent path.

Triggers analyzation of the path if invoked.

set_io(&block)

Set the IO block to the provided block.