internal package Foswiki::Plugins::BookmakerPlugin::Book

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

Child packagesChild packages

internal package Foswiki::Plugins::BookmakerPlugin::Book

An object that represents a loaded book topic. A book is simply a list of topics, with some simple rules regarding its composition:

1. It is ordered
2. It stores full web.topic names
3. Entries are unique (can occur only once)
4. Indentation is used to indicate the topic "level"

ClassMethod new($topic)

Construct a new Book object by loading the topic specified by $topic. If $topic does not specify a web, then the preference BOOKMAKER_BOOKWEB will be used or, if that is not set, Sandbox.

If the topic already exists, access controls will be checked for read access. If this is denied, a Foswiki::AccessControlException will be thrown.

It is not an error to open a non-existent book topic (it will be created on the first save).

Note that Foswiki macros in the book topic are expanded when it is loaded, thus allowing use of %INCLUDE etc. However these macros will be lost when the book is saved.

The book parser accepts topics in a variety of formats, as described in BookmakerPlugin

ObjectMethod find($topic) → $index

Given the name of a topic return the index of that topic in the book. If $topic does not have a web specification, it will be assumed to be in the same web as the book topic.

Returns -1 if the topic is not found in the book.

Note that a topic can only occur once in a book.

ObjectMethod at($index) → $entry

Get the entry at a given $index, or undef if it is out of range.

The entry is a hash containing { web, topic, level }

ObjectMethod remove($i) → $entry

Remove the topic at the given index from the book. If $i < 0, will shift the first entry. If $i > length=, will pop the last. Otherwise will splice.

Returns the removed entry.

ObjectMethod add($entry) → $entry

Add an existing entry to the end of the book.

ObjectMethod add($topic [, $level]) → $entry

Create a new entry at the end of the book.

If $topic does not have a web specification, it will be placed in the same web as the book topic.

The topic will be added at level 0 if $level is not given.

Returns the new entry.

ObjectMethod insert($i, $topic [, $level]) → $entry

Create a new entry at the given index. If $i < 0, will add at the start, if $i > length at the end,

If $topic does not have a web specification, it will be placed in the same web as the book topic.

The topic will be added at level 0 if $level is not given.

Returns the new entry.

ObjectMethod insert($i, $entry) → $entry

Insert an existing entry at the given index. If $i < 0, will add at the start, if $i > length at the end,

ObjectMethod each() → $iterator

Return an iterator over the topics in the book. Iterators are used as follows:

my $i = $book->each();
while ($i->hasNext()) {
    my $entry = $i->next();
    # $entry is a hash with {web, topic, level}
}

Modifying the list during iteration is not supported.

ObjectMethod save()

Save the current book to the book topic. The caller must have CHANGE access, or an Foswiki::AccessControlException will be thrown. Existing meta-data is kept, as are header and footer sections.

ObjectMethod stringify() → $string

Generate a string representation of the book, suitable for debugging.