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 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 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 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 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 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 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 Esupport@SoftwareDiamonds.comE 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 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 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 Esupport@SoftwareDiamonds.comE 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 Esupport@SoftwareDiamonds.comE 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