View on
Stas Bekman > DocSet-0.19 > DocSet::RunTime



Annotate this POD

View/Report Bugs


DocSet::RunTime - RunTime Configuration


  use DocSet::RunTime;

  # run time options
  if (get_opts('verbose') {
      print "verbose mode";

  # hosting system capabilities testing

  # 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
  $obj = get_render_obj();


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.


META: To be completed, see SYNOPSIS

Run Time Options

Only get_opts() method is exported by default.

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.

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(
             # 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.

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.


Stas Bekman <stas (at)>

syntax highlighting: