freeuhs

FreeUHS is a free/open-source hint viewer program for the UHS file format.
These programs are public domain.

IMPORTANT NOTE: This is not affiliated with or endorsed by Universal Hint
System; the designation "UHS" in this program is only used to identify the
file format (which I believe to be fair use).

The standard aliases are "freeuhs-" and the program name without the .js
extension. For example "view.js" has the standard alias "freeuhs-view".

Also note that this software is not designed for Windows, although if you
have a colour ANSI terminal emulator and can guarantee that files and
standard I/O use binary mode, then you may be able to run them on Windows
as well (but I have not tested this).

This is not an importable package, so require("freeuhs") will not work.


=== catalog ===

Access the UHS catalog. The first argument is the command to execute on
the catalog, and depending on the command may take further arguments.

Optionally, you can use an equal sign as the first argument, in which case
the second argument is the URL of the catalog, and then the command starts
with the third argument. The URI scheme may be "http", "https", "file", or
"gopher"; there is currently no support for FTP. If the scheme is omitted,
it is relative to the current directory.

If using HTTP or HTTPS, it also tries to cache the catalog if possible,
although the official UHS catalog does not currently support caching.

The commands can be:

- get - Takes one argument, being the filename. Downloads that UHS file
to stdout. Downloads are compressed; this program will automatically
uncompress the file when downloading it.

- json - Download the catalog to stdout but it is converted to JSON.

- list - Can optionally have arguments for filtering and sorting. The
output is a list of available files. The columns are: filename, title,
compressed size, uncompressed size, date. K = kilobytes, M = megabytes.

- raw - Download the catalog to stdout.

Filtering/sorting commands are listed below. Some of them take an argument
which is the next command-line argument after the filter/sort command.

- after <date> - Match only files from after the given date.

- before <date> - Match only files from before the given date.

- glob <pattern> - Match the filename, using ? and * wildcards. It is
case insensitive.

- limit <number> - Keep only that many records from the beginning of the
resulting list, like a LIMIT clause in SQL.

- max <size> - Set maximum uncompressed file size wanted. You can use K
and M suffixes.

- maxz <size> - Set maximum compressed file size wanted. You can use K
and M suffixes.

- nglob <pattern> - Match the filename, but only files that do not match
the pattern.

- offset <number> - Discard that many records from the beginning of the
resulting list, like a OFFSET clause in SQL.

- regexp <regexp> - Match the title using a case insensitive regexp.

- rev - Reverse the sort order (specify this after sorting).

- sdate - Sort by date.

- sfull - Sort by uncompressed size.

- shuffle - Sort in a random order.

- since <date> - Match only files on or after the given date.

- sname - Sort by filename. (This seems to be the default sort order for
the official UHS catalog, although unofficial catalogs may have different
default sort orders.)

- ssize - Sort by compressed size.

- stitle - Sort by title.

- title <text> - Match the text found in part of the title.

- until <date> - Match only files on or before the given date.


=== export ===

Convert a hint file read from stdin to another format and output it on
stdout. By copyright law it would be prohibited to distribute the
converted files if you do not have implicit or explicit permission to
do so.

The only command-line argument is the format, which is one of:

- json - Output the JSON data (the same internal format used by view.js).

- json_decoded - Output as JSON, but encrypted data is decoded.

- key - Output the contents of the decoding key for nested hints, as a
list of numbers with commas in between.

- sql - Output a list of SQL statements. It will add BEGIN and COMMIT
around it, and right after BEGIN will be the schema.

More formats might be added in future.


=== make ===

This program compiles a hint file from a source format into a UHS format.
The input is from stdin and output is to stdout; command-line arguments
are ignored.

It will write zero instead of the correct checksum. This is deliberate;
I think they don't want the official UHS software to be able to load
unofficial hint files, and hopefully entering the wrong checksum will
cause them to refuse to load it, while FreeUHS and OpenUHS will be able
to load these unofficial hint files. (I also don't know how this checksum
is supposed to be calculated anyways.)

