NAME

Badger::Workspace - an object representing a project workspace

DESCRIPTION

This module implements an object for representing a workspace, for example the directory containing the source, configuration, resources and other files for a web site or some other project. It is a subclass of Badger::Workplace which implements the base functionality.

The root directory for a workspace is expected to contain a configuration directory, called config by default, containing configuration files for the workspace. This is managed by delegation to a Badger::Config::Filesystem object.

CLASS METHODS

new(\%config)

This is the constructor method to create a new "Badger::Workspace" object.

    use Badger::Workspace;

    my $space = Badger::Workspace->new(
        directory => '/path/to/workspace',
    );

CONFIGURATION OPTIONS

root / dir / directory

This mandatory parameter must be provided to indicate the filesystem path to the project directory. It can be also specified using any of the names "root", "dir" or "directory", as per Badger::Workplace

config_module

The name of the delegate module for managing the files in the configuration directory. This defaults to Badger::Config::Filesystem.

config_dir / config_directory

This optional parameter can be used to specify the name of the configuration direction under the root project directory. The default configuration directory name is "config".

config_file

This optional parameter can be used to specify the name of the main configuration file (without file extension) that should reside in the config_dir directory under the "root" project directory. The default configuration file name is "workspace".

PUBLIC METHODS

config($item)

When called without any arguments this returns a Badger::Config::Filesystem object which manages the configuration directory for the project.

    my $cfg = $workspace->config;

When called with a named item it returns the configuration data associated with that item. This will typically be defined in a master configuration file, or in a file of the same name as the item, with an appropriate file extension added.

    my $name = $workspace->config('name');

inherit_config($item)

Attempts to fetch an inherited configuration from a parent namespace. The workspace must have a parent defined and must have the "inherit" option set to any true value.

parent_config($item)

Attempts to fetch the configuration for a named item from a parent workspace. Obviously this requires the workspace to be attached to a parent. Note that this method is not bound by the "inherit" flag and will delegate to any parent regardless.

dir($name)

dirs(\%dirmap)

resolve_dir($name)

file($path)

attach($parent)

Attaches the workspace to a parent workspace.

detach()

Detaches the workspace from any parent workspace.

parent($n)

Returns the parent workspace if there is one. If a numerical argument is passed then it indicates a number of parents to skip. e.g. if $n is 1 then it bypasses the parent and returns the grandparent instead. Thus, passing an argument of 0 is the same as passing no argument at all.

ancestors($list)

Returns a list of the parent, grandparent, great-grandparent and so on, all the way up as far as it can go. A target list reference can be passed as an argument.

heritage()

This returns the same items in the "ancestors()" list but in reverse order, from most senior parent to most junior.

PRIVATE METHODS

TODO

Inheritance of configuration data between parent and child workspaces.

AUTHOR

Andy Wardley <abw@wardley.org>.