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

   init(\%config)
       This method redefines the default initialisation method.  It calls the init_workplace()
       method inherited from Badger::Workplace and then calls the init_workspace() method to
       perform any workspace-specific initialisation.

   init_workspace(\%config)
       This method performs workspace-specific initialisation.  In this module it simply calls
       init_config().  Subclasses may redefine it to do something different.

   init_config(\%config)
       This initialised the Badger::Config::Filesystem object which manages the config
       configuration directory.

   init_dirs(\%config)
   init_parent(\%config)
   write_config_file($uri, $data)
       Delegates to the method of the same name provided by the filesystem config object - see
       Badger::Config::Filesystem.

TODO

       Inheritance of configuration data between parent and child workspaces.

AUTHOR

       Andy Wardley <abw@wardley.org>.

COPYRIGHT

       Copyright (C) 2008-2014 Andy Wardley.  All Rights Reserved.