Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DocSet::RunTime(3)    User Contributed Perl Documentation   DocSet::RunTime(3)

       "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.

       o   registers_reset()

	   This	function resets	various	run-time registers, used for

	   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.:

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

       o   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,
	       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.

       o   set_opt(\%args)

       o   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.

       o   has_storable_module

       o   can_create_ps

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

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

       o   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.

       o   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.

       o   unset_render_obj()

	   Unsets the currently	set rendering object.

       o   get_render_obj()

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

       Stas Bekman <stas (at)>

       Hey! The	above document had some	coding errors, which are explained

       Around line 303:
	   An empty L<>

       Around line 330:
	   An empty L<>

perl v5.32.0			  2005-09-02		    DocSet::RunTime(3)


Want to link to this manual page? Use this URL:

home | help