libdocview C++ API References

docview.hpp is the C++ header of libdocview. It provides all functions, classes, enumerations required to interact with Docview. It mainly consists of two parts. One part is for applications like documentation viewer or browsers, IDEs for handling documentations. Another part is for extensions. The first part provides functions required to load and unload extensions, parse documents into document trees and access them. The second part is extension related. It defines the most important class for extensions, docview::extension, which is the base class for all extensions.

Note

This header is compatible only with C++17 and above. It recommended to switch to C++17 or above if using old standards, as those are old and C++17 many new features, required by this header. If you are unable to upgrade, please consider using the C header instead.

Include this file with:

#include <docview.hpp>

namespace docview

Namespace containing classes and function provided by libdocview.

Namespace docview contains all symbols (e.g. functions, classes, enumerations) exposed by libdocview. It includes symbols required by both applications and extensions.

Functions

void load_ext(std::filesystem::path path)

Loads an extension from given path.

This function loads an extension from given path. If extension is already loaded, there is no effects. If the provided path doesn’t exist or it’s target isn’t valid, an instance of std::runtime_error is thrown. If the path doesn’t point to a valid extension, an instance of std::invalid_argument is thrown.

Parameters

• path: path to extension

Exceptions

• std::runtime_error: if given path or it’s target is invalid

• std::invalid_argument: if the path doesn’t point to a valid extension

void unload_ext(std::filesystem::path path)

Unloads extension with given path.

This function unloads extension with given path. If extension at given path isn’t loaded, there are no effects. This function never throws exceptions unless an internal error occurred.

Parameters

• path: path to extension

bool is_loaded(std::filesystem::path path)

Checks whether extension at given path is loaded.

This function checks whether an extension at given path is located. This function never throws exceptions unless an internal error occurred.

Return

whether extension at given path is loaded

Parameters

• path: path to extension

const doc_tree_node *get_doc_tree(std::filesystem::path path)

Returns a pointer to document tree of a path, nullptr on failure.

This function returns a pointer to document tree of a path, nullptr on failure. The pointer returned should not be managed by the application.

Return

pointer to document tree

Parameters

• path: path to documents

std::pair<std::string, bool> get_doc(const doc_tree_node *node)

Returns the URI or HTML content of document.

This function will return a pair of a std::string and a bool. The value bool will true of the value of std::string is a URI, false if the value of std::string is HTML.

Return

URI or HTML content of document

Parameters

• node: pointer to a node in document tree

std::string brief(const doc_tree_node *node)

Returns the brief of from document.

This function will return the brief of the the document specified by parameter node. Return value should be in plain text without any markup (however it’s not impossible to contains markup or special characters). May return empty string.

Return

brief of from document

Parameters

• node: pointer to a node in document tree

std::string details(const doc_tree_node *node)

Returns the details of from document.

This will return the brief from the document specified by parameter node. Return value should be in plain text without any markup (however it’s not impossible to contains markup or special characters). May return empty string.

Return

details of from document

Parameters

• node: pointer to a node in document tree

std::string section(const doc_tree_node *node) noexcept

Returns a section from document.

This will return a section from the document specified by parameter node. Return value should be in plain text without any markup (however it’s not impossible to contains markup or special characters). May return empty string.

Return

details of from document

Parameters

• node: pointer to a node in document tree

std::vector<const doc_tree_node*> search(std::string query)

Searches through all loaded document trees.

This function searches through the title and synonyms of all nodes of all document trees (including root nodes). Matches occurs only when title or any of synonyms follows or matches exactly (e.g. abc matches with abc, abcabc, abcdef, but not with acb). Returned vector does not have any particular order.

Return

vector with nodes of matched document nodes

Parameters

• query: the search query

std::vector<const doc_tree_node*> search(std::string query, std::vector<std::pair<const docview::doc_tree_node*, std::filesystem::path>> document_roots)

Searches through given document trees.

This function searches through the title and synonyms of all nodes of given document trees (including root nodes). Matches occurs only when title or any of synonyms follows or matches exactly (e.g. abc matches with abc, abcabc, abcdef, but not with acb). Returned vector does not have any particular order.

Warning

This function is deprecated. This was added due to an issue during search. This function will be removed eventually.

Return

vector with nodes of matched document nodes

Parameters

• query: the search query

bool validate(const doc_tree_node *node)

Checks whether a document node is still valid.

This function checks whether a document node is still valid. A document may be invalidate because of unloading an extension. It is recommended to validate one node from every document node tree after unloading an extension.

Return

whether a document node is valid

Parameters

• node: the node to validate

struct doc_tree_node

#include <docview.hpp>

Structure for holding a document node.

This structure holds all information about a document node. For more, see “What is a document node?”.

Public Members

const doc_tree_node *parent = nullptr

Pointer to parent, nullptr if there is no parent.

std::string title

The title of document.

std::vector<std::string> synonyms

Synonyms of title, alternative search queries for finding this document.

std::vector<const doc_tree_node*> children

Vector of pointers to children, empty if there is no child.

class extension

#include <docview.hpp>

Base class for extension, which defines the structure of an extension object.

Public Types

enum applicability_level

Enum holding all possible values of applicability level.

For more, see “What is applicability level?”.

Values:

enumerator tiny

The extension applies to a tiny amount of documentations.

enumerator small

The extension applies to a small amount of documentations, but not as small as tiny.

enumerator medium

The extension applies to a bigger amount of documentations then small.

enumerator big

The extension applies to a reasonable amount of documentations.

enumerator huge

The extension applies to a huge amount of documentations.

Public Functions

extension()

Constructs a new extension object.

~extension() = 0

Destroys the extension object.

applicability_level get_applicability_level() noexcept = 0

Returns the applicability level of extension.

Extensions must implement this method. This is used determine the extension calling order. For more, see “What is applicability level?”.

Return

applicability level of extension

const doc_tree_node *get_doc_tree(std::filesystem::path path) noexcept = 0

Returns a pointer to document tree of a path, nullptr on failure.

Extensions must implement this method. Note that memory used by the tree isn’t managed by libdocview, it’s extension’s responsibility to do and not do that.

Return

pointer to document tree

Parameters

• path: path to documents

std::pair<std::string, bool> get_doc(const doc_tree_node *node) noexcept = 0

Returns the URI or HTML content of document.

Extensions must implement this method. This function will return a pair of a std::string and a bool. The value bool will be true if the value of std::string is a URI, false if the value of std::string is HTML.

Return

URI or HTML content of document pointed by node

Parameters

• node: pointer to a node in document tree

std::string brief(const doc_tree_node *node) noexcept

Returns the brief of from document.

Extensions should override this method. This will return the brief of the document specified by parameter node. Return value should be in plain text (although any type of text is allowed). The base class implemention returns an empty string.

Return

brief of from document

Parameters

• node: pointer to a node in document tree

std::string details(const doc_tree_node *node) noexcept

Returns the details of from document.

Extensions should override this method. This function will return the details from the document specified by parameter node. Return value should be in plain text (although any type of text is allowed). The base class implemention returns an empty string.

Return

details of from document

Parameters

• node: pointer to a node in document tree

std::string section(const doc_tree_node *node, std::string section) noexcept

Returns a section from document.

Extensions should override this method. This will return a section from the document specified by parameter node. Return value should be in plain text (although any type of text is allowed). The base class implemention returns an empty string.

Return

details of from document

Parameters

• node: pointer to a node in document tree

• section: the name of section

See also

• libdocview C API References

• Writing extensions