.\" 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::Template 3" .TH CAD::Drawing::Template 3 "2008-01-04" "perl v5.8.8" "User Contributed Perl Documentation" .SH "NAME" CAD::Drawing::Template \- Replace tags with text and geometry. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 9 \& my $bp = CAD::Drawing::Template->new(); \& $bp->load('my_template.dxf'); \& # set some values for the boiler-plate: \& $bp->set_data(foo => 'value for foo'); \& my @parts = qw(E8955 Q4200); \& $bp->set_vtable(parts => \e@parts); \& $bp->set_geom(birdseye => 'birdseye.dwg'); \& my $drw = $bp->done(pass => qr/^shipping/, die => 0); \& $drw->save('output.dxf'); .Ve .SH "Input Templates" .IX Header "Input Templates" Input templates must be CAD::Drawing compatible files or objects. These are brought into the CAD::Drawing::Template object via \fIload()\fR or \&\fIimport()\fR and searched for 'texts' items which match the formats listed below. .PP The tags may be on any layer in the drawing except 'comments' and 'fit' which are reserved names. The 'comments' layer is completely discarded, and the 'fit' layer must only contain rectangles (which are necessary for scaling calculations, but are also discarded.) .SH "Tag Formats" .IX Header "Tag Formats" The 'tags' are 'texts' entities (single\-line text in dwg/dxf formats) which must begin and end with matching angle-brackets ('<' and '>'.) These text entities are sourced for their insertion point, text height, and name. Future versions of this module will support orientations, fonts, and options within the tag text itself. .PP In general, tags are formatted as <$type:$name>. Where \f(CW$type\fR is one of the types defined below and \f(CW$name\fR is the name of the tag (to be used in addressing it via the set_*() functions. .PP Tag names should adhere to the same rules as perl variable names: .PP .Vb 3 \& 1. Alphanumeric characters (and underscores) only (a-z, A-Z, 0-9, _) \& 2. Must start with a letter ("a2", not "2a", and not "_2") \& 3. Case senSitive .Ve .PP The following tag types are supported. Examples show the text string that would be in the template. .IP "data" 4 .IX Item "data" A 'data' tag is replaced with a single scalar value. .Sp Examples: .Sp .Vb 3 \& \& \& .Ve .IP "vtable" 4 .IX Item "vtable" A 'vtable' tag is replaced with a list of values, each one some distance below the previous, with the top line's insertion point at the tag's insertion point. .Sp Examples: .Sp .Vb 2 \& \& .Ve .IP "geo" 4 .IX Item "geo" Loads a drawing and fits it into a rectangle. .Sp \&\s-1NOTE:\s0 The rectangle must be on a layer named 'fit' and contain the insertion point of the tag. Each tag must be within a rectangle on the 'fit' layer and each rectangle on the 'fit' layer must have exactly one tag inside of it. If this is not true, death ensues. These rectangles are removed from the drawing before output. .Sp While a rectangle may contain two 'geo' tags, each tag must be contained in one rectangle (the innermost containing rectangle wins.) .Sp Examples: .Sp .Vb 2 \& \& .Ve .IP "block" 4 .IX Item "block" Loads a drawing to the insertion point. .Sp Examples: .Sp .Vb 2 \& \& .Ve .IP "function" 4 .IX Item "function" A 'function' tag calls a perl function, and afterwards behaves like a data tag. There is no \fIset_function()\fR function, since this tag is supposed to be fully\-automatic. .Sp The function is assumed to be a member of a Perl module. If that module is not already loaded, it is \fIrequire()\fR'd within an \fIeval()\fR statement before the function is called. There is no provision for passing values to these functions. The function is called in a list context, and the results joined by spaces. Any errors encountered in calling the function will be \fIcroak()\fR'd along with the function name. .Sp If the module is contained under a non-standard path (one which is not included in \f(CW@INC\fR), it should be preceded by a directory path. This directory is then brought into \f(CW@INC\fR via the 'use lib' pragma. .Sp Examples: .Sp .Vb 4 \& # uses main::date() \& \& \& .Ve .SH "AUTHOR" .IX Header "AUTHOR" Eric L. Wilhelm .PP http://scratchcomputing.com .SH "COPYRIGHT" .IX Header "COPYRIGHT" This module is copyright (C) 2004\-2006 by Eric L. Wilhelm. .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 "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" .Vb 1 \& CAD::Drawing .Ve .SH "Constructors" .IX Header "Constructors" .Sh "new" .IX Subsection "new" .Vb 1 \& my $bp = CAD::Drawing::Template->new(%options); .Ve .IP "Valid options" 4 .IX Item "Valid options" .Vb 1 \& pass => [@list], # type:name strings only .Ve .Sh "clone" .IX Subsection "clone" Duplicates the boiler-plate as a snapshot in time (useful to save effort in loops.) .PP .Vb 1 \& my $bp2 = $bp->clone(); .Ve .SH "Template Handling" .IX Header "Template Handling" Getting template data in and finished data out. .Sh "load" .IX Subsection "load" .Vb 3 \& $bp->load($filename); \& # or: \& $bp->load($drawing_object); .Ve .Sh "done" .IX Subsection "done" .Vb 1 \& $drw = $bp->done(%options); .Ve .PP Options: .PP .Vb 4 \& pass - array ref of pass-able tags ("type:name" strings) \& strict - croak on tags not listed in pass \& warnings - carp warnings \& default - "drop" or "pass" (default) action for un-passed tags .Ve .Sh "tag_list" .IX Subsection "tag_list" .Vb 1 \& $bp->tag_list(); .Ve .SH "Methods" .IX Header "Methods" These methods allow you to manipulate the template. .Sh "set_data" .IX Subsection "set_data" Replace the tag's text with a string. .PP .Vb 1 \& $bp->set_data($name => $value); .Ve .PP .Vb 3 \& # replace the tag with the department's name: \& $dep = 'Department of Redundancy Department'; \& $bp->set_data(department => $dep); .Ve .Sh "set_vtable" .IX Subsection "set_vtable" Remove the tag entity, and create a series of texts, each spaced slightly below the previous. .PP .Vb 1 \& $bp->set_vtable($name => \e@list); .Ve .PP .Vb 8 \& # uses the tag: \& # create a table of revision notes: \& my @rev = ( \& ' 1 Changed fonts for PHB', \& ' 2 Changed fonts back (for same)', \& ' 3 Removed all text', \& ); \& $bp->set_vtable(revision => \e@rev); .Ve .Sh "set_geo" .IX Subsection "set_geo" Load a drawing into the template, scaling it to fit within an enclosing rectangle. .PP .Vb 3 \& $bp->set_geo($name => $filename); \& # or: \& $bp->set_geo($name => $drawing_object); .Ve .Sh "set_block" .IX Subsection "set_block" Identical to set_geo, except no scaling is performed. .PP .Vb 3 \& $bp->set_block($name => $filename); \& # or: \& $bp->set_block($name => $drawing_object); .Ve .SH "Guts" .IX Header "Guts" These methods are used internally. .Sh "find_tags" .IX Subsection "find_tags" Grabs the addresses of all tags which match the regex m/^<.*>$/. Any which were are in the array @{$self\->{pass}} are left untouched. .PP After finding all of the tags, execute any tags which were found. .PP .Vb 1 \& $bp->find_tags(); .Ve .Sh "geo_match" .IX Subsection "geo_match" Performs the rectangle-tag matching. Must be able to reduce each geo tag to an innermost enclosing rectangle or dies with much whining. .PP .Vb 1 \& $bp->geo_match(); .Ve .Sh "run_function" .IX Subsection "run_function" Runs the function \f(CW$name\fR (in a list context) and places it's results (joined with spaces) into the string at \f(CW$addr\fR. .PP .Vb 1 \& $bp->run_function($name, $addr); .Ve .Sh "load_drawing" .IX Subsection "load_drawing" Loads a drawing from a filename or CAD::Drawing object and returns a CAD::Drawing object. .PP .Vb 3 \& $drw = $bp->load_drawing($name => $filename); \& # or: \& $drw = $bp->load_drawing($name => $drawing_object); .Ve .SH "Functions" .IX Header "Functions" Not object\-oriented, and likely not exported. .Sh "parse_tag" .IX Subsection "parse_tag" Break a tag into type, name, and options. When (and if) options are supported within the tags, they will be handled here. .PP .Vb 1 \& ($type, $name, $options) = parse_tag($tag); .Ve