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

 ##########
 # 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.

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, XML::Simple 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.

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.

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 (num2revision in Data::Revision) 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.

 ($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.

 $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.

 $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.

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 (revise in File::Drawings).

 $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.

 $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.

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

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

 $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.

 $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.

 $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.

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

 $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$@" 

 $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.

Someday.

 #########
 # 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) ));

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.

The holder of the copyright and maintainer is

<support@SoftwareDiamonds.com>

Copyrighted (c) 2002 Software Diamonds

All Rights Reserved

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 (3.2.3.6 in Docs::US_DOD::STD490A). In accordance with the License, Software Diamonds is not liable for any requirement, binding or otherwise.

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.

Data::Dumper

Data::Secs2

Data::SecsPack

Data::Startup

File::Revision

File::Where

Docs::Site_SVD::File_Drawing (Docs::Site_SVD::File_Drawing)

Test::STDmaker

Test::Tech

ExtUtils::SVDmaker