Linux Certif

Toute la documentation sur la certification Linux LPI

Zim::Store.3pm

NAME

Zim::Store - Base class for page storage objects

DESCRIPTION

This is a base class for storage backends. It documents the interface expected to handle page objects. It provides a number of stub methods and some logic that is common to most stores.

When implementing a new store at least implement "get_page()", "resolve_name()" or "resolve_case()". When implementing a store that is writable "delete_page()" also needs to be there. You might want to implement a native "copy_page()" and "move_page()" also then. To make your pages show up in the side pane implement "list_pages()". All other methods are optional.

Note that when a page name is given it is always given fully-specified, so you need to take into account your own namespace prefix.

It is good practice to throw an exception when a method fails. This way the GUI knows that something went wrong and can alert the user.

METHODS

new(parent => PARENT, namespace => NAMESPACE, ...)

Simple object constructor. PARENT can be a parent repository object or undef. NAMESPACE is the prefix for all pages managed by this store.

"init()"

Stub init function, to be overloaded.

"list_pages(NAMESPACE)"

This method should return a list of pages in NAMESPACE. The list is used by the gui to produce a hierarchical index, it does not tell anything about the actual existence of the pages.

The default returns an empty list.

"get_page(NAME)"

This method is expected to return a page object for NAME. See Zim::Page for an example.

When a page does not exist an empty object should be returned that can be used to create this page by saving to it. The status of this object should be set to 'new'. When a page does not exists and can not be created undef should be returned.

The default does nothing.

"resolve_page(LINK, PAGE, NO_DEFAULT)"

Convenience function packing "resolve_name()" and "get_page()".

"resolve_name(NAME, REF, NO_DEFAULT)"

Resolves a page relative to a given path. Does an upward search through the path for relative links. This search is depth first (or actually ``surface first''), since checking the given path is cheaper than doing a in width search.

* make name case sensitive * match name against REF * check existence

for matching only use first element of NAME either anchored in path REF or an existing leaf of REF match case-insensitive.

when a match is found the remainig parts of NAME need to be resolved to put them in correct case

without REF, or when NAME starts with ':' we consider the absolute name a direct match and continue with resolving case

when no match is found a default is returned unless NO_DEFAULT is set this default is the REF minus the last part plus all parts of NAME in their original case

"resolve_case(\@NAME, \@REF)"

Private method called by "resolve_name()". To be overloaded by child classes.

NAME contains the parts of the pagename we are looking for. REF contains parts of the pagename we use as base for a relative lookup. Try to match the first part of NAME in the path defined by REF. If REF is undefined, just start from ``:''.

Should return a case sensitive page name.

"copy_page(SOURCE, TARGET)"

Copy contents of object SOURCE to object TARGET. Both page objects should belong to this store.

Make sure to update the page objects correctly. For example set status and update or flush the parse tree.

"move_page(SOURCE, TARGET)"

Move the content of object SOURCE to object TARGET. Both page objects should belong to this store.

Make sure to update the page objects correctly. For example set status and update or flush the parse tree.

The default just calls "copy_page()" and "delete_page()".

"delete_page(PAGE)"

Delete object PAGE and returns the page object. Be aware that although the content is deleted the PAGE object goes on living and should be updated accordingly. The status of the object should be set to 'deleted'.

The default method fails by exception.

"search()"

TODO

Document Interface

This interface is used to deal with external documents that belong to the notebook. Think of these documents as attachments.

The documents are stored as files in a directory that may or may not be the same as the directory where page contents are stored. The parent object has an attribute ``document_dir'' to specify the document root directory.

The ``document_root'' is an alternative directory. This is used as a top level directory to find _external_ documents (not considered attachments). This can for example be a parent directory of document_dir or some totally unrelated dir.

"document_dir(PAGE)"

Returns the document dir for PAGE. Returns the toplevel dir if PAGE is undefined.

"document_root()"

Returns the document root directory or undef.

"store_file(FILE, PAGE, NAME, MOVE)"

Stores a file in the document dir for PAGE, or in the toplevel dir if PAGE is not specified. Returns a path that can be used to link this file.

NAME is optional and gives the desired file name to store. If NAME is not provided the name of FILE is used.

If MOVE is true the original file is moved instead of copied.

If the name is identical to that of an existing file a number will appended before the file extension in order to make the name unique. If the name contains a sequence 'XX' (or longer) this sequence will be replaced with a number such that the part of the name up to and including the 'XX' is unique. (So file extension does not matter). This can be used to attach a group of files with the same basename while making sure that none of them conflicts with an existing file.

"resolve_file(PATH, PAGE)"

PAGE is an optional argument.

This method resolves links to files, the argument can be either a file:// url or a path starting with either './', '../', '~/' or '/'.

In case an url or a path starting with '~/' is used these are considered absolute paths.

In case the path starts with './', '../' the file is resolved relative to the document dir for PAGE. If PAGE is not given the top level document dir is used.

In case the path starts with '/' the document root is used. This can be the toplevel document dir but may also be some other dir. If no document root is set, the file system root is used.

"relative_path(PATH, PAGE)"

Returns a path relative to the document dir for page, the document root or the users home directory. Returns a complete path or file uri otherwise. This is used to turn paths that are inserted into links and keep them readable. PAGE is an optional argument.

Utility methods

These methods are commonly used methods in store objects. They do not need to be overloaded.

"clean_name(NAME, RELATIVE)"

Class function that returns a sanatized page name. Removes forbidden chars etc.

If RELATIVE is true the name is not made absolute.

"root()"

Returns the top parent repository object. This is used to get pages when we are not sure these pages belong to our store.

"check_dir()"

Checks for a ``dir'' attribute, else check if parent has a dir and derives from that. Dies on failure. Used when initializing store sub-classes that are dir based.

"check_file()"

Check if a ``file'' attribute is set and make sure ``dir'' is set based on that. Used when initializing store sub-classes that are file based.

"wipe_array(REF)"

Removes double items from the array refered to by ref.

BUGS

Please mail the author if you find any bugs.

AUTHOR

Jaap Karssenberg || Pardus [Larus] <pardus@cpan.org>

Copyright (c) 2006 Jaap G Karssenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Zim