NAME

CAD::Drawing::IO - I/O methods for the CAD::Drawing module

Description

This module provides the load() and save() functions for CAD::Drawing and provides a point of flow-control to deal with the inheritance and other trickiness of having multiple formats handled through a single module.

AUTHOR

Eric L. Wilhelm <ewilhelm at cpan dot org>

http://scratchcomputing.com

COPYRIGHT

LICENSE

This module is distributed under the same terms as Perl. See the Perl source package for details.

You may use this software under one of the following licenses:

  (1) GNU General Public License
    (found at http://www.gnu.org/copyleft/gpl.html)
  (2) Artistic License
    (found at http://www.perl.com/pub/language/misc/Artistic.html)

NO WARRANTY

This software is distributed with ABSOLUTELY NO WARRANTY. The author, his former employer, and any other contributors will in no way be held liable for any loss or damages resulting from its use.

Modifications

The source code of this module is made freely available and distributable under the GPL or Artistic License. Modifications to and use of this software must adhere to one of these licenses. Changes to the code should be noted as such and this notification (as well as the above copyright information) must remain intact on all copies of the code.

Additionally, while the author is actively developing this code, notification of any intended changes or extensions would be most helpful in avoiding repeated work for all parties involved. Please contact the author with any such development plans.

front-end Input and output methods

The functions load() and save() are responsible for determining the filetype (with forced types available via $options{type}.) These then call the appropriate <Package>::load() or <Package>::save() functions.

See the Plug-In Architecture section for details on how to add support for additional filetypes.

Beginning with version 0.26, a string-based type specification is available by using $filename = "$type:filename". While this prevents you from saving files with colons in the names, an explicit type passed in the options will allow it. This gives the added bonus that your program's users may directly control the output type simply by giving a <type>:<file> argument on the command line (if that is where you get your filenames.)

save

Saves a file to disk. See the save<type> functions in this file and the other filetype functions in the CAD::Drawing::IO::<type> modules.

See each save<type> function for available options for that type.

While you may call the save<type> function directly (if you include the module), it is recommended that you stick to the single point of interface provided here so that your code does not become overwhelmingly infected with hard-coded filetypes.

Note that this method also implements forking. If $options{forkokay} is true, save() will return the pid of the child process to the parent process and setup the child to exit after saving (with currently no way for the child to give a return value to the parent (but (-e $filename) might work for you).)

  $drw->save($filename, \%options);

load

Loads a file from disk. See the load<type> functions in this file and the other filetype functions in the CAD::Drawing::IO::<type> modules.

See each load<type> function for available options for that type.

In most cases %options may contain the selection methods available via the CAD::Drawing::check_select() function.

While you may call the load<type> function directly (if you include the module), it is recommended that you stick to the single point of interface provided here.

  $drw->load($filename, \%options);

can_load

Returns true if the plugins think they can load this filename (no test-loading is done, only verification of the type.)

  $drw->can_load($filename);

Plug-In Architecture

Plug-ins are modules which are under the CAD::Drawing::IO::* namespace. This namespace is searched at compile time, and any modules found are require()d inside of an eval() block (see BEGIN.) Compile failure in any one of these modules will be printed to STDERR, but will not halt the running program.

Each plug-in is responsible for declaring one or all of the following variables:

  our $can_save_type = "type";
  our $can_load_type = "type (or another type)";
  our $is_inherited = 1; # or 0 (or undef())

If a package claims to be able to load or save a type, then it must contain the functions load() or save() (respectively.) Package which declare $is_inherited as a true value will become methods of the CAD::Drawing class (though their load() and save() functions will not be visible due to their location in the inheritance tree.)

BEGIN

The BEGIN block implements the module path searching (looking only in directories of @INC which contain a "CAD/Drawing/IO/" directory.)

For each plug-in which is found, code references are saved for later use by the diskaction() function.

diskaction

This function is for internal use, intended to consolidate the type selection and calling of load/save methods.

  $drw->diskaction("load|save", $filename, $type, \%options);

For each plug-in package which was located in the BEGIN block, the function <Package>::check_type() will be called, and must return a true value for the package to be used for $action.

Utility Functions

These are simply inherited by the CAD::Drawing module for your direct usage.

outloop

Crazy new experimental output method. Each entity supported by the format should have a key to a function in %functions, which is expected to accept the following input data:

  $functions{$ent_type}->($obj, \%data);

The %data hash is passed verbatim to each function.

  $count = $drw->outloop(\%functions, \%data);

In addition to each of the $ent_type keys, functions for the keys 'before' and 'after' may also be defined. These (if they are defined) will be called before and after each entity, with the same arguments as the $ent_type functions.

is_persistent

Returns 1 if $filename points to a persistent (directory / db) drawing.

  $drw->is_persistent($filename);