NAME
    File::Drawing - release, revise and retrieve contents to/from a drawing
    program module

SYNOPSIS
     ##########
     # Subroutine interface
     #
     use File::Drawing qw(
         dod_date dod_drawing_number number2pm pm2number obsolete  
         broken backup);

     $date = dod_date($sec, $min, $hour, $day, $month, $year);
     $drawing_number = dod_drawing_number( );

     $pm = number2pm($drawing_number, $repository); 
     $drawing_number = pm2number($drawing_number, $repository);

     $old_value = config( $option );
     $old_value = config( $option => $new_value);
     (@all_options) = config( );

     obsolete($drawing_number, $repository);
     broken($drawing_number, $repository);
     ($file, $backup_file) = backup($drawing_number, $repository, $dir);

     ###### 
     # Class Interface 
     #
     use File::Drawing;

     $default_options = defaults(@options);

     $old_value = $default_options->config( $option );
     $old_value = $default_options->config( $option => $new_value);
     (@all_options) = $default_options->config( );

     $drawing = new File::Drawing($contents, $white_tape, $pod, $file_contents, $drawing_number, $repository);

     $drawing = File::Drawing->retrieve($drawing_number, @options);

     $error = $drawing->release(@options);

     $error = $drawing->revise(@options);

     $date = $drawing->dod_date($sec, $min, $hour, $day, $month, $year);
     $drawing_number = $$drawing->dod_drawing_number( );

     $pm = $drawing->number2pm($drawing_number, $repository); 
     $drawing_number = $drawing->pm2number($drawing_number, $repository); 

     $drawing->obsolete($drawing_number, $repository);
     $drawing->broken($drawing_number, $repository);
     ($file, $backup_file) = $drawing->backup($drawing_number, $repository, $dir);

    Generally, if a subroutine will process a list of options, "@options",
    that subroutine will also process an array reference, "\@options",
    "[@options]", or hash reference, "\%options", "{@options}". If a
    subroutine will process an array reference, "\@options", "[@options]",
    that subroutine will also process a hash reference, "\%options",
    "{@options}". See the description for a subroutine for details and
    exceptions.

