synopsis.
The directory address object is used to handle the addressing aspects of a directory ("folder") in a computer file system. It or its child class directory_o can be used for handling a directory. An instance of the directory address class need not correspond to an actual directory in the file system, except for a few operations (full_path(), expand_path()) that need to access the file system for information. So you are free to create, modify, and destroy these objects without needing to worry about them being real or not. Thus you can create examples, experiments, or models of directory addresses without an actual file system.

string variables (string_o) are used to provide information to these objects. The syntax of the text in the strings depends on the environment. For Microsoft, devices can be included in the path and backslashes should be used as separators (devices are represented by a single capital letter followed by a colon, eg, "D:").

member functions (primary)

directory_address_o_o()
SIGNATURE: directory_address_o ()
SYNOPSIS:
instantiaate a directory address instance. The object will initially have no path. Prior to setting a path, most operations will return an error condition and / or an empty string ("") for the directory path.
 

directory_address_o_o(directory_address_o_o)
SIGNATURE: directory_address_o (const directory_address_o &rhs)
SYNOPSIS:
makes an exact copy of the RHS object. if the copied object is uninitialized, the current object will be uninitialized also.
 

operator = (directory_address_o_o)
SIGNATURE: const directory_address_o &operator = (const directory_address_o &RHS)
SYNOPSIS: copies exactly the RHS object; previous contents lost
 

destructor
SIGNATURE: ~directory_address_o ()
 

