oracular (3) Badger::Workspace.3pm.gz

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.