.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CAD::Drawing::IO 3"
.TH CAD::Drawing::IO 3 "2008-01-04" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
CAD::Drawing::IO \- I/O methods for the CAD::Drawing module
.SH "Description"
.IX Header "Description"
This module provides the \fIload()\fR and \fIsave()\fR 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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Eric L. Wilhelm <ewilhelm at cpan dot org>
.PP
http://scratchcomputing.com
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This module is copyright (C) 2004\-2006 by Eric L. Wilhelm.  Portions
copyright (C) 2003 by Eric L. Wilhelm and A. Zahner Co.
.SH "LICENSE"
.IX Header "LICENSE"
This module is distributed under the same terms as Perl.  See the Perl
source package for details.
.PP
You may use this software under one of the following licenses:
.PP
.Vb 4
\&  (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)
.Ve
.SH "NO WARRANTY"
.IX Header "NO WARRANTY"
This software is distributed with \s-1ABSOLUTELY\s0 \s-1NO\s0 \s-1WARRANTY\s0.  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.
.SH "Modifications"
.IX Header "Modifications"
The source code of this module is made freely available and
distributable under the \s-1GPL\s0 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.
.PP
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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "CAD::Drawing" 4
.IX Item "CAD::Drawing"
The frontend.
.Sh "Builtin Backends"
.IX Subsection "Builtin Backends"
The following modules are included in the main distribution.
.IP "CAD::Drawing::IO::Circ" 4
.IX Item "CAD::Drawing::IO::Circ"
.PD 0
.IP "CAD::Drawing::IO::Compressed" 4
.IX Item "CAD::Drawing::IO::Compressed"
.IP "CAD::Drawing::IO::FlatYAML" 4
.IX Item "CAD::Drawing::IO::FlatYAML"
.IP "CAD::Drawing::IO::Split" 4
.IX Item "CAD::Drawing::IO::Split"
.PD
.Sh "External Backends"
.IX Subsection "External Backends"
.IP "CAD::Drawing::IO::OpenDWG" 4
.IX Item "CAD::Drawing::IO::OpenDWG"
\&\s-1DWG/DXF\s0 handling using the OpenDWG toolkit.
.IP "CAD::Drawing::IO::PostScript" 4
.IX Item "CAD::Drawing::IO::PostScript"
Postscript output.
.IP "CAD::Drawing::IO::Image" 4
.IX Item "CAD::Drawing::IO::Image"
Image::Magick based output.
.IP "CAD::Drawing::IO::PgDB" 4
.IX Item "CAD::Drawing::IO::PgDB"
PostgreSQL connected drawing database.
.IP "CAD::Drawing::IO::Tk" 4
.IX Item "CAD::Drawing::IO::Tk"
Tk::WorldCanvas popup viewer \*(-- not exactly an input/output backend, but
it uses much of the same facility because it is primarily just output to
a display.
.SH "front-end Input and output methods"
.IX Header "front-end Input and output methods"
The functions \fIload()\fR and \fIsave()\fR are responsible for determining the
filetype (with forced types available via \f(CW$options\fR{type}.)  These then
call the appropriate <Package>::\fIload()\fR or <Package>::\fIsave()\fR functions.
.PP
See the Plug-In Architecture section for details on how to add support
for additional filetypes.
.PP
Beginning with version 0.26, a string-based type specification is
available by using \f(CW$filename\fR = \*(L"$type:filename\*(R".  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.)
.Sh "save"
.IX Subsection "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.
.PP
See each save<type> function for available options for that type.
.PP
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.
.PP
Note that this method also implements forking.  If \f(CW$options\fR{forkokay} is
true, \fIsave()\fR 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 \f(CW$filename\fR)
might work for you).)
.PP
.Vb 1
\&  $drw->save($filename, \e%options);
.Ve
.Sh "load"
.IX Subsection "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.
.PP
See each load<type> function for available options for that type.
.PP
In most cases \f(CW%options\fR may contain the selection methods available via
the \fICAD::Drawing::check_select()\fR function.
.PP
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.
.PP
.Vb 1
\&  $drw->load($filename, \e%options);
.Ve
.Sh "can_load"
.IX Subsection "can_load"
Returns true if the plugins think they can load this filename (no
test-loading is done, only verification of the type.)
.PP
.Vb 1
\&  $drw->can_load($filename);
.Ve
.SH "Plug-In Architecture"
.IX Header "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 \fIrequire()\fRd inside of an \fIeval()\fR block (see \s-1BEGIN\s0.)  Compile
failure in any one of these modules will be printed to \s-1STDERR\s0, but will
not halt the running program.
.PP
Each plug-in is responsible for declaring one or all of the following
variables:
.PP
.Vb 3
\&  our $can_save_type = "type";
\&  our $can_load_type = "type (or another type)";
\&  our $is_inherited = 1; # or 0 (or undef())
.Ve
.PP
If a package claims to be able to load or save a type, then it must
contain the functions \fIload()\fR or \fIsave()\fR (respectively.)  Package which
declare \f(CW$is_inherited\fR as a true value will become methods of the
CAD::Drawing class (though their \fIload()\fR and \fIsave()\fR functions will not
be visible due to their location in the inheritance tree.)
.Sh "\s-1BEGIN\s0"
.IX Subsection "BEGIN"
The \s-1BEGIN\s0 block implements the module path searching (looking only in
directories of \f(CW@INC\fR which contain a \*(L"CAD/Drawing/IO/\*(R" directory.)
.PP
For each plug-in which is found, code references are saved for later
use by the \fIdiskaction()\fR function.
.Sh "diskaction"
.IX Subsection "diskaction"
This function is for internal use, intended to consolidate the type
selection and calling of load/save methods.
.PP
.Vb 1
\&  $drw->diskaction("load|save", $filename, $type, \e%options);
.Ve
.PP
For each plug-in package which was located in the \s-1BEGIN\s0 block, the
function <Package>::\fIcheck_type()\fR will be called, and must return a true
value for the package to be used for \f(CW$action\fR.
.SH "Utility Functions"
.IX Header "Utility Functions"
These are simply inherited by the CAD::Drawing module for your direct
usage.
.Sh "outloop"
.IX Subsection "outloop"
Crazy new experimental output method.  Each entity supported by the
format should have a key to a function in \f(CW%functions\fR, which is expected
to accept the following input data:
.PP
.Vb 1
\&  $functions{$ent_type}->($obj, \e%data);
.Ve
.PP
The \f(CW%data\fR hash is passed verbatim to each function.
.PP
.Vb 1
\&  $count = $drw->outloop(\e%functions, \e%data);
.Ve
.PP
In addition to each of the \f(CW$ent_type\fR 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 \f(CW$ent_type\fR functions.
.Sh "is_persistent"
.IX Subsection "is_persistent"
Returns 1 if \f(CW$filename\fR points to a persistent (directory / db) drawing.
.PP
.Vb 1
\&  $drw->is_persistent($filename);
.Ve