GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
DocSet::RunTime(3) User Contributed Perl Documentation DocSet::RunTime(3)

"DocSet::RunTime" - RunTime Configuration

  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();

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

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()

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

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.

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.

Stas Bekman <stas (at) stason.org>

Hey! The above document had some coding errors, which are explained below:
Around line 303:
An empty L<>
Around line 330:
An empty L<>
2005-09-02 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.