For Gauche 0.9.15Search (procedure/syntax/module):

Next: , Previous: , Up: Library modules - Utilities   [Contents][Index]

12.71 text.info - Accessing info document

Module: text.info

This module provides some basic functionalities to extract information from info files, a documentation format defined by texinfo system (https://www.gnu.org/software/texinfo/). It is used in REPL toplevel commands infoand doc (see Working in REPL). It focuses mainly to handle Gauche documents, so it may not handle all features used in texinfo.

Class: <info-document>

{text.info} An object for opened info file(s), returned by open-info-document. All slots are private.

Class: <info-node>

{text.info} An object for each info node. It keeps the node’s content, as well as links to neighboring nodes. Its instance should be considered immutable object.

A node can be obtained from an <info-document> object by info-get-node.

Instance Variable of <info-node>: name

A string name of the info node. Every info document has at least "Top" node.

Instance Variable of <info-node>: next

The string name of the next node. You can visit all nodes in the document following the next link. It may be #f if the node is the last one of the document.

Instance Variable of <info-node>: prev

The string name of the previous node. It’s a reverse link of the next node. The previous node of "Top" is "(dir)" by convention, which is a special node that lists all info documents installed on the system (it is not included in the info document itself.)

Instance Variable of <info-node>: up

If the node is a subnode, this contains the name of the upper node (a chapter name for sections, a section name for subsections, etc.) It is #f for "Top" node.

Instance Variable of <info-node>: file

An <info-document> object of the info document this node is contained.

Instance Variable of <info-node>: content

A string content of the node.

Function: open-info-document info-file-path

{text.info} Open the named info document and returns an <info-document> instance. The argument is a pathname to a master info file, usually with .info suffix. Depending on the installation, info files may be compressed with gzip or bzip2, having extensions .gz or .bz2 after .info; you don’t need to specify those extensions. The procedure searches possible compression options.

A large info document may be splitted into multiple info files, each with a suffix .info-1, .info-2 etc. Those are automatically read, so you only need to give the path to the master file.

If it can’t find the named document, or can’t recognize its format, an error is thrown.

Function: info-get-node info-doc node-name

{text.info} The info-doc argument is an <info-document> instance. Returns an <info-node> instance with the string name node-name, or #f if no node with the given name is found.

Function: info-index-add! info-doc index-node-name :optional key-modifier

{text.info} Read the node named index-node-name in the info document info-doc, and adds its menu entries into the index table.

It is particularly useful to give the index page of the info doc, so that you’ll be able to lookup particular term (e.g. function name) quickly. Typical info document has a node called Index. Large documents, such as programming language reference (Gauche Users’ Reference is one of them) may have multiple index pages for different categories. You can call this procedure multiple times to add more than one index pages.

The optional key-modifier argument is a procedure applied to the entry-name (string) to obtain a key (string) in the index table. Sometimes the index uses different entry name from the actual name; e.g. Gauche’s class index lists class names without surrounding < and >, since using the actual name makes all class names being listed below < subheading, which isn’t very useful. You can pass (^e #"<~|e|>") as key-modifier to recover the actual class name to be used as the key.

If there are more than one entries per key, both are saved in the index table. See info-index-ref below.

Function: info-index-ref info-doc key

{text.info} Lookup index with the given key. Returns a list of (node-name line-number).

You can use pass node-name to info-node-get to obtain the info node contaning the definition, then pass the node and line-number to info-extract-definition to obtain the definition as a text.

Function: info-index-keys info-doc

{text.info} Returns a list of keys (strings) in the index.

Function: info-index->alist info-doc

{text.info} Returns the content of the index as ((key (node line) ...) ...).

Function: info-parse-menu info-node

{text.info} This is used in info-index-add!, but it is generally useful to parse a menu in an info node. It searches the * Menu: line, then gathers menu entry names and associated node names. Some menus such as index page also lists line numbers for each entry.

Returns a list of menu entries. Each menu entry is the following form:

(<entry-name> <node-name> [<line-number>])
Function: info-extract-definition info-node start-line

{text.info} Extract one definition from the node’s content. Assumes the definition begins from the specified line; then we go forward to find the end of the definition. The end of definition is when we see the end of content, or we see a line begins with less than or equal to 3 whitespaces. (Except the ’defunx’-type multi entry).

Returns a string describing the definition. If no definition is found, an empty string is returned.

A typical idiom is to add index node using info-index-add!, and get the node name and line number of the definition of a specific item with info-index-ref, then then use this procedure to extract the definition.


Next: , Previous: , Up: Library modules - Utilities   [Contents][Index]


For Gauche 0.9.15Search (procedure/syntax/module):