Document module system

    Fix #511.

1 files changed, 85 insertions, 0 deletions

diff --git a/docs/content/3.manual/manual.yml b/docs/content/3.manual/manual.yml
index c9e3ce09..4e510f8d 100644
--- a/docs/content/3.manual/manual.yml
+++ b/docs/content/3.manual/manual.yml
@@ -161,6 +161,11 @@ sections:
         Read filter from the file rather than from a command line, like
         awk's -f option. You can also use '#' to make comments.
 
+      * `-Ldirectory` / `-L directory`:
+
+        Add `directory` to the search list for modules.  See the section
+        on modules below.
+
       * `-e` / `--exit-status`:
 
         Sets the exit status of jq to 0 if the last output values was
@@ -2239,3 +2244,83 @@ sections:
 
               (.posts[] | select(.author == "stedolan") | .comments) |=
                   . + ["terrible."]
+
+  - title: Modules
+    body: |
+
+      jq has a library/module system.  Modules are files whose names end
+      in `.jq`.  Modules should start with a `module` directive.
+      Programs and modules must `import` their dependencies, if any.
+
+      A search path is used to search for modules.  Each directory in
+      the search path is tested twice: once with a directory named "any"
+      added on the end, and once with the jq version number as a
+      directory added on the end.
+
+      For paths starting with "~/", the user's home directory is
+      substituted for "~".
+
+      For paths starting with "$ORIGIN/", the path of the directory of
+      the dependent is used.  For main programs that's the path of the
+      jq executable's containing directory.
+
+      Modules may be organized into a hierarchy, with name components
+      separated by double-colons ("::").  For example: "foo::bar".  Each
+      component in the name corresponds to a directory on the
+      filesystem.  Consecutive components with the same name are not
+      allowed to avoid ambiguities (e.g., "foo::foo").
+
+      For example, a module named "foo::bar" would be searched for in
+      "foo/bar.jq" and "foo/bar/bar.jq" in the given search path. This
+      is intended to allow modules to be placed in a directory along
+      with, for example, version control files, README files, and so on,
+      but also to allow for single-file modules.
+
+      The search path used is as follows:
+
+      - the directory indicated in the search key of the `import`
+        directive metadata (see below)
+      - otherwise any directory(ies) listed in the `-L` command-line
+        argument
+      - otherwise any directory(ies) listed in the `$JQ_LIBRARY_PATH`
+        environment variable
+
+      For example, with `-L$HOME/.jq` A module `foo` can be found in
+      `$HOME/.jq/any/foo.jq`, `$HOME/.jq/1.4/foo.jq`,
+      `$HOME/.jq/any/foo/foo.jq`, and in `$HOME/.jq/foo/foo.jq`.
+
+    entries:
+      - title: "`module NAME {<metadata>};`"
+        body: |
+
+          Defines a module named `NAME` with the given metadata.  If
+          given it must be the first thing in the module.  Programs also
+          may use this directive.
+
+          The metadata must be a constant jq expression.  It should be
+          an object with keys like "version", "repo", "URI", and so on.
+          At this time jq doesn't use this metadata, but it is made
+          available to users via the `modulemeta` builtin.
+
+      - title: "`import NAME {<metadata>};` `import NAME {<metadata>} as NAME;`"
+        body: |
+
+          Imports a module named `NAME`.  If the second form is used
+          then the module's symbols are prefixed with "NAME::".
+
+          The metadata must be a constant jq expression.  It should be
+          an object with keys like "version", "repo", "URI", and so on.
+          
+          The "search" key in the metadata, if present, should have a
+          string value consisting of a single directory path to search.
+
+      - title: "`modulemeta`"
+        body: |
+
+          Takes a module name as input and outputs the module's
+          metadata, with the module's imports (including metadata) as
+          the "deps" key.
+
+          Programs can use this to query a module's metadata, which they
+          could then use to, for example, search for, download, and
+          install missing dependencies.