NAME

DocSet::NavigateCache - Navigate the DocSet's caches in a readonly mode

SYNOPSIS

  my $nav = DocSet::NavigateCache->new($cache_path, $id, $rel_path);

  # go through all nodes from left to right, and remember the sequence
  # number of the $nav node (from which we have started)
  my $iterator = $nav->first;
  my $seq = 0;
  my $counter = 0;
  my @meta = ();
  while ($iterator) {
     $seq = $counter if $iterator->id eq $nav->id;
     push @meta, $iterator->meta;
     $iterator = $iterator->next;
     $counter++;
  }
  # add index node's meta data
  push @meta, $nav->index_node;

  # prev object
  $prev  = $nav->prev;

  # get all the ancestry
  my @parents = ();
  $p = $nav->up;
  while ($p) {
      push @parents, $p;
      $p = $p->up;
  }

  # access the docsets of the child nodes
  $child_docset = $nav->down()

DESCRIPTION

DocSet::NavigateCache navigates the cache created by docset objects during their scan stage. Once the navigator handle is obtained, it's possible to move between the nodes of the same level, using the next() and prev() methods or going up one level using the up() method. the first() method returns the object of the first node on the same level. Each of these methods returns a new DocSet::NavigateCache object or undef if the object cannot be created.

This object can be used to retrieve node's meta data, its id and its index node's meta data.

Currently it is used in the templates for the internal navigation widgets creation. That's where you will find the examples of its use (e.g. tmpl/custom/html/menu_top_level and tmpl/custom/html/navbar_global).

As DocSet::NavigateCache reads cache files in, it caches them, since usually the same file is required many times in a few subsequent calls.

Note that DocSet::NavigateCache doesn't see any hidden objects stored in the cache.

METHODS

META: to be completed (see SYNOPSIS meanwhile)

• new

    DocSet::NavigateCache->new($cache_path, $id, $rel_path);

  $cache_path is the path of the cache file to read.

  $id is the id of the current node. if not specified the id for the first item (0) is retrieved.

  If the docset is empty (no items) new returns undef.

  $rel_path is optional and passed if an object has a parent node. It contains a relative path from the current node to its parent.

• parent_rel_path

• next

• prev

• first

• up

• down

• index_node

• meta

• id

AUTHORS

Stas Bekman <stas (at) stason.org>