PerlPoint-Package
view release on metacpan or search on metacpan
lib/PerlPoint/Generator.pm view on Meta::CPAN
{
# we got a relative path, absolutify it and use the result
my ($base, $path, $type)=fileparse($me->{options}{imagedir});
$me->{options}{imageref}=join('/', abs_path($path), basename($me->{options}{imagedir}));
}
}
}
# make image target directory, if necessary
if (exists $me->{options}{imagedir} and not -d $me->{options}{imagedir})
{
warn "[Info] Making image directory $me->{options}{imagedir}.\n" unless exists $me->{options}{noinfo};
mkpath($me->{options}{imagedir});
}
# bootstrap the template engine, if necessary (check options etc.)
# - the template engine might rely on our configuration, so this is done in the finish
# of this method
$me->{template}->bootstrap() if exists $me->{template};
}
}
# inits with parser - this is just a dummy to be overwritten by child classes
sub initParser
{
# get and check parameters
(my __PACKAGE__ $me)=@_;
confess "[BUG] Missing object parameter.\n" unless $me;
confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
}
# inits with backend
sub initBackend
{
# get and check parameters
(my __PACKAGE__ $me)=@_;
confess "[BUG] Missing object parameter.\n" unless $me;
confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
# bind the backend to the stream (to enable access to its data *before* backend invokation,
# which might be used in inherited methods)
$me->{backend}->bind($me->{build}{streamData});
}
# provide option declarations
sub declareOptions
{
# get and check parameters
(my __PACKAGE__ $me)=@_;
confess "[BUG] Missing object parameter.\n" unless $me;
confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
# declare options
(
# added options
[
"acceptedFormat=s@", # more accepted formats (embedded or included);
"activeContents", # evaluation of active contents;
"cache", # control the cache;
"cacheCleanup", # cache cleanup;
"dstreaming|docstreaming=s", # document stream handling (allow "docstreaming" for backwards compatibility);
"help", # online help, usage;
"imagedir|image_dir=s", # target image directory (allow "image_dir" for backwards compatibility with pp2html);
"imageref|image_ref=s", # target image directory reference (allow "image_ref" for backwards compatibility with pp2html);
"includelib=s@", # library pathes;
"nocopyright", # suppress copyright message;
"noinfo", # suppress runtime informations;
"nowarn", # suppress runtime warnings;
"prefix|slide_prefix=s", # target file prefix (slide_prefix for pp2html backwards compatibility);
"quiet", # suppress all runtime messages except of error ones;
"reloadStream", # reload stream from -streamBuffer file;
"safeOpcode=s@", # permitted opcodes in active contents;
"set=s@", # user settings;
"skipcomments", # do not convert PerlPoint comments;
"skipstream=s@", # skip certain document streams;
"mainstream=s", # choose an alternative name for the "main" stream;
"streamBuffer=s", # a file to store the stream;
"suffix|slide_suffix=s", # target file suffix (slide_suffix for pp2html backwards compatibility);
"tagset=s@", # add a tag set to the scripts own tag declarations;
"targetdir|slide_dir=s", # target file prefix (slide_dir for pp2html backwards compatibility);
"templatesAccept=s@", # targets accepted by the templates used;
"templatetype=s", # template engine type;
"trace:i", # activate trace messages;
"version", # display version informations and exit;
# document data ("doc...")
"docdescription|description=s", # presentation description (allow "description" for backwards compatibility);
"doctitle|title=s", # presentation title (allow "title" for backwards compatibility);
"docsubtitle=s", # presentation subtitle;
"docauthor=s", # presentation author;
"docdate=s", # presentation date explicitly configured;
],
# deactivated options - non at this highest level
[],
);
}
# do not overwrite this - it is intended for internal use
sub readOptions
{
# get and check parameters
((my __PACKAGE__ $me), my ($declared, $deactivated))=@_;
confess "[BUG] Missing object parameter.\n" unless $me;
confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
confess "[BUG] Missing declared options parameter.\n" unless $declared;
confess "[BUG] Declared options parameter is no array reference.\n" unless ref($declared) eq 'ARRAY';
confess "[BUG] Missing deactivated options parameter.\n" unless $deactivated;
confess "[BUG] Deactivated options parameter is no array reference.\n" unless ref($deactivated) eq 'ARRAY';
# update the stored values
@{$me->{optionlist}[0]}{@$declared}=();
@{$me->{optionlist}[1]}{@$deactivated}=();
# if what we declare now was deactivated before, the list of deactivations
# need to be updated
/(\w+)[=:]?/, delete $me->{optionlist}[1]{$_} for @$declared;
}
# provide source filter declarations
sub sourceFilters
lib/PerlPoint/Generator.pm view on Meta::CPAN
((my __PACKAGE__ $me), my @options)=@_;
confess "[BUG] Missing object parameter.\n" unless $me;
confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
confess "[BUG] Missing option list parameter.\n" unless @options;
# resolve option files
argvFile(default=>1, home=>1);
# get options
GetOptions($me->{options}, @options);
# propagate options as necessary
@{$me->{options}}{qw(nocopyright noinfo nowarn)}=(1) x 3 if exists $me->{options}{quiet};
$me->{options}{trace}=$ENV{SCRIPTDEBUG} if not exists $me->{options}{trace} and exists $ENV{SCRIPTDEBUG};
}
# provide help portions
sub help
{
# get and check parameters
(my __PACKAGE__ $me)=@_;
confess "[BUG] Missing object parameter.\n" unless $me;
confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
# to get a flexible tool, help texts are supplied in portions
{
# supply the options part
OPTIONS => {
acceptedFormat => <<EOO,
Configures the converter to accept the specified format for embedded or included files.
This option can be specified multiply.
EOO
activeContents => <<EOO,
For reasons of security, Active Contents (conditions, embedded Perl, paragraph filters,
import filters etc.) is disabled by default. Use this option to activate it.
Note: you need to specify valid opcodes by C<-safeOpcode> if C<activeContents> is used.
EOO
cache => <<EOO,
Activates the cache, see docs for details. By default, the cache is deactivated.
Note: in most cases you can skip this option.
EOO
cacheCleanup => <<EOO,
Cleans up the cache. Mostly invoked automatically. See docs for details.
EOO
dstreaming => <<EOO,
Document stream handling (for backwards compatibility, C<-docstreaming> can still be used).
Takes a numerical flag value as argument.
Example: -dstreaming 2
By default (or when 0 is passed as value), document streams are evaluated as streams. A value
of 1 ignores all docstreams, while a value of 2 treats docstream entry points as headlines.
For details about document streams please see the parser documentation and the tutorial.
Docstreams are "inlined documents" embedded into the main document and can be used in
various ways. We recommend to try them out!
EOO
formatter => <<EOO,
The formatter determines I<how> the target format (chosen by C<-target>) will be produced.
There can be many formatters available for a certain target, see section I<"Intro"> above
for details.
So, once you have set up your target, you can configure which of the related formatters
should be used.
By convention there is always a formatter "Default" for every target. If the option is
omitted, the converter will use that default one.
EOO
help => <<EOO,
provides this online help. The help is composed dynamically, depending on the chosen target,
formatter and template engine. So for a complete help, try to set all of the following as
in a "real" call: C<-target>, C<-formatter>, C<-styledir>, C<-style>.
EOO
imagedir => <<EOO,
Images need special handling: they are not transformed but should be made part of generated
documents. Because results are usually generated at another place than sources (and images)
are stored, a converter needs to copy images from their source path to their target directory.
By default, this is the directory of the target files.
To allow flexible usage, it is possible to specify a I<special> target directory for images
with this option, e.g. to collect all image files at a central place on a server.
Please pass the name of the directory images should be copied into as argument.
Example: The source is ppsrc/doc.pp, files
are generated into results/doc, and
images shall be stored in results/img.
Use these options to achieve this:
-targetdir results/doc
-imagedir results.img
ppsrc/doc.pp
EOO
imageref => <<EOO,
As described for option C<-imagedir>, images need special handling. This is true for code
generation as well: target code should use an image path relative to itself, not to the
lib/PerlPoint/Generator.pm view on Meta::CPAN
nocopyright => qq(Suppress copyright message.),
noinfo => qq(Suppress runtime informations.),
nowarn => qq(Suppress runtime warnings.),
quiet => qq(Suppress all runtime messages except of error hints.),
safeOpcode => <<EOO,
This option is a supplement to C<-activeContents>. If Active Contents is activated, you need
to declare which opcodes you trust. This is done for reasons of security, in case the processed
PerlPoint sources were written by someone else. Remember, Active Contents is full featured Perl,
unless restricted by this option.
Restrictions are implemented by running Active Contents in a C<Safe> module compartment. C<Safe>
requires to activate trusted opcodes. See the C<Safe> and C<Opcode> modules for a list of valid
opcode specifications.
Please note that C<Safe> cannot run all code, there are things that cannot be done in a
compartment, but try for yourself.
If all this sounds complicated, or if you are sure you can trust all Active Contents entirely,
or if you are using a safe sandbox, consider using the "ALL" argument. As the name intends,
"ALL" in fact enables I<all> opcodes in general. This is done by running Active Contents via
C<eval()>.
EOO
set => <<EOO,
This option allows you to pass in user defined options. Those options have no direct impact
to the way C<perlpoint> does its job, instead it allows you to control source processing by making
or omitting settings queried in Active Contents, namely conditions.
Example: The following condition checks if
one of the options "a", "b" or "all"
was set (via -set a, -set b or -set all):
? flagSet(qw(a b all))
Note: currently, it is not possible to pass values to such settings. This might be added in
future versions.
EOO
skipcomments => <<EOO,
PerlPoint comments are usually transformed into comments of the target language. With
this option, they will be ignored. (Comments might be intended for the author, but make
no sense in generated objects, or skipping them could help to compact the results.)
EOO
skipstream => <<EOO,
Implements a document stream filter. The stream specified by the option argument will be
ignored. The option can be used multiply.
Example: -skipstream details
Note: you cannot skip the "main" stream.
Note: to skip document streams I<in general>, use C<-dstreaming 1>.
EOO
streamBuffer => <<EOO,
With this option, the stream produced by the parser will be stored in the specified file.
This is useful to bypass parsing later on with option C<-reloadStream>.
Please note that stream buffering is an "all or nothing" operation. While you can contineously
buffer streams, only the I<complete> last buffered stream can be reloaded. On the other hand,
a complete stream allows complete parser bypassing, which can save you a lot of time.
See the C<-cache> options for a finer grained and controled caching.
EOO
reloadStream => <<EOO,
Reloads a stream previously saved via C<-streamBuffer>. C<-streamBuffer> needs to be declared
as well, to get the name of the stream to reload.
Stream reload is a fast alternative to reparsing the sources, which can take a long time.
Please note that stream buffering is an "all or nothing" operation. While you can contineously
buffer streams, only the I<complete> last buffered stream can be reloaded. On the other hand,
a complete stream allows complete parser bypassing, which can save you a lot of time.
No further check is performed to see if the stream is up to date related to the sources, or if
it matches the specified sources at all.
See the C<-cache> options for a finer grained and controled caching.
EOO
tagset => <<EOO,
Adds a tag set to the scripts own tag declarations.
Usually, C<perlpoint> only acepts tags declared by the processor to your chosen target format.
This means that an HTML target processor can allow other targets than an SDF target processor.
This makes things very flexible, but can result in nonportable sources. Sources using HTML
only tags might not be processed when translating into SDF, for example.
By adding tagsets of another target processor, the "foreign" tags get be accepted (in fact,
they are recognized as tags but ignored). Read the docs of C<PerlPoint::Tags::...> modules
to find out which tagsets are available.
Note: in most cases, there is no need to deal with tagsets.
EOO
target => <<EOO,
Specifies the target format. This is a mandatory setting - in fact, it is I<the> base setting
to be made. Once you have chosen a target, you can decide which formatter should be used to
produce it. See the I<"Intro"> section above for more details about the target choice.
Examples: -target XML
lib/PerlPoint/Generator.pm view on Meta::CPAN
# init parser
$me->initParser;
# run the parser
$me->runParser;
}
# build a backend
$me->buildBackend;
# init backend
$me->initBackend;
# store chapter data
$me->storeChapterData;
# run the backend
$me->runBackend;
# finish
warn "[Info] Finish started ...\n" unless exists $me->{options}{noinfo};
$me->finish;
warn "[Info] Finish completed.\n" unless exists $me->{options}{noinfo};
}
# run the parser
sub runParser
{
# get and check parameters
(my __PACKAGE__ $me)=@_;
confess "[BUG] Missing object parameter.\n" unless $me;
confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
# and call it
$me->{build}{parser}->run(
stream => $me->{build}{streamData},
files => \@ARGV,
filter => join('|', @{$me->{build}{sourceFilters}}),
safe => exists $me->{options}{activeContents} ? $me->{safe} : undef,
activeBaseData => {
targetLanguage => $me->{options}{target},
userSettings => {map {$_=>1} exists $me->{options}{set} ? @{$me->{options}{set}} : ()},
},
predeclaredVars => {
CONVERTER_NAME => basename($0),
CONVERTER_VERSION => $main::VERSION,
},
libpath => exists $me->{options}{includelib} ? $me->{options}{includelib} : [],
skipcomments => exists $me->{options}{skipcomments},
docstreams2skip => exists $me->{options}{skipstream} ? $me->{options}{skipstream} : [],
docstreaming => (exists $me->{options}{dstreaming} and ($me->{options}{dstreaming}==DSTREAM_HEADLINES or $me->{options}{dstreaming}==DSTREAM_IGNORE)) ? $me->{options}{dstreaming} : DSTREAM_DEFAULT,
nestedTables => $me->{build}{nestedTables},
vispro => 1,
headlineLinks => 1,
cache => (exists $me->{options}{cache} ? CACHE_ON : CACHE_OFF)
+ (exists $me->{options}{cacheCleanup} ? CACHE_CLEANUP : 0),
display => DISPLAY_ALL
+ (exists $me->{options}{noinfo} ? DISPLAY_NOINFO : 0)
+ (exists $me->{options}{nowarn} ? DISPLAY_NOWARN : 0),
trace => TRACE_NOTHING
+ ((exists $me->{options}{trace} and $me->{options}{trace} & TRACE_PARAGRAPHS) ? TRACE_PARAGRAPHS : 0)
+ ((exists $me->{options}{trace} and $me->{options}{trace} & TRACE_LEXER) ? TRACE_LEXER : 0)
+ ((exists $me->{options}{trace} and $me->{options}{trace} & TRACE_PARSER) ? TRACE_PARSER : 0)
+ ((exists $me->{options}{trace} and $me->{options}{trace} & TRACE_SEMANTIC) ? TRACE_SEMANTIC : 0)
+ ((exists $me->{options}{trace} and $me->{options}{trace} & TRACE_ACTIVE) ? TRACE_ACTIVE : 0)
+ ((exists $me->{options}{trace} and $me->{options}{trace} & TRACE_TMPFILES) ? TRACE_TMPFILES : 0),
) or exit(1);
# store new stream data and parser anchors, if required
nstore([$me->{build}{streamData}, PerlPoint::Parser::anchors], $me->{options}{streamBuffer}) if exists $me->{options}{streamBuffer};
}
# run the backend
sub runBackend
{
# get and check parameters
(my __PACKAGE__ $me)=@_;
confess "[BUG] Missing object parameter.\n" unless $me;
confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
# run the backend
$me->{backend}->run($me->{build}{streamData});
# if there's a final pending page, produce it
# (don't forget there might be an open docstream frame)
$me->handleDocstreamEntry(DIRECTIVE_DSTREAM_ENTRYPOINT, DIRECTIVE_START, ''),
$me->format(item => $me->stackCollect())
if @{$me->{build}{stack}};
# rebind backend to the stream, to make its methods available for later access
$me->{backend}->bind($me->{build}{streamData});
}
# store chapter data as provided by the backend
# (run this while the backend is bound to a stream)
sub storeChapterData
{
# get and check parameters
(my __PACKAGE__ $me)=@_;
confess "[BUG] Missing object parameter.\n" unless $me;
confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
# get raw data of all headlines
my $nr=0;
foreach my $chapter (@{$me->{backend}->headlineIds2Data([1 .. $me->{backend}->headlineNr])})
( run in 2.387 seconds using v1.01-cache-2.11-cpan-140bd7fdf52 )