NAME

DocSet::RunTime - RunTime Configuration

SYNOPSIS

  use DocSet::RunTime;

  # run time options
  DocSet::RunTime::set_opt(\%args);
  if (get_opts('verbose') {
      print "verbose mode";
  }

  # hosting system capabilities testing
  DocSet::RunTime::has_storable_module();
  DocSet::RunTime::can_create_ps();
  DocSet::RunTime::can_create_pdf();

  # source documents lookup
  DocSet::RunTime::scan_src_docs($base_path, \@search_paths, \@search_exts);
  my $full_src_path = find_src_doc($resource_rel_path);

  # rendering object singleton
  set_render_obj($obj);
  unset_render_obj();
  $obj = get_render_obj();

DESCRIPTION

This module is a part of the docset application, and it stores the run time arguments, caches results of expensive calls and provide Singleton-like service to the whole system.

FUNCTIONS

META: To be completed, see SYNOPSIS

Run Time Options

Only get_opts() method is exported by default.

• registers_reset()

  This function resets various run-time registers, used for validations.

  If the runtime is run more than once remember to always run first this function and even better always run it before using the runtime. e.g.:

    DocSet::RunTime::registers_reset();
    my $docset = DocSet::DocSet::HTML->new($config_file);
    $docset->set_dir(abs_root => ".");
    $docset->scan;
    $docset->render;

• register

    my @entries = register($register_name, $key, $val);

  Push into the register for a given key the supplied value.

  Return an array of the given register's key.

  For example used to track duplicated docset ids with:

      my @entries = DocSet::RunTime::register('unique_docset_id', $id,
                                             $self->{config_file});
      die if @entries > 1;

  because if the register returns two value for the same key, someone has already registered that key before. The values in @entries include the config files in this example.

• set_opt(\%args)

• get_opts()

Hosting System Capabilities Testing

These methods test the capability of the system and are a part of the runtime system to perform the checking only once.

• has_storable_module

• can_create_ps

• can_create_pdf

Source Documents Lookup

A system for mapping L<> escapes to the located of the rendered files. This system scans once the @search_paths for files with @search_exts starting from $base_path using scan_src_docs(). The @search_paths and @search_exts are configured in the config.cfg file. For example:

    dir => {
             # search path for pods, etc. must put more specific paths first!
             search_paths => [qw(
                 foo/bar
                 foo
                 .
             )],
             # what extensions to search for
             search_exts => [qw(pod pm html)],
            },  

So for example if the base path is ~/myproject/src, the files with extensions .pod, .pm and .html will be searched in ~/myproject/src/foo/bar, ~/myproject/src/foo and ~/myproject/src.

Notice that you must specify more specific paths first, since for optimization the seen paths are skipped. Therefore in our example the more explicit path foo/bar was listed before the more general foo.

When the POD parser finds a L<> sequence it indentifies the resource part and passes it to the find_src_doc() which looks up for this file in the cache and returns its original (src) location, which can be then easily converted to the final location and optionally adjusting the extension, e.g. when the POD file is converted to HTML.

As a special extension this function automatically assumes that index.html will be generated in each directory containing items of an interest. Therefore in find_src_doc() it'll automatically find things like: the guide, even though there was no source index.pod or index.html in first place.

Only the find_src_doc() function is exported by default.

• scan_src_docs($base_path, \@search_paths, \@search_exts);

• find_src_doc($resource_rel_path);

  returns undef if nothing was found. See the description above.

Rendering Object Singleton

Since the rendering process may happen by a third party system, into which we provide hooks or overload some of its methods, it's quite possible that we won't be able to access the current document (or better rendering) object. One solution would be to have a global package variable, but that's very error-prone. Therefore the used solution is to provide a hook into a RunTime environment setting the current rendering object when the rendering of a single page starts via set_render_obj($obj) and unsetting it when it's finished via unset_render_obj(). Between these two moments the current rendering object can be retrieved with get_render_obj() method.

Notice that this is all possible in the program which is not threaded, or/and only one rendering process exists at any given time from its start to its end.

All three methods are exported by default.

• set_render_obj($obj)

  Sets the current rendering object.

  You cannot set a new rendering object before the previous one is unset. This is in order to make sure that one document won't use by mistake a rendering object of another document. So when the rendering is done remember to call the unset_render_obj() function.

• unset_render_obj()

  Unsets the currently set rendering object.

• get_render_obj()

  Retrieves the currently set rendering object or complains aloud if it cannot find one.

AUTHORS

Stas Bekman <stas (at) stason.org>

cpanm DocSet

perl -MCPAN -e shell
install DocSet