view release on metacpan or  search on metacpan

Universal.pm  view on Meta::CPAN

region. For the region mentioned above the parent will be a region with
the name E<quot>def:StringContentE<quot>.

=item $region->id

Returns a unique numerical id for the region.

=back

=head2 Schemes

Schemes in Colorer describe general context changes. For example, the scheme
will change when parsing an interpolated string constant. The current
scheme defines the regions that can be found, e.g. you can't have function
calls inside a string scheme. Schemes unlike regions can stretch over multiple
lines. The current Colorer version defines only one method for the scheme
object:

=over 4

=item $scheme->name

Returns the name of the scheme, e.g. E<quot>perl:InterpolateStringE<quot>
for an interpolated string constant in Perl.

=back

=head1 PROBLEMS

=head2 HTML output is too verbose

The default output will use the name of a region and of all its parents as
the class name for a block of text. This allows adding styles only for
generally defined regions in most cases while still being able to take
language-specific features into account. However, this increases the amount
of text largely.

I<Solution 1>: Use server-side compression, e.g. mod_gzip. The size difference
in compressed output is negligible.

I<Solution 2>: You can replace the function used for creating class names to
include only one region name of the C<def:*> scheme.

  *Syntax::Highlight::Universal::_createClassName = sub {
    $region = shift;

    while (defined $region && $region->name !~ /^def:/)
    {
      $region = $region->parent;
    }
    my $class = defined $region ? $region->name : 'unknown';
    $class =~ s/\W/_/g;
    return $class;
  };

Note: this approach is not recommended and might stop working in future
versions of the module.

=head2 Text processing is very slow

Colorer was originally meant for desktop applications where one second to
load the configuration files doesn't matter. Unfortunately it matters a lot
for web applications. Furthermore, the parsing of text itself also needs
some time though much less than processing HRC configuration.

I<Solution 1>: If you often have to highlight the same texts, you
can use caching. L<Set up caching directory|/Setting a cache directory> where
the module can store processed text. Next time the same text needs to be
highlighted the result will be taken from the cache instead of parsing the
text all over again (and loading the necessary configuration files in the
process).

I<Solution 2>: This module implements a mechanism to store an already parsed
Colorer configuration on disk and load it into memory again. The time
requirement is 5-10 times less than for loading HRC configurations. See
description of methods L<precompile|/Precompiling configuration files> and
L<setPrecompiledConfig|/Loading a precompiled configuration> for more
information on this feature. When installing the module C<make test> will
automatically create a precompiled configuration file C<precompiled.hrcc>
(about 2 MB) that can be copied into the module's library directory (that's
where the C<hrc> directory is put when installing the module).

=head1 INCLUDED COLORER FILES

The source files belonging to the Colorer library are in the C<colorer>
directory of the distribution. It is a subset of files from Colorer-take5
Library beta3. All files are unchanged with the following exceptions:

=over 4

=item common/Features.h

The constants C<USE_CHUNK_ALLOC>, C<USE_DL_MALLOC>, C<JAR_INPUT_SOURCE>,
C<HTTP_INPUT_SOURCE> have been removed (the corresponding files haven't
been included). Instead, a constant C<ALLOW_SERIALIZATION> is defined.

=item common/Common.h

This file doesn't include C<MemoryChunks.h> any more.

=item colorer/parsers/HRCParserImpl.cpp

Some blocks have been added that become active if C<ALLOW_SERIALIZATION>
is defined. They are used to store additional information in the objects
of class C<SchemeNode> so that they can be written to disk and restored
without being changed.

=item colorer/parsers/helpers/HRCParserHelper.(h|cpp)

If C<ALLOW_SERIALIZATION> is defined, some fields are added to the class
C<SchemeNode>.

=item colorer/parsers/HRCParserImpl.cpp

Method C<loadFileType()> has been made virtual to allow overloading.

=item xml/xmldom.h

Made the definition of constants in class C<Node> an C<enum> (MS Visual C++
6.0 has problems with the current definition).