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
<
[email protected]>
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>
[email protected]<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>
[email protected]<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>
[email protected]<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