directory_address_o_o(<args>)
SIGNATURE: directory_address_o (const string_o &path)
SYNOPSIS:
creates a new directory address instance and sets it to the given path. The syntax of the "path" variable should conform to the operating system environment that it is run on: in unix environments, a forward-slash ("/") separates directories and in Microsoft environments a back-slash ("\") should be used. If there is a syntax error in the input parameter "path", the object will not be initialized.
 

directory_address_o_o(<args>)
SIGNATURE: directory_address_o (const string_o &path, const string_o &dev)
SYNOPSIS: this constructor sets the directory path to "path" and the device name to "dev". It is a convenience function.
TRAITS: the order of the parameters of this constructor may seem a bit backwards
 

operator = (directory_address_o_o)
SIGNATURE: const directory_address_o &operator = (const string_o &path)
SYNOPSIS:
maps the variable in 'path', a string object, to the current directory address. it sets the object to the path specified in the string "path". This path need not actually exist.
 

{implicit_conversion}()
SIGNATURE: operator string_o ()
SYNOPSIS:
gets the contents of the current object, formats it as a string, and returns a new string object. This operation is equivalent to path(string_o &).
 

name()
SIGNATURE: const string_o &name (int *pi = NULL) const
SYNOPSIS: returns the directory path, as a string object.
PARAMETERS

pi: error indicator output variable. Currently this is always set to 0.

TRAITS: the name ("name()") is confusing, and this function will most likely be phased out.
 

leaf()
SIGNATURE: const string_o leaf (int *pi = NULL) const
SYNOPSIS: returns the leaf node directory name, as a string (if set).
DESCRIPTION:
if the path maintained by the object is "/tmp/foo/subdir", this function will return "subdir". if it is "/xxx", this function will return "xxx".
 

device()
SIGNATURE: const string_o device (int *pi = NULL) const
SYNOPSIS: returns the device name, as a string (if any).
TRAITS: this function was added exclusively for Microsoft OSes.
 

exists()
SIGNATURE: boolean exists (int *pi = NULL) const
SYNOPSIS: tells if the path the object is set to is real
PARAMETERS

pi: error indicator output variable. values:
0: directory exists;
zErr_NotFound: directory does not exist;
zErr_TypeIncorrect: item exists, but is not a directory

DESCRIPTION:
this tests the object's value. It checks the local file system for a matching directory path, and if found, returns TRUE; otherwise, it returns FALSE and pi is set to non-zero value.
 

ostream &operator <<()
SIGNATURE: std::ostream &operator << (std::ostream &oso, const directory_address_o &da)
SYNOPSIS: automatic formatting of directory address object to string format. Prints out the directory value
 

operator !=()
SIGNATURE: int operator != (const directory_address_o &rhs) const
SYNOPSIS: compares current directory address to rhs. This function is the converse of "::operator == (rhs)"
RETURNS:
0: directories are equivalent
1: directories are different
 

operator ==()
SIGNATURE: int operator == (const directory_address_o &rhs) const
SYNOPSIS:
compares current directory address to rhs. Rather than doing a string compare, this member function compares each subdirectory to that of "rhs". As soon as there is a difference, 0 is returned. If all components match exactly, 1 is returned.
RETURNS:
0: directories are different
1: directories are equivalent
 

dir_parent()
SIGNATURE: const string_o &dir_parent ()
SYNOPSIS: returns a string containing the OS notation for the meaning of "parent directory".
DESCRIPTION: this is a symbolic representation of what on Microsoft and unix platforms is "..".
TRAITS:
this isd a static member function - it takes no specific object instance to use it. call it like so:

string_o s = directory_address_o::dir_parent();
::chdir (s.data());

 

dir_current()
SIGNATURE: const string_o &dir_current ()
SYNOPSIS: returns a string containing the OS notation for the meaning of "current directory".
DESCRIPTION: this is a symbolic representation of what on Microsoft and unix platforms is ".".
TRAITS:
this isd a static member function - it takes no specific object instance to use it:

string_o sdir(".");
if (sdir == directory_address_o::dir_current())
    std::cout << "It works!\n";

 

set()
SIGNATURE: int set (const string_o &s_path)
SYNOPSIS:
sets or resets the current directory address object to the path specified by "s_path". The input variable need not correspond to an actual physical path, but it must have valid syntax in order for the operation to succeed.
 

reset()
SIGNATURE: int reset ()
SYNOPSIS: resets the current object to at-construction state. Any existing path in the current object is wiped out.
 

path()
SIGNATURE: int path (string_o &s, int *pi = NULL) const
SYNOPSIS:
puts the directory value (the path) into string form, returning it in the output parameter "s". a directory's path is simply the concatenation of each subdirectory (separated by the "directory separator" symbol).
 

full_path()
SIGNATURE: int full_path (string_o &s, int *pi = NULL) const
SYNOPSIS:
This operation converts the path specified by this object into a real path on the current system. It gets the directory, puts it into string form, returns it in the output parameter "s". This function uses expand_path() for the actual analysis work.
 

expand_path()
SIGNATURE: int expand_path (const string_o &in, string_o &out, int *pi = NULL) const
SYNOPSIS:
this subroutine converts the path specified by "in" into a real path on the current system. The path starts with the root symbol, and includes any devices (in Microsoft environments, they are denoted by a single letter, followed by a colon, eg, "C:").
Since this function doesn't use any data or apply to a specific directory address object, but closely related to directory addresses, it is a static member function. Call it like so:

  string_o spath_actual, spath_relative = "..\\parent";
  directory_address_o::expand_path (spath_relative, spath_actual);
  std::cout << "the true path is: " << spath_actual << "\n";

TRAITS: the error processing-notification in this function is very poor currently ("pi" is not used).
 

add_subdir()
SIGNATURE: int add_subdir (const string_o &s, int *pe = NULL)
SYNOPSIS:
appends a [new] 'leaf node' directory to the object's current path. The directory represented by "s" cannot have subdirectories of its own - only 1 individual directory (aka inode).
PARAMETERS

• s: name of the additional directory to tack on
• pe: error indicator output variable. values:
  0: addition successfully performed
  zErr_Param_NotSet: bad parameter - empty string used
  zErr_Param_BadFormat: supplied string has sub-directories (not allowed).

 

delete_leafdir()
SIGNATURE: int delete_leafdir (int *pe = NULL)
SYNOPSIS: deletes the final ("leaf") subdirectory of the current object (if any)
 

expand_path()
SIGNATURE: int expand_path (const string_o &sin, string_o &sot, int *pi = NULL);
SYNOPSIS: expand a given path, so that it starts with "/"
PARAMETERS

• sin: the string object containing the path to "expand"
• sot: the output; "sin" expanded
• pi: error indicator [output] varlable. values:
  0: success
  zErr_Data_BadSyntax: invalid character or symbol encountered in "sin"
  zErr_DataUnexpected: encounted a device symbol (":") in the middle of the path string
  zErr_DataUnknown: strange (illegal) character encountered
  zErr_Data_BadFormat: contents of 'sin' not correctly formatted. This error happens when the string contains "/.." inside - possibly an attempt to go up one directory from the last position?

DESCRIPTION:
given a string whos value represents a valid path on the local file system, this converts the path to a fully-qualified disk file system path.
TRAITS: this isd a static member function - it takes no specific object instance to use it
 

bad_reference()
SIGNATURE: const directory_address_o &bad_reference ()
SYNOPSIS:
returns the "bad reference" - standard Z Directory "orthodox" construct, used for functions that return a reference. The return address of the object represents a singleton "bad" object, and that the function returning this reference failed.
TRAITS: this isd a static member function - it takes no specific object instance to use it
 

clone()
SIGNATURE: directory_address_o *clone () const
SYNOPSIS:
allocates a new directory address object and copies the contents of the current object into it - eg, a new object is cloned. returns a handle to the newly created object.
 

ostream redirect()
SIGNATURE: std::ostream &operator << (std::ostream &os, const directory_address_o &da)
SYNOPSIS: maps the directory address to a string, suitable for printing
 

note.
In the past, there has been some variation and inconsistency, and a proliferation of functions and objects to manage the concept of a "directory separator". This has generally been the character '/' (forward-slash) on unix-type operating systems and the character '\' on Microsoft-type OS's. In true Vettrasoft style, a string is generally used to hold this item. In the past, each directory address object has lugged around its own string object to manage the directory separator. There probably was the notion of allowing the program to set different strings to different directory address instances, to handle the obscure case of someone wanting to model a network of computers with heterogeneous operating systems. All this is being phased out, and any need for the directory separator is to be handled by the global function z_DIRSEP() from now on (which returns a string object - string_o). In the event some robotic operating system of the futrure decides to use the character sequence "::-O(" to denote the start of a new subdirectory, the Z Directory is ready.

history.

??? 11/21/1995: "pathexp.c" migrated & merged into this file
Thu 05/30/2002: new #define naming conventions ("zos_", "zcc_")
Wed 08/27/2003: reworked "directory_address_o::name()"
Wed 02/09/2011: add device (eg drive letter) to input & output strings
Tue 02/15/2011: added add_subdir() & delete_leafdir() {--GD}