DESCRIPTION
    The "File::Drawing" program module uses American National Standards for
    drawings as a model for storing data. Commercial, governement and casual
    orgainizations have stored information over the centuries as drawings.
    Drawings probably evolved from the census that the Roman's rulers,
    started back when Rome was a little frontier town. In other words, the
    practices of the drafting displines have evolved over time and have
    stood the test of time. Any deviation must be a crystal clear advantage.
    Many of the practices are in place to avoid common and costly human
    mistakes that obviously a computerize drafting system will not make. A
    good approach is to make the computerized data structure optimum for
    computers and have the computer render the computerized data into a form
    that meets the drafting standards. The "File::Drawing" program module,
    uses the Perl program module name as a drawing repository, drawing
    number combination. The contents of the drawing is contained in the
    program module file. The <File::Drawing> program module established
    methods to retrieve contents from a program module drawing file, create
    an Perl drawing object with the contents, and methods to release and
    revise the contents in a program module drawing file from a Perl drawing
    object. Other popular methods for computerize date are the SQL and XML.
    Perl has a wide range of program modules using these approach.

    In this time in history, the Drawings are highly standardize and even
    subject to Internationl standarization agreements. The Drawing Sheet
    Size and Format conform to ANSI Y14.1-1975 or its successor. The drawing
    has a box with zone numbers running right to left alon the top and
    bottom, and zone letters running bottom to top along the sides. There is
    a section inside the box, lower right corner with the blocks for such
    things as the title, drawing number, current revision, authoriztion, and
    sheet number. There is an expandable four column table in the top right
    corner to record the revision history.

    The data in a drawing may be divided into two parts as follows:

    contents
        The contents proper is the text and graphics inside the drawing
        boundaries, not including the lower right corner blocked off area
        containing the title and the upper right corner revision history.
        The contents should conform to standards for contents such as ANSI
        X3.5-1970, Flowchart Symbols and their Usage in Information
        Processing.

    white tape
        The white tape is the drawing information that is not the contents
        such as the drawing number, revision, revision history. This is meta
        type data about the contents.

        The term white tape is derived from a common practice of writing
        part numbers and drawing numbers on white tape and affixing the
        white tape to parts and drawing media such as magnetic tape, disks,
        etc. There are vendors that sell gadgets whereby you can punch in
        text and it will generate tape with the text to affix to parts and
        drawings.

    The "File::Drawing" program module provides a format for very specific
    white tape data and 100% open, unspecified contents.

    The white tape data include information needed to support rendering of
    the drawings for delivery to other activities such as other commerical
    and industry activities and government activities.

    For example, for delivery to the US DOD, the drawing number must meet
    very specific requirements. The drawing number must comply to
    DOD-STD-100C, Drawing Practices following requirements

    401.4. *Drawing Number.* The drawing number consists of letters, numbers
    or combination of letters and numbers, which may or may not be separated
    by dashes. The number is assigned to a particular drawing for
    identification purposes by the design activity.

    402.5 *Drawing number.* The drawing number shall not exceed 15
    characters. These characters may include numbers, letter, and dashes
    with the following limitations:

    a. Letters "I", "O', "Q", "S", "X", and "Z" shall not be used; however
    letters "S" and "Z" may be used only if they are a part of the existing
    drawing numbering system. THey shall not be used in the development of
    new drawing numbering systems. Letters shall be upper case (capital
    letters).

    b. Numbers shall be arabic numberals. Fractional, decimal and Roman
    numberals shall not be used.

    c. Blank spaces are not permitted.

    d. Symbols such as: parentheseis, asterisks, virgule, degree, plus,
    minus shall not be used, except when referencing the Government or
    non-governemnt standardization document whose identification contains
    such symbol

    e. The FSCM number, drawing format size letter, and drawing revision
    letter (see paragraphs 503.2 and 602.3) are not considered part of the
    drawing number

    f. A system based on a significant numbering system or a sequentially
    assigned non-significant numbering system designed to preclude
    duplication is acceptable.

    Does the <File::Drawing> internal data format have to comply to DOD
    drawing standards? Of course not. Do they have ot comply to American
    National Standards? Of course not. In fact, just the index of American
    National Standards may on A size paper (drafting talk for 8.5" by 11")
    may be more than half as thick as the Bible. With these many rules it is
    nearly impossible to comply to the standards 100%. Some of DOD
    activities still insist that programs be delivered on mylar "paper"
    tape, logistic data delivered on punched cards.

    Is the US DOD the only activity that makes such demands on their
    contractors? Of course not. If you build semiconductor implanters where
    the base model runs 2 million dollars, one of your customers if you have
    a going business is Intel. An implanter will dope semiconductor wafers
    with different ions. If takes time, many ten, twenty, forty minutes,
    depending on the type of ion and enery levels, to take down an ion beam
    and setup and tune a new beam for a different ion. Intel does not care
    about the setup time. They will buy a different implanter for each ion
    beam. Intel's setup time is the time to move a cassette of wafers from
    one implanter to the next. In the semiconductor equipment business,
    "what Intel wants, Intel gets." Maybe not exactly what they want but
    Intel does carry a big stick to the negotiating table. Does this mean
    you cannot negotiate. Of course, not. Chrome plated front panel; No
    problem; $100,000. Solid gold front panel to match your other equipment.
    No problem; $6,000,000. Things like this only happen in dreams. The HP
    in the HP model number means High Performance, not High Price.

    Should you comply with them? If you want their business. Yes. If your
    drawings are hard copy base, then your internal drafting must be
    accordance with the standards. However, if it is computer base, such as
    "File::Drawing" program module, the internal program module data format
    does not have to be in accordance with the standards.

    The "File::Drawing" program module white tape data has open unspecificd
    properties key that may be used for data needed to render the drawing
    object as hard copies, soft display images that comply to the national,
    government, industry or company specific standards.

    The approach here is to design a "File::Drawing" class that has very
    specific hard coded "$white_tape" data formats. Perl has many program
    modules such as DBI, the XML::Simple manpage that may be used to enter
    data into "File::Drawing" objects from many different sources. The
    "$white_tape" properties key provides a home for information to render
    in formats that complies to special delivery requirements of outside
    activities.

    Thus, the "File::Drawing" methods only have to deal with very, specific,
    hard coded data and not every current or future curve ball that the DOD,
    Intel, or the New Iraq Army throws. Those things will be handle by
    vendor specific methods that filter, massage and transfer the US DOD,
    Intel or the New Iraq Army view of the world into "File::Drawing" source
    control or specification drawing objects or another appropriate type of
    "File::Drawing" drawing object that has the "File::Drawing" rose colored
    view of the world.

  "File::Drawing" Class

    The "File::Drawing" program module establishes a "File::Drawing" class
    with "release" and "retrive" methods that reads and writes the data for
    a "File::Drawing" object to and from a file. A <File::Drawing> object
    underlying data is a two member array, the first member the drawing
    contents and the second member the drawing white tape.

    A "File::Drawing" drawings object's data will be stored in a file
    separate from the <File::Drawing> class methods. The format of the file
    is a Perl program module with the data stored in a <$contents> variable
    and a <$white_tape> hash between unique comments that identify the
    drawing data. Equivalent file formats such as a file containing
    Data::Secs2 binary or ascii image of the "File::Drawing" data program
    module are also acceptable.

    The "$contents" variable is undefined and assumes whatever form is
    appropriate for the "$contents". The "$white_tape" hash is used to store
    information found and required by National Standards on the drawing,
    such as the title block, revision block, date block. The contents may be
    either a hash or an array and is the contents of the drawing.

    The "File::Drawing" class design is to try to internally to utilize Perl
    features for the best performance while supporting the introduction of
    outside data control by source control and specification "File::Drawing"
    objects from as many sources as possible and supporting rendering the
    "File::Drawing" object in as many output forms as possible.

    Thus, not matter where the source of the drawing data and the sink of
    the drawing data, the drawing data for the "File::Drawing" object is in
    a very well defined and extremely filtered from outside influences.
    After extemely, narrow well-defined data, rosed-colored view greatly
    simplies the "File::Drawing" methods and allows the design to
    concentrate and the best data form to maximize the Perl "File::Drawing"
    methods performance.

  white tape keys

    Preassigned keys for the White Tape hash are as follows:

    version
        Perl version of form \d+.\d+ starting with 0.01

    revision
        The revision is an integer starting with 0 for the initial release
        that originates the "File::Drawing" object. The revision is
        incremented by one each time the "File::Drawing" object is revised.
        The num2revision subroutine will render a revision letter(s) that
        complies to drafting standards from the revision integer.

    date_loc
        The local date and time in US DOD format which is the same as many
        countries such as Canada. DOD-STD-100C, Drawing Practices,

        402.17. *Original Date.* The method for specifying the date on a
        drawing shall be numerically - year, month, date (e.g. 75-10-15

        With computer automation of drawings, activities that took days and
        weeks, now happen in milliseconds. Thus, time is also now very
        relevant.

    date_gm
        The gm time in US DOD format.

    time_to_live
        The time in seconds from the date_gm that the drawing data is valid.
        An empty or undef signifies there is no time limit.

    active_obsolete
        The number of revisions that are maintained before the older drawing
        revisions are permantenly removed.

    repository
        For drawing program modules the program module identifier is divided
        into two parts as follows

         $repository . '::' $drawing_number

        The repository is the leading part of the program module that
        determines the location of a group of drawing program modules.

        For a file, the repository is the relative path that correponds to
        the program module respository.

        Repositories local to a specific user may add library absolute path
        to the beginning of the PERL5LIB environmental variable so that
        "File::Drawing" look for drawings the local repository first. This
        is best set when the user logs on. When the PERL5LIB environmental
        variable has been correctly set up, the repository absolute library
        root appears as a member in the "@INC" array.

    drawing_number
        The drawing number does not conform to known drawing standards. It
        is based on the site operating system that identifies the drawing
        file from other files in the operating system file system.

        The drawing number is the trailing part of the program module that
        determines the an unique drawing program modules in a repository
        group.

        For a file, the drawing_number is the relative path that correponds
        to the program module drawing_number.

    type
        The type of drawing that should be one of the American Nation
        Standards drawing types with contents in accordance with the
        Standard for that drawing type

    description
        A short description of the drawing that should be natural language
        and may or may not conform to a drawing standard.

    title
        A natural language title that may or may not conform to drawing
        standards

    keywords
        These words should be the anticipated words that a person would
        enter into a web search engine to find the drawing.

    file
        The file key is the absolute file specification for the site
        operating system for the drawing program module.

    classification
        The classification key is security level, licenses or references to
        this information.

    revision_history
        The revision_history key is at this type an unspecified revision
        history.

    authorization
        The authorization for the drawing. This may be a legal digital key
        authorization, plain text, link or left blank.

    properties
        The properties key data is unspecified. It may be used for whatever
        is necessary for rendering the drawing in a form for delivery or use
        of another activity. One anticipate use is for information for hard
        copy or soft rendering of the drawing such as a HTML page or a
        format suitable for delivery to specific activities. For web page
        rendering this could be keys for titles for list tables. For DOD
        rendering typical keys would be as follows:

        dod_fscm property
            A US DOD number that identifies the activity responsible for
            maintaining the file. It goes without saying that if activity
            does not have a dod identifying number the dod_fscm is blank or
            missing and is required for drawings to be rendered for delivery
            to the US government activities.

        dod_title property
            A title that conforms to drafing standards of noun, adjective
            where the nouns and adjectives are selected from standardize
            lists. This is empty or missing expect when the drawing must be
            rendered as a drawing conforming to American National Standards
            or a similar standard.

        dod_drawing_number property
            A drawing number that complies to DOD standards. Most industry
            and commerical activities reqirements for drawing numbers are
            the same.

            The "dod_drawing_number" method generates a number that complies
            to these requirements.

            This field is missing or empty unless a rendering for delivery
            requires this information. Once assigned it should never be
            revised or deleted.

Methods
  backup

     ($file, $backup_file) = $self->backup($drawing_number, $repository, $dir);

    The "backup" subroutine determines the absolute file for
    "$drawing_number" "$repository" and determines a backup file as follows:
    The backup repository is "$repository . '::' . $dir".

  broken

     $self->broken($drawing_number, $repository);

    The "retreive" method calls the "broken" subroutine when it cannot
    retreive the drawing data from a drawing "$repository" "$drawing_number"
    program module.The "obsolete" subroutine determines the
    "$file,$backup_file" as follows:

     ($file,$backup_file) = $self->backup($number, $repository, 'Broken')

    The "$backup_file" repositiory is ""$repository::Broken"". The drawing
    number is "$file" with an embedded revision number inserted by
    "File::Revision". The "broken" subroutine renames the broken program
    module file "$file" to "$backup_file".

  config

     $old_value = config( $option );
     $old_value = config( $option => $new_value);
     (@all_options) = config( );

    When Perl loads the "File::Drawing" program module, Perl creates a
    "$File::Drawing::default_options" object using the "default" method.

    Using the "config" as a subroutine

     config(@_) 

    writes and reads the "$File::Drawing::default_options" object directly
    using the Data::Startup::config method. Avoided the "config" and in
    multi-threaded environments where separate threads are using
    "File::Drawing". All other subroutines are multi-thread safe. They use
    "override" to obtain a copy of the "$File::Drawing::default_options" and
    apply any option changes to the copy keeping the original intact.

    Using the "config" as a method,

     $options->config(@_)

    writes and reads the "$options" object using the Data::Startup::config
    method. It goes without saying that that object should have been created
    using one of the following or equivalent:

     $default_options = $class->File::Drawing::defaults(@_);

    The underlying object data for the "File::Drawing" class of objects is a
    hash. For object oriented conservative purist, the "config" subroutine
    is the accessor function for the underlying object hash.

    Since the data are all options whose names and usage is frozen as part
    of the "File::Drawing" interface, the more liberal minded, may avoid the
    "config" accessor function layer, and access the object data directly.

  defaults

    The "defaults" subroutine establish "File::Drawing" class wide options
    options as follows:

     option                  initial value
     --------------------------------------------
     default_repository      'Etc::'

     drawing_block_regex     '(\n#<--\s*BLK\s+ID\s*=\s*\"DRAWING\"\s*-->\s*\n' .
                             '.*?' .
                             #\s*<--\s*/BLK\s*-->[ \t]*\n)'

     drawing_block_start     "#<-- BLK ID=\"DRAWING\" -->"
     drawing_block_end       "#<-- /BLK -->"

     original                 0
     clobber                  0
     inc_dir                  ''

    In general, whenever a subroutine or method, it will use
    "default_repository" whenever it has a "$repository" input and none is
    found.

    The "release", "retreive" and "revise" methods use "drawing_block_regex"
    option to locate the drawing contents and replaces the drawing contents
    with "$drawing_block_holder" option until revised contents are
    available. These subroutines have option inputs that may be used to
    override these options during the execution of that subroutine.

    The "revise" subroutine uses the "original", "clobber", and "inc_dir".
    See revise.

  dod_date

     $date = $self->dod_date($sec, $min, $hour, $day, $month, $year);

    The "dod_date" method generates a date in the yyyy/mm/dd hh:mm::ss
    numeric format. This is the format used by the US DOD and many countries
    besides the United States.

  dod_drawing_number

     $drawing_number = $self->dod_drawing_number( );

    The "dod_drawing_number" generates a drawing number that complies to
    DOD-STD-100C, 401, 402. The number should comply to most other industry
    and commerical standards for drawing numbers. The "dod_drawing_number"
    subroutine cannot generate numbers faster than one number per sec. For
    large activities, place this on a server and every one must obtain a
    number from the only copy running on the server. This number will have
    no relation or importance what so ever for the "File::Drawing" objects
    since they use a linguistic drawing numbers map one to one to the file
    system.

  number2pm

     $pm = number2pm($drawing_number, $repository); 

    The "number2pm" combines a "repository" and "$drawing_number" into a
    <$pm> name.

  new

     $self = new File::Drawing($contents, $white_tape, $pod, $file_contents, $drawing_number, $repository);

    The "new" method is used internally by the "revise" and "release"
    methods to create "File::Drawing" objects. If "new" receivces blank
    inputs, the "new" method creates the "File::Drawing" without those
    inputs. The "$drawing_number" and "$repository" are keys in the
    "$white_tape" hash and when present will override the values for those
    keys in the "$white_tape" hash.

    The "$contents" "$white_tape" "$pod" and "$file_contents" normally are
    orginally obtained by the "retreive" method from the "File::Drawings"
    program module specified by a "$repository" "$drawing_number". The data
    typically will have processed as established by the "retrieve" and
    "release" method and used to release or revise a "File::Drawing" program
    module file.

  obsolete

     $self->obsolete($drawing_number, $repository);

    The "revise" method calls the "obsolete" subroutine whenever it is about
    to revise a drawing "$repository" "$drawing_number" program module. The
    "obsolete" subroutine determines the "$file,$backup_file" as follows:

     ($file,$backup_file) = $self->backup($number, $repository, 'Obsolete')

    The "$backup_file" repositiory is ""$repository::Obsolete"". The drawing
    number is "$file" with an embedded revision number inserted by
    "File::Revision". The "obsolete" subroutine copies the program module
    "$file" about to be revised "$backup_file".

  pm2number

     $drawing_number = pm2number($pm, $repository); 

    The "pm2number" returns the "$drawing_number" for a "$pm" "$repository"
    pair. The "$drawing_number" is the trailing part of "$pm" after the
    leading "$repository" part.

  release

    The "release" method calls the "revise" method with the "original =" 1>
    option added to the "revise" method options.

  retrieve

     $drawing = File::Drawing->retrieve($drawing_number);
     $drawing = File::Drawing->retrieve($drawing_number, @options);
     $drawing = File::Drawing->retrieve($drawing_number, \@options);
     $drawing = File::Drawing->retrieve($drawing_number, \%options);

    The "retrieve" method is the top constructor for a "File::Drawing"
    object. The "retrieve" method creates a "File::Drawing" object from the
    data in a drawing program module file specified by "$drawing_number" and
    "$repository" The method uses "$File::Drawing::default_repository" for
    $respository unless overriden by the "repository" option. The program
    module file is located by <$repository> <$drawing_number> in the "@INC"
    path.

    The <retrieve> method breaks up the drawing program module file into
    four parts:

    "$white_tape $contents $file_contents $pod"

    The method obtains $white_tape and $contents by "eval" of the drawing
    block in the $file_contents by the "$File::Drawing::drawing_block_regex"
    regular expression and replacing it with
    "$File::Drawing::drawing_block_holder".

    If the "eval" fails, the "retrieve" method moves the drawing program
    module to the "Broken" directory under <$respository>. If the drawing
    program package name does not match the drawing file name, the
    "retrieve" method changes the package name to argee and calls the
    "release" method with "clobber =" 1> option automatically release the
    revised "File::Drawing" object.

    One early design actually used "require" to load in the module. However
    no was found for unloading the program module without leaving a residue
    memory. When processing a large number of drawing program modules the
    resulting memory leak brought the processing to a crawl. Creating an
    Perl object from the data from the program file, taps Perl's fine tuned
    memory management for objects. Performance is consistent so long as Perl
    drawing objects do not accumulate. When the object is no longer in use,
    Perl behind the scene memory management does an excellent job of free
    memory with no noticeable memory leaks.

    If the "retrieve" subroutine encounters an event where it cannot
    continue, it halts processing, and returns the event as a scalar string,
    with the subroutine name and version. If the "retrieve" subroutine
    return is a reference, the return is a "$drawing" object; otherwise it
    is a scalar text event message.

    The events are as follows:

     "No drawing number specified\n"
     "# Locate error. Cannot find $pm in " . join( ' ', @INC) . "\n"
     "# ($repository)$drawing_number read error. $!\n"
     "# Contents eval error. Removing ($repository)$drawing_number.\n#\t$@" 

  revise

     $error = $self->revise();
     $error = $self->revise(@options);
     $error = $self->revise(\@options);
     $error = $self->revise(\%options);

    The "revise" method revises the program module file for a
    "File::Drawing" object created by the "new" or "retrieve" method.

    Unless the "original" or "clobber" options exists, the "revise" method
    uses the "retrieve" method to obtain the current drawing and compares
    the current drawing contents and the revised contents. If the contents
    are the same, the method returns an empty string.

    If the compare was differenct or not made, the "revise" method cleans up
    the "$white_tape", incrementing the "revision" and "version" keys off
    the current drawing if that is needed to keep the revision and version
    from going backwards, copyies the current revision to the
    ""$repository::Obsolete" respository and overwrites the current drawing
    program module file with the revised "$contents" and "$white_tape"

    The "revise" method processes the following options:

    revise_repository
        Override the "$white_tape" repository key.

    revise_drawing_number
        Override the "$white_tape" drawing key.

    original
        Sets the "$white_tape" (version, revision) to ('0.01', '0')

    clobber
        Releases the "File::Drawing" object no matter what. Releases the
        drawing object even if the revised "$contents" are the same as the
        current "$contents".

    inc_path
        When a drawing program file cannot be found used the "inc_path" list
        of directories instead of "@INC" to try to locate a repository with
        the drawing number.

    If the "revise" subroutine encounters an event where it cannot continue,
    it halts processing, and returns the event as a scalar string, with the
    subroutine name and version. If the "revise" subroutine return does not
    exist, the "revise" was successful; otherwise it is an event message.

    The events are as follows:

     "# Create directory error. Path: $dirs\n" .
     "#\tDrawing: ($repository)$drawing_number\n .
     "#\t$@\n"

     "# Open Error. File: $file\n#\t$!"

    In addition, to these events, the "revise" subroutine passes along any
    events from the retrieve subroutine.

REQUIREMENTS
    Someday.

DEMONSTRATION
     #########
     # perl Drawing.d
     ###

    ~~~~~~ Demonstration overview ~~~~~

    The results from executing the Perl Code follow on the next lines as
    comments. For example,

     2 + 2
     # 4

    ~~~~~~ The demonstration follows ~~~~~

         use File::Package;
         use File::SmartNL;
         use File::Path;
         use File::Copy;
         my $fp = 'File::Package';
         my $uut = 'File::Drawing';
         my $loaded;
         my $artists1;

     ##################
     # Load UUT
     # 

     my $errors = $fp->load_package($uut)
     $errors

     # ''
     #

     ##################
     # pm2number
     # 

     $uut->pm2number('_Drawings_::Repository0::Artists_M::Madonna::Erotica','_Drawings_::Repository0')

     # 'Artists_M::Madonna::Erotica'
     #

     ##################
     # pm2number, empty repository
     # 

     $uut->pm2number('_Drawings_::Repository0::Artists_M::Madonna::Erotica','')

     # '_Drawings_::Repository0::Artists_M::Madonna::Erotica'
     #

     ##################
     # pm2number, no repository
     # 

     $uut->pm2number('Etc::Artists_M::Madonna::Erotica')

     # 'Artists_M::Madonna::Erotica'
     #

     ##################
     # number2pm
     # 

     $uut->number2pm('Artists_M::Madonna::Erotica','_Drawings_::Repository0')

     # '_Drawings_::Repository0::Artists_M::Madonna::Erotica'
     #

     ##################
     # number2pm, empty repository
     # 

     $uut->number2pm('Artists_M::Madonna::Erotica','')

     # 'Artists_M::Madonna::Erotica'
     #

     ##################
     # number2pm, no repository
     # 

     $uut->number2pm('Artists_M::Madonna::Erotica')

     # 'Etc::Artists_M::Madonna::Erotica'
     #

     ##################
     # dod_date
     # 

     $uut->dod_date(25, 34, 36, 5, 1, 104)

     # '2004/02/05 36:34:25'
     #

     ##################
     # dod_drawing_number
     # 

     length($uut->dod_drawing_number())

     # 11
     #

     ##################
     # Repository0 exists
     # 

        ####
        # Drawing must find the below directory in the @INC paths
        # in order to perform this test.
        #
     -d (File::Spec->catfile( qw(_Drawings_ Repository0)))

     # '1'
     #

     ##################
     # Created Repository1
     # 

        ####
        # Drawing must find the below directory in the @INC paths
        # in order to perform this test.
        #     
        rmtree (File::Spec->catdir( qw(_Drawings_ Repository1) ));
        mkpath (File::Spec->catdir( qw(_Drawings_ Repository1) ));
     -d (File::Spec->catfile( qw(_Drawings_ Repository1)))

     # '1'
     #

     ##################
     # Retrieve erotica source control drawing
     # 

     my $erotica2 = $uut->retrieve('Artists_M::Madonna::Erotica', repository => '_Drawings_::Repository0')
     ref($erotica2)

     # 'File::Drawing'
     #

     ##################
     # Release erotica to different repository
     # 

      my $error= $erotica2->release(revise_repository => '_Drawings_::Repository1::' )
     $error

     # ''
     #

     ##################
     # Retrieve erotica
     # 

     my $erotica1 = $uut->retrieve('Artists_M::Madonna::Erotica', repository => '_Drawings_::Repository1');
     ref($erotica1)

     # 'File::Drawing'
     #

     ##################
     # Erotica contents unchanged
     # 

      $erotica1->[0]

     # {
     #          'amazon' => {
     #                        'part_number' => 'B000002M32'
     #                      },
     #          'in_house' => {
     #                          'path' => [
     #                                      'Index',
     #                                      'Music::Index',
     #                                      'Artists::Index',
     #                                      'Artists_M::Index',
     #                                      'Artists_M::Madonna::Index',
     #                                      'Artists_M::Madonna::Erotica'
     #                                    ],
     #                          'release_date' => '05 November, 1992',
     #                          'product_name' => 'Erotica',
     #                          'artists' => [
     #                                         'Madonna'
     #                                       ],
     #                          'thumb_url' => 'thumbs/erotica.jpg',
     #                          'product_type' => 'Audio CD',
     #                          'UPC' => {
     #                                     'part_number' => '093624058526'
     #                                   },
     #                          'home' => [
     #                                      'Artists_M::Madonna::Index,music',
     #                                      'Pop_Music::Artists_M::Madonna',
     #                                      'Pop_Music::Adult_Contemporary_Singles'
     #                                    ],
     #                          'discs' => [
     #                                       [
     #                                         'Erotica (Album Edit)',
     #                                         'Erotica (Kenlou B-Boy Mix)',
     #                                         'Erotica (WO 12 Inch)',
     #                                         'Erotica (Underground Club Mix)',
     #                                         'Erotica (Masters At Work Dub)',
     #                                         'Erotica (Jeep Beats)',
     #                                         'Erotica (William Orbit 12")'
     #                                       ]
     #                                     ],
     #                          'manufacturer' => 'Warner Brothers',
     #                          'image_url' => 'images/erotica.jpg',
     #                          'part_number' => 'Artists_M::Madonna::Erotica',
     #                          'features' => [
     #                                          'CD-single'
     #                                        ]
     #                        }
     #        }
     #
      $erotica1->[1]

     # {
     #          'description' => 'Madonna's Erotica Audio CD - narcissistic, dark, brooding, hint of S&M',
     #          'title' => 'Erotica',
     #          'date_loc' => '2004/05/03 01:53:23',
     #          'revision' => '0',
     #          'active_obsolete' => '',
     #          'revision_history' => {},
     #          'drawing_number' => 'Artists_M::Madonna::Erotica',
     #          'repository' => '_Drawings_::Repository1::',
     #          'date_gm' => '2004/05/03 05:53:23',
     #          'properties' => {
     #                            'dod_title' => 'Madonna, Erotica',
     #                            'dod_fscm' => 'none-SoftDia',
     #                            'dod_drawing_number' => '04040364301'
     #                          },
     #          'keywords' => 'cd single,madonna,music,pop music,madonna,adult contemporary singles,erotica,audio cd,pop,adult,contemporary,erotica,narcissistic,dark,brooding,S&M',
     #          'classification' => 'Public Domain',
     #          'file' => 'E:\User\SoftwareDiamonds\installation\t\File\_Drawings_\Repository1\Artists_M\Madonna\Erotica.pm',
     #          'version' => '0.01',
     #          'type' => 'source_control',
     #          'authorization' => {},
     #          'time_to_live' => ''
     #        }
     #

     ##################
     # Revise erotica contents
     # 

         $erotica2->[0]->{in_house}->{num_media} =  1;
         $error = $erotica2->revise();
     $error

     # ''
     #
     -e File::Spec->catfile(qw(_Drawings_ Repository1 Obsolete Artists_M Madonna Erotica.pm))

     # '1'
     #

     ##################
     # Retrieve erotica, revision 1
     # 

     $erotica1 = $uut->retrieve('Artists_M::Madonna::Erotica', repository => '_Drawings_::Repository1');
     ref($erotica1)

     # 'File::Drawing'
     #

     ##################
     # Erotica Revision 1 contents revised
     # 

     $erotica1->[0]

     # {
     #          'amazon' => {
     #                        'part_number' => 'B000002M32'
     #                      },
     #          'in_house' => {
     #                          'path' => [
     #                                      'Index',
     #                                      'Music::Index',
     #                                      'Artists::Index',
     #                                      'Artists_M::Index',
     #                                      'Artists_M::Madonna::Index',
     #                                      'Artists_M::Madonna::Erotica'
     #                                    ],
     #                          'release_date' => '05 November, 1992',
     #                          'product_name' => 'Erotica',
     #                          'artists' => [
     #                                         'Madonna'
     #                                       ],
     #                          'thumb_url' => 'thumbs/erotica.jpg',
     #                          'product_type' => 'Audio CD',
     #                          'UPC' => {
     #                                     'part_number' => '093624058526'
     #                                   },
     #                          'home' => [
     #                                      'Artists_M::Madonna::Index,music',
     #                                      'Pop_Music::Artists_M::Madonna',
     #                                      'Pop_Music::Adult_Contemporary_Singles'
     #                                    ],
     #                          'discs' => [
     #                                       [
     #                                         'Erotica (Album Edit)',
     #                                         'Erotica (Kenlou B-Boy Mix)',
     #                                         'Erotica (WO 12 Inch)',
     #                                         'Erotica (Underground Club Mix)',
     #                                         'Erotica (Masters At Work Dub)',
     #                                         'Erotica (Jeep Beats)',
     #                                         'Erotica (William Orbit 12")'
     #                                       ]
     #                                     ],
     #                          'manufacturer' => 'Warner Brothers',
     #                          'image_url' => 'images/erotica.jpg',
     #                          'part_number' => 'Artists_M::Madonna::Erotica',
     #                          'num_media' => 1,
     #                          'features' => [
     #                                          'CD-single'
     #                                        ]
     #                        }
     #        }
     #
     $erotica1->[1]->{version}

     # '0.02'
     #
     $erotica1->[1]->{revision}

     # '1'
     #
     $erotica1->[1]->{date_gm}

     # '2004/05/03 05:53:23'
     #
     $erotica1->[1]->{date_loc}

     # '2004/05/03 01:53:23'
     #
         $erotica2->[1]->{classification} = 'Top Secret';
         $error = $erotica2->revise();
     $error

     # ''
     #
     -e File::Spec->catfile(qw(_Drawings_ Repository1 Obsolete Artists_M Madonna Erotica-01.pm))

     # undef
     #

     ##################
     # Retrieve erotica revision 2
     # 

     $erotica1 = $uut->retrieve('Artists_M::Madonna::Erotica', repository => '_Drawings_::Repository1');
     ref($erotica1)

     # 'File::Drawing'
     #
      $erotica1->[1]

     # {
     #          'description' => 'Madonna's Erotica Audio CD - narcissistic, dark, brooding, hint of S&M',
     #          'title' => 'Erotica',
     #          'date_loc' => '2004/05/03 01:53:24',
     #          'revision' => '2',
     #          'active_obsolete' => '',
     #          'revision_history' => {},
     #          'drawing_number' => 'Artists_M::Madonna::Erotica',
     #          'repository' => '_Drawings_::Repository1::',
     #          'date_gm' => '2004/05/03 05:53:24',
     #          'properties' => {
     #                            'dod_title' => 'Madonna, Erotica',
     #                            'dod_fscm' => 'none-SoftDia',
     #                            'dod_drawing_number' => '04040364301'
     #                          },
     #          'keywords' => 'cd single,madonna,music,pop music,madonna,adult contemporary singles,erotica,audio cd,pop,adult,contemporary,erotica,narcissistic,dark,brooding,S&M',
     #          'classification' => 'Top Secret',
     #          'file' => 'E:\User\SoftwareDiamonds\installation\t\File\_Drawings_\Repository1\Artists_M\Madonna\Erotica.pm',
     #          'version' => '0.03',
     #          'type' => 'source_control',
     #          'authorization' => {},
     #          'time_to_live' => ''
     #        }
     #

     ##################
     # Retrieve _Drawings_::Erotica
     # 

     $erotica2 = $uut->retrieve('_Drawings_::Erotica', repository => '');
     ref($erotica2)

     # 'File::Drawing'
     #

     ##################
     # Revise erotica revision 2
     # 

     $error = $erotica2->revise(revise_drawing_number=>'Artists_M::Madonna::Erotica', revise_repository=>'_Drawings_::Repository1');
     $error

     # ''
     #
     -e File::Spec->catfile(qw(_Drawings_ Repository1 Obsolete Artists_M Madonna Erotica-2.pm))

     # '1'
     #

     ##################
     # Retrieve erotica revision 3
     # 

     $erotica1 = $uut->retrieve('Artists_M::Madonna::Erotica', repository => '_Drawings_::Repository1');
     ref($erotica1)

     # 'File::Drawing'
     #
     $erotica1->[1]->{version}

     # '0.04'
     #
     $erotica1->[1]->{revision}

     # '3'
     #
     $erotica1->[1]->{date_gm}

     # '2004/05/03 05:53:24'
     #
     $erotica1->[1]->{date_loc}

     # '2004/05/03 01:53:24'
     #

     ##################
     # Erotica revision 3 file contents revised
     # 

      $erotica1->[3]

     # '#!/usr/bin/perl
     ##
     ##
     #package _Drawings_::Repository1::Artists_M::Madonna::Erotica;

     #use strict;
     #use warnings;
     #use warnings::register;

     ##<-- BLK ID="DRAWING" -->
     ##<-- /BLK -->

     ######
     ## This section may be used for Perl subroutines and expressions.
     ##
     #print "Hello world from _Drawings_::Erotica\n";

     #1
     #'
     #

     ##################
     # Retrieve Sandbox erotica
     # 

        unshift @INC,'_Sandbox_';
        $erotica2 = $uut->retrieve('Artists_M::Madonna::Erotica', repository => '_Drawings_::Repository1');
     ref($erotica2)

     # 'File::Drawing'
     #

     ##################
     # Revise erotica revision 3
     # 

         shift @INC;
         $error = $erotica2->revise( );
     $error

     # ''
     #
     -e File::Spec->catfile(qw(_Drawings_ Repository1 Obsolete Artists_M Madonna Erotica-3.pm))

     # '1'
     #

     ##################
     # Retrieve erotica revision 4
     # 

     $erotica1 = $uut->retrieve('Artists_M::Madonna::Erotica', repository => '_Drawings_::Repository1')
     ref($erotica1)

     # 'File::Drawing'
     #
     $erotica1->[1]->{version}

     # '0.05'
     #
     $erotica1->[1]->{revision}

     # '4'
     #
     $erotica1->[1]->{date_gm}

     # '2004/05/03 05:53:24'
     #
     $erotica1->[1]->{date_loc}

     # '2004/05/03 01:53:24'
     #

     ##################
     # Erotica Revision 4 file contents revised
     # 

      $erotica1->[3]

     # '#!/usr/bin/perl
     ##
     ##
     #package _Drawings_::Repository1::Artists_M::Madonna::Erotica;

     #use strict;
     #use warnings;
     #use warnings::register;

     ##<-- BLK ID="DRAWING" -->
     ##<-- /BLK -->

     ######
     ## This section may be used for Perl subroutines and expressions.
     ##
     #print "Hello world from Sandbox\n";

     #1
     #'
     #
     rmtree (File::Spec->catdir( qw(_Drawings_ Repository1) ));

QUALITY ASSURANCE
    Running the test script "Drawing.t" verifies the requirements for this
    module. The "tmake.pl" cover script for Test::STDmaker automatically
    generated the "Drawing.t" test script, "Drawing.d" demo script, and
    "t::File::Drawing" STD program module POD, from the "t::File::Drawing"
    program module contents. The "tmake.pl" cover script automatically ran
    the "Drawing.d" demo script and inserted the results into the
    'DEMONSTRATION' section above. The "t::File::Drawing" program module is
    in the distribution file File-Drawing-$VERSION.tar.gz.

NOTES
  Author

    The holder of the copyright and maintainer is

    <support@SoftwareDiamonds.com>

  COPYRIGHT NOTICE

    Copyrighted (c) 2002 Software Diamonds

    All Rights Reserved

  Binding Requirements Notice

    Binding requirements are indexed with the pharse 'shall[dd]' where dd is
    an unique number for each header section. This conforms to standard
    federal government practices, STD490A 3.2.3.6. In accordance with the
    License, Software Diamonds is not liable for any requirement, binding or
    otherwise.

  License

    Software Diamonds permits the redistribution and use in source and
    binary forms, with or without modification, provided that the following
    conditions are met:

    1   Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.

    2   Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.

    SOFTWARE DIAMONDS, http://www.softwarediamonds.com, PROVIDES THIS
    SOFTWARE 'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
    NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SOFTWARE
    DIAMONDS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    SPECIAL,EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
    TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,DATA, OR
    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF NEGLIGENCE OR OTHERWISE) ARISING IN
    ANY WAY OUT OF THE POSSIBILITY OF SUCH DAMAGE.