The source format consists of lines, where the first character of the
line indicates the type of the line; leading and trailing spaces are
ignored, so indentation is possible. No space should be written between
the type indicator and the text on that line.

A line starting with # is a comment which will not be written to the
output file. A blank line is also a comment.

The title of the hint file is specified by a line starting with & and
then the title follows.

Begin a block with < for a credit hunk, { for a subject hunk, ( for a
comment hunk (this is not the same as a # comment), and [ for a hint or
nesthint hunk (it automatically decides which). Following is an optional
node name (used only in the source file, for links), and then a dot and
the title of this block (the dot is required even if the internal name
is omitted).

End a block with ] ) } > to match the beginning. It can optionally be
followed by a node name; if it is, and it does not match, then it is an
error. (If there is no name given, it is OK whether or not a name was
given at the top.)

A line of text for any block other than a subject hunk starts with . and
then the text on that line follows.

Use - to make a separator in a menu (a subject hunk) or to separate the
hints inside of a hint block.

You can make a link by : and then the link name (the same as the node
name given in the beginning of the block), and then optionally . and the
title of the link. If the title is omitted, the title of the block it
points to is used.


=== view ===

This program is used to view a hint file in UHS format. Currently, it
implements most features of 88a, 91a, 95a, and 96a formats. It does not
care about the checksum.

It takes a single command-line argument being the name of the hint file.
You can optionally have additional arguments with + or - at first; if so,
they are followed by the letters of options to turn on or off.

When navigating to a node (it starts at the root node automatically), it
will display it. The first line displayed is the path of the node, using
greater-than signs between components, and displaying the title of each
component (except for 88a format hints, the root node's title will be the
same as the filename).

The prompt will be green, and will be "-" if there is more text, or "="
if there is no more text for the current node.

Nodes that can be accessed from the current node are listed with purple
numbers, and then the title is next to it. The colours are as follows:

- Cyan - A submenu

- Green - Normal text (not a hint)

- Yellow - Hints (possibly nested)

- Blue - A link to another node

- Red - Special information (such as format version)

Access one of the items by typing in its number. When a hint is accessed,
type a blank line to view the next hint.

Other commands are:

- [a]gain - Redisplay the current node. If it is a hint node, it starts
again from the first hint.

- [c]lear - Clear the screen and redisplay the current node.

- [f]ind - It will ask you for a word or phase to find, and then it will
search within the current node and its descendants for it, and print the
link numbers and titles of all nodes it finds. The "r" and "t" options
control this.

- [g]oto - Go back to the node remembered with the [m]ark command.

- [h]istory - Display history of recently viewed nodes. It is not saved
across sessions.

- [i]nfo - Display info about the current node. Currently this includes
the path, node type, and link number.

- [m]ark - Remember the current node.

- [o]ption - List the options. Options are not saved across sessions.

- [q]uit - Exit the program.

- [r]eset - Go back to the root node.

- [t]ree - Display a tree with the current node and its descendants.

- [u]p - Go up to the parent node.

- Link access - Type a forward slash followed by the link number (you can
see it by the [i]nfo command) to quickly navigate to that node.

- Turn on options - Type a plus sign and one or more letters to turn on
those options.

- Turn off options - Type a minus sign and one or more letters to turn off
those options.

- Help - Type a question mark for short help (listing the commands with
letters for a quick reference).

The letter in brackets indicates what letter to type to access that
command.

The valid options are:

- 8 - Display the 88a format hints even if the hint file is a new format.

- f - Causes # formatting to be parsed.

- r - Means the search term for the [f]ind command is a regular expression
(JavaScript format). This also makes it case-sensitive, unless overridden
within the regular expression. (By default, searches are case-insensitive)

- t - Searches full text if set. If not set, [f]ind only searches the
titles of nodes.