SEE ALSO
    Data::Dumper
    Data::Secs2
    Data::SecsPack
    Data::Startup
    File::Revision
    File::Where
    Docs::Site_SVD::File_Drawing
    Test::STDmaker
    Test::Tech
    ExtUtils::SVDmaker
Title Page
     Software Version Description

     for

      File::Drawing - release, revise and retrieve contents to/from a drawing program module

     Revision: -

     Version: 0.01

     Date: 2004/05/04

     Prepared for: General Public 

     Prepared by:  SoftwareDiamonds.com E<lt>support@SoftwareDiamonds.comE<gt>

     Copyright: copyright © 2003 Software Diamonds

     Classification: NONE

1.0 SCOPE
    This paragraph identifies and provides an overview of the released
    files.

  1.1 Identification

    This release, identified in 3.2, is a collection of Perl modules that
    extend the capabilities of the Perl language.

  1.2 System overview

    The <File::Drawing> program module uses American National Standards for
    drawings as a model for storing data. The drafting displines practices
    have evolved over time and have stood the test of time. Any deviation
    must be a crystal clear advantage. Many of the practices are in place to
    avoid common and costly human mistakes that obviously a computerize
    drafting system will not make. A good approach is to make the
    computerized data structure optimum for computers and have the computer
    render the computerized data into a form that meets the drafting
    standards. The "File::Drawing" program module, uses the Perl program
    module name as a drawing repository, drawing number combination. The
    contents of the drawing is contained in the program module file. The
    <File::Drawing> program module established methods to retrieve contents
    from a program module drawing file, create an Perl drawing object with
    the contents, and methods to release and revise the contents in a
    program module drawing file from a Perl drawing object.

  1.3 Document overview.

    This document releases File::Drawing version 0.01 providing a
    description of the inventory, installation instructions and other
    information necessary to utilize and track this release.

3.0 VERSION DESCRIPTION
    All file specifications in this SVD use the Unix operating system file
    specification.

  3.1 Inventory of materials released.

    This document releases the file

     File-Drawing-0.01.tar.gz

    found at the following repository(s):

      http://www.softwarediamonds/packages/
      http://www.perl.com/CPAN/authors/id/S/SO/SOFTDIA/

    Restrictions regarding duplication and license provisions are as
    follows:

    Copyright.
        copyright © 2003 Software Diamonds

    Copyright holder contact.
         603 882-0846 E<lt>support@SoftwareDiamonds.comE<gt>

    License.
        Software Diamonds permits the redistribution and use in source and
        binary forms, with or without modification, provided that the
        following conditions are met:

        1   Redistributions of source code, modified or unmodified must
            retain the above copyright notice, this list of conditions and
            the following disclaimer.

        2   Redistributions in binary form must reproduce the above
            copyright notice, this list of conditions and the following
            disclaimer in the documentation and/or other materials provided
            with the distribution.

        SOFTWARE DIAMONDS, http://www.SoftwareDiamonds.com, PROVIDES THIS
        SOFTWARE 'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
        BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
        FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
        SOFTWARE DIAMONDS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
        SPECIAL,EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
        LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
        USE,DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
        ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING USE OF THIS SOFTWARE, EVEN IF ADVISED OF
        NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE POSSIBILITY
        OF SUCH DAMAGE.

  3.2 Inventory of software contents

    The content of the released, compressed, archieve file, consists of the
    following files:

     file                                                         version date       comment
     ------------------------------------------------------------ ------- ---------- ------------------------
     lib/Docs/Site_SVD/File_Drawing.pm                            0.01    2004/05/04 new
     MANIFEST                                                     0.01    2004/05/04 generated new
     Makefile.PL                                                  0.01    2004/05/04 generated new
     README                                                       0.01    2004/05/04 generated new
     lib/File/Drawing.pm                                          0.01    2004/05/04 new
     t/File/Drawing.d                                             0.01    2004/05/04 new
     t/File/Drawing.pm                                            0.01    2004/05/04 new
     t/File/Drawing.t                                             0.01    2004/05/04 new
     t/File/_Drawings_/Repository0/Artists_M/Madonna/Erotica.pm   0.01    2004/05/04 new
     t/File/_Sandbox_/_Drawings_/Repository1/Artists_M/Madonna/Er 0.01    2004/05/04 new
     t/File/_Drawings_/Erotica.pm                                 0.02    2004/05/04 new
     t/File/_Drawings_/Repository0/Artists/Index.pm               0.01    2004/05/04 new
     t/File/_Drawings_/Repository0/Artists/IndexBad.pm            0.05    2004/05/04 new
     t/File/File/Package.pm                                       1.16    2004/05/04 new
     t/File/Test/Tech.pm                                          1.22    2004/05/04 new

  3.3 Changes

    Changes are as follows:

    Test-TestUtil-0.01
        Originated

        .

  3.4 Adaptation data.

    This installation requires that the installation site has the Perl
    programming language installed. There are no other additional
    requirements or tailoring needed of configurations files, adaptation
    data or other software needed for this installation particular to any
    installation site.

  3.5 Related documents.

    There are no related documents needed for the installation and test of
    this release.

  3.6 Installation instructions.

    Instructions for installation, installation tests and installation
    support are as follows:

    Installation Instructions.
        To installed the release file, use the CPAN module pr PPM module in
        the Perl release or the INSTALL.PL script at the following web site:

         http://packages.SoftwareDiamonds.com

        Follow the instructions for the the chosen installation software.

        If all else fails, the file may be manually installed. Enter one of
        the following repositories in a web browser:

          http://www.softwarediamonds/packages/
          http://www.perl.com/CPAN/authors/id/S/SO/SOFTDIA/

        Right click on 'File-Drawing-0.01.tar.gz' and download to a
        temporary installation directory. Enter the following where $make is
        'nmake' for microsoft windows; otherwise 'make'.

         gunzip File-Drawing-0.01.tar.gz
         tar -xf File-Drawing-0.01.tar
         perl Makefile.PL
         $make test
         $make install

        On Microsoft operating system, nmake, tar, and gunzip must be in the
        exeuction path. If tar and gunzip are not install, download and
        install unxutils from

         http://packages.softwarediamonds.com

    Prerequistes.
         'File::Where' => '0.04',
         'File::Revision' => '1.04',
         'File::SmartNL' => '1.14',
         'Data::Secs2' => '1.19',
         'Data::SecsPack' => '0.04',
         'Data::Startup' => '0.02',

    Security, privacy, or safety precautions.
        None.

    Installation Tests.
        Most Perl installation software will run the following test
        script(s) as part of the installation:

         t/File/Drawing.t

    Installation support.
        If there are installation problems or questions with the
        installation contact

         603 882-0846 E<lt>support@SoftwareDiamonds.comE<gt>

  3.7 Possible problems and known errors

    There is still much work needed to ensure the quality of this module as
    follows:

    *   State the functional requirements for each method including not only
        the GO paths but also what to expect for the NOGO paths

    *   All the tests are GO path tests. Should add NOGO tests.

    *   Add the requirements addressed as *# R: * comment to the tests

    *   Write a program to build a matrix to trace test step to the
        requirements and vice versa by parsing the *# R: * comments.
        Automatically insert the matrix in the module POD.

4.0 NOTES
    The following are useful acronyms:

    .d  extension for a Perl demo script file

    .pm extension for a Perl Library Module

    .t  extension for a Perl test script file

    POD Plain Old Documentation

2.0 SEE ALSO
    File::Drawing
    Docs::US_DOD::SVD
