@weborigami/origami 0.0.72 → 0.1.0

package/src/help/help.yaml

@@ -0,0 +1,425 @@
+calc:
+  description: Perform math and logical operations
+  commands:
+    add:
+      args: (a, b, ...)
+      description: Add the numbers
+    and:
+      args: (a, b, ...)
+      description: Return true if all the arguments are true
+    divide:
+      args: (a, b)
+      description: Divide a by b
+    equals:
+      args: (a, b)
+      description: Return true if a equals b
+    if:
+      args: (a, b, c)
+      description: If a is true return b, otherwise c
+    multiply:
+      args: (a, b, ...)
+      description: Multiply the numbers
+    not:
+      args: (value)
+      description: Return true if a is false and vice versa
+    or:
+      args: (a, b, ...)
+      description: Return true if any of the arguments are true
+    subtract:
+      args: (a, b)
+      description: Subtract b from a
+
+dev:
+  description: Develop and debug Origami projects
+  commands:
+    breakpoint:
+      args: (a)
+      description: Break into the JavaScript debugger, then return a
+    changes:
+      args: (old, new)
+      description: Return a tree of changes
+    debug:
+      args: (tree)
+      description: Add debug features to the tree
+    explore:
+      args: ()
+      description: Explore the current scope [when run in browser]
+    log:
+      args: (a, message)
+      description: Log message to the console and return a
+    serve:
+      args: (tree, port)
+      description: Start a web server for the tree
+    svg:
+      args: (tree, options)
+      description: Render a tree visually in SVG format
+    watch:
+      args: (tree, fn)
+      description: Reevaluate fn when tree changes
+
+explore:
+  description: URL protocol to treat a website with JSON keys as a tree
+
+files:
+  description: URL protocol for file system folders and files
+
+help:
+  description: Get help on builtin namespaces and commands
+
+http:
+  description: URL protocol for web resources via HTTP
+
+https:
+  description: URL protocol for web resources via HTTPS
+
+httpstree:
+  description: URL protocol for a website tree via HTTPS
+
+httptree:
+  description: URL protocol for a website tree via HTTP
+
+image:
+  description: Format and resize images
+  commands:
+    format:
+      args: (image, format, options)
+      description: Return the image in a different format
+    resize:
+      args: (image, options)
+      description: Resize the image
+
+inherited:
+  description: URL protocol to get an inherited value instead of a local one
+
+js:
+  description: JavaScript classes and functions
+  collection: true
+  commands:
+    Array:
+      description: JavaScript Array class
+    Boolean:
+      description: JavaScript Boolean class
+    Date:
+      description: JavaScript Date class
+    Error:
+      description: JavaScript Error class
+    Infinity:
+      description: JavaScript Infinity constant
+    Intl:
+      description: JavaScript Intl object
+    JSON:
+      description: JavaScript JSON object
+    Map:
+      description: JavaScript Map class
+    Math:
+      description: JavaScript Math object
+    NaN:
+      description: JavaScript NaN constant
+    Number:
+      description: JavaScript Number class
+    Object:
+      description: JavaScript Object class
+    RegExp:
+      description: JavaScript RegExp class
+    Set:
+      description: JavaScript Set class
+    String:
+      description: JavaScript String class
+    Symbol:
+      description: JavaScript Symbol class
+    decodeURI:
+      description: JavaScript decodeURI function
+    decodeURIComponent:
+      description: JavaScript decodeURIComponent function
+    encodeURI:
+      description: JavaScript encodeURI function
+    encodeURIComponent:
+      description: JavaScript encodeURIComponent function
+    "false":
+      description: JavaScript false constant
+    fetch:
+      description: JavaScript fetch function
+    isFinite:
+      description: JavaScript isFinite function
+    isNaN:
+      description: JavaScript isNaN function
+    "null":
+      description: JavaScript null constant
+    parseFloat:
+      description: JavaScript parseFloat function
+    parseInt:
+      description: JavaScript parseInt function
+    "true":
+      description: JavaScript true constant
+    undefined:
+      description: JavaScript undefined constant
+
+new:
+  description: Create instances of JavaScript classes
+
+node:
+  description: Node.js classes and modules
+  collection: true
+  commands:
+    Buffer:
+      description: Node.js Buffer class
+    path:
+      description: Node.js path module
+    process:
+      description: Node.js process object
+    url:
+      description: Node.js URL module
+
+origami:
+  description: Perform general Origami language functions
+  commands:
+    basename:
+      args: (key)
+      description: Removes an extension from the key if present
+    builtins:
+      description: The set of installed builtin functions
+    config:
+      description: The current project's configuration
+    extension:
+      description: Helpers for working with file extensions
+    json:
+      args: (obj)
+      description: Render the object in JSON format
+    jsonParse:
+      args: (text)
+      description: Parse text as JSON
+    naturalOrder:
+      description: A comparison function for natural sort order
+    once:
+      args: (fn)
+      description: Run the function only once, return the same result
+    ori:
+      args: (text)
+      description: Evaluate the text as an Origami expression
+    post:
+      args: (url, data)
+      description: POST the given data to the URL
+    project:
+      description: The root folder for the current Origami project
+    regexMatch:
+      args: (text, regex)
+      description: Return matches of the regex in the text
+    repeat:
+      args: (n, obj)
+      description: An array of n copies of the object
+    shell:
+      args: (text)
+      description: Run the text as a shell command, return the output
+    slash:
+      description: Helpers for working with trailing slashes
+    stdin:
+      description: Returns the content of the standard input stream
+    string:
+      args: (obj)
+      description: Coerce a buffer or document to a string
+    toFunction:
+      args: (obj)
+      description: Coerce a tree or packed function definition to a function
+    unpack:
+      args: (buffer)
+      description: Unpack the buffer into a usable form
+    version:
+      args: ()
+      description: Return the version number of the Origami language
+    yaml:
+      args: (obj)
+      description: Render the object in YAML format
+    yamlParse:
+      args: (text)
+      description: Parse text as YAML
+
+package:
+  description: URL protocol for packages installed in node_modules
+
+scope:
+  description: URL protocol to explicitly reference a key in scope
+
+site:
+  description: Add common website features
+  commands:
+    audit:
+      args: (tree)
+      description: Identify broken internal links and references
+    crawl:
+      args: (tree, base)
+      description: A tree of a site's discoverable resources
+    index:
+      args: (tree)
+      description: A default index.html page for the tree
+    jsonKeys:
+      args: (tree)
+      description: Add .keys.json files to a tree
+    redirect:
+      args: (url, options)
+      description: Redirect to the given URL
+    rss:
+      args: (feed)
+      description: Transforms a JSON Feed tree to RSS XML
+    sitemap:
+      args: (tree)
+      description: Generate a sitemap for the tree
+    slug:
+      args: (text)
+      description: A version of the text suitable for use in URLs
+    static:
+      args: (tree)
+      description: Define common static files for the tree
+
+text:
+  description: Manipulate text
+  commands:
+    document:
+      args: (text, [data])
+      description: Create a document object with the text and data
+    indent:
+      description: Tagged template literal for normalizing indentation
+    inline:
+      args: (text)
+      description: Inline Origami expressions found in the text
+    mdHtml:
+      args: (markdown)
+      description: Render the markdown as HTML
+
+tree:
+  description: Work with trees
+  commands:
+    addNextPrevious:
+      args: (tree)
+      description: Add next/previous fields to the tree's values
+    assign:
+      args: (target, source)
+      description: Apply key/values from source to target
+    cache:
+      args: (tree, [cache], [filter])
+      description: Caches values from the tree
+    clear:
+      args: (tree)
+      description: Remove all values from the tree
+    concat:
+      args: (...objs)
+      description: Concatenate text and/or trees of text
+    copy:
+      args: (source, target)
+      description: Copy the source tree to the target
+    deepMap:
+      args: (tree, options)
+      description: Map the keys and values of a deep tree
+    deepMerge:
+      args: (...trees)
+      description: Return a deeply-merged tree
+    deepReverse:
+      args: (tree)
+      description: Reverse order of keys at all levels of the tree
+    deepTake:
+      args: (tree, n)
+      description: The first n values from the deep tree
+    deepValues:
+      args: (tree)
+      description: The in-order leaf values of the tree
+    defineds:
+      args: (tree)
+      description: Only the defined values of the tree
+    entries:
+      args: (tree)
+      description: The tree's [key, value] pairs
+    first:
+      args: (tree)
+      description: The first value in the tree
+    forEach:
+      args: (tree, fn)
+      description: Apply fn to each (value, key)
+    from:
+      args: (object, options)
+      description: Create a tree from an object
+    fromFn:
+      args: (fn, [keys])
+      description: A tree defined by a value function
+    globs:
+      args: (patterns)
+      description: A tree whose keys can include wildcard patterns
+    group:
+      args: (tree, fn)
+      description: A new tree with values grouped by the function
+    has:
+      args: (tree, key)
+      description: True if key exists in tree
+    inners:
+      args: (tree)
+      description: The tree's interior nodes
+    isAsyncMutableTree:
+      args: (object)
+      description: True if object is an async mutable tree
+    isAsyncTree:
+      args: (object)
+      description: True if object is an async tree
+    isTraversable:
+      args: (object)
+      description: True if object is traversable
+    isTreelike:
+      args: (object)
+      description: True if object can be coerced to a tree
+    keys:
+      args: (tree)
+      description: The keys of the tree
+    length:
+      args: (tree)
+      description: The tree's size (number of keys)
+    map:
+      args: (tree, options)
+      description: Create a new tree by mapping keys and/or values
+    mapReduce:
+      args: (tree, valueFn, reduceFn)
+      description: Map values and reduce them
+    match:
+      args: (pattern, fn, [keys])
+      description: Matches simple patterns or regular expressions
+    merge:
+      args: (...trees)
+      description: Return a new tree merging the given trees
+    paginate:
+      args: (tree, [n])
+      description: Group the tree's values into fixed-size sets
+    parent:
+      args: (tree)
+      description: The parent of the given tree node
+    paths:
+      args: (tree)
+      description: Slash-separated paths for the tree's values
+    plain:
+      args: (tree)
+      description: Render the tree as a plain JavaScript object
+    remove:
+      args: (tree, key)
+      description: Remove the value for the key from tree
+    reverse:
+      args: (tree)
+      description: Reverse the order of the tree's keys
+    setDeep:
+      args: (target, source)
+      description: Applies the source tree to the target
+    shuffle:
+      args: (tree)
+      description: Shuffle the keys of the tree
+    sort:
+      args: (tree, options)
+      description: A new tree with its keys sorted
+    take:
+      args: (tree, n)
+      description: The first n values in the tree
+    traverse:
+      args: (tree, ...keys)
+      description: Return the value at the path of keys
+    traverseOrThrow:
+      args: (tree, ...keys)
+      description: Return the value at the path of keys or throw
+    traversePath:
+      args: (tree, path)
+      description: Traverse a slash-separated path
+    values:
+      args: (tree)
+      description: The tree's values

package/src/{builtins/@image → image}/format.js

@@ -1,4 +1,4 @@
-import assertTreeIsDefined from "../../misc/assertTreeIsDefined.js";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 import imageFormatFn from "./formatFn.js";
 
 /**
@@ -13,6 +13,6 @@ import imageFormatFn from "./formatFn.js";
  * @param {any} options
  */
 export default async function imageFormat(input, format, options) {
-  assertTreeIsDefined(this, "image/format");
+  assertTreeIsDefined(this, "image:format");
   return imageFormatFn.call(this, format, options)(input);
 }

package/src/{builtins/@image → image}/formatFn.js

@@ -1,5 +1,5 @@
 import sharp from "sharp";
-import assertTreeIsDefined from "../../misc/assertTreeIsDefined.js";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 
 /**
  * Return a function that transforms an input image to a different format.

package/src/image/image.js

@@ -0,0 +1,2 @@
+export { default as format } from "./format.js";
+export { default as resize } from "./resize.js";

package/src/{builtins/@image → image}/resize.js

@@ -1,4 +1,4 @@
-import assertTreeIsDefined from "../../misc/assertTreeIsDefined.js";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 import imageResizeFn from "./resizeFn.js";
 
 /**
@@ -9,6 +9,6 @@ import imageResizeFn from "./resizeFn.js";
  * @param {import("sharp").ResizeOptions} options
  */
 export default async function resize(input, options) {
-  assertTreeIsDefined(this, "image/resize");
+  assertTreeIsDefined(this, "image:resize");
   return imageResizeFn.call(this, options)(input);
 }

package/src/{builtins/@image → image}/resizeFn.js

@@ -1,5 +1,5 @@
 import sharp from "sharp";
-import assertTreeIsDefined from "../../misc/assertTreeIsDefined.js";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 
 /**
  * Return a function that resizes an image.

package/src/internal.js

@@ -0,0 +1,24 @@
+//
+// This library includes a number of modules with circular dependencies. This
+// module exists to explicitly set the loading order for those modules. To
+// enforce use of this loading order, other modules should only load the modules
+// below via this module.
+//
+// About this pattern:
+// https://medium.com/visual-development/how-to-fix-nasty-circular-dependency-issues-once-and-for-all-in-javascript-typescript-a04c987cf0de
+//
+// Note: to avoid having VS Code auto-sort the imports, keep lines between them.
+
+export { default as jsHandler } from "./handlers/js.handler.js";
+
+export { default as oriHandler } from "./handlers/ori.handler.js";
+
+export { default as oridocumentHandler } from "./handlers/oridocument.handler.js";
+
+export { default as processUnpackedContent } from "./common/processUnpackedContent.js";
+
+export { default as wasmHandler } from "./handlers/wasm.handler.js";
+
+export { default as yamlHandler } from "./handlers/yaml.handler.js";
+
+export { default as builtinsTree } from "./builtinsTree.js";

package/src/{builtins/@js.js → js.js}

@@ -1,4 +1,9 @@
-const js = {
+async function fetchWrapper(resource, options) {
+  const response = await fetch(resource, options);
+  return response.ok ? await response.arrayBuffer() : undefined;
+}
+
+export default {
   Array,
   Boolean,
   Date,
@@ -20,6 +25,7 @@ const js = {
   encodeURI,
   encodeURIComponent,
   false: false,
+  fetch: fetchWrapper,
   isFinite,
   isNaN,
   null: null,
@@ -28,8 +34,3 @@ const js = {
   true: true,
   undefined: undefined,
 };
-
-js.usage = "@js\tAccess JavaScript classes and utility functions";
-js.documentation = "https://weborigami.org/language/@js.html";
-
-export default js;

package/src/{builtins/@node.js → node.js}

@@ -14,14 +14,9 @@ const patchedProcess = Object.create(null, {
   },
 });
 
-const node = {
+export default {
   Buffer,
   path,
   process: patchedProcess,
   url,
 };
-
-node.usage = "@node\tAccess Node classes and utility functions";
-node.documentation = "https://weborigami.org/language/@node.html";
-
-export default node;

package/src/{builtins/@basename.js → origami/basename.js}

@@ -1,6 +1,6 @@
-import { extname } from "@weborigami/language";
+import { extension } from "@weborigami/async-tree";
 
 export default function basename(key) {
-  const ext = extname(key);
+  const ext = extension.extname(key);
   return ext ? key.slice(0, -ext.length) : key;
 }

package/src/{builtins/@config.js → origami/config.js}

@@ -1,4 +1,4 @@
-import project from "./@project.js";
+import project from "./project.js";
 
 /**
  * Return the configuration for the current project.
@@ -18,6 +18,3 @@ export default async function config(key) {
   const parent = projectTree.parent;
   return key === undefined ? parent : parent.get(key);
 }
-
-config.usage = `@config\tThe current project's configuration tree`;
-config.documentation = "https://weborigami.org/language/@config.html";

package/src/{builtins/@json.js → origami/json.js}

@@ -1,6 +1,6 @@
 /** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
 import { isUnpackable, toPlainValue } from "@weborigami/async-tree";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 
 /**
  * Render the given object in JSON format.
@@ -9,7 +9,7 @@ import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
  * @param {any} [obj]
  */
 export default async function json(obj) {
-  assertTreeIsDefined(this, "json");
+  assertTreeIsDefined(this, "origami:json");
   // A fragment of the logic from getTreeArgument.js
   if (arguments.length > 0 && obj === undefined) {
     throw new Error(
@@ -26,6 +26,3 @@ export default async function json(obj) {
   const value = await toPlainValue(obj);
   return JSON.stringify(value, null, 2);
 }
-
-json.usage = "@json <obj>\tRender the object as text in JSON format";
-json.documentation = "https://weborigami.org/builtins/@json.html";

package/src/{builtins/@jsonParse.js → origami/jsonParse.js}

@@ -4,6 +4,3 @@ export default async function jsonParse(input) {
   const text = toString(input);
   return text ? JSON.parse(text) : undefined;
 }
-
-jsonParse.usage = `@jsonParse <text>\tParse text as JSON`;
-jsonParse.documentation = "https://weborigami.org/builtins/@jsonParse.html";

package/src/{builtins/@once.js → origami/once.js}

@@ -1,4 +1,4 @@
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 
 const fnPromiseMap = new WeakMap();
 
@@ -10,7 +10,7 @@ const fnPromiseMap = new WeakMap();
  * @param {Function} fn
  */
 export default async function once(fn) {
-  assertTreeIsDefined(this, "once");
+  assertTreeIsDefined(this, "origami:once");
   if (!fnPromiseMap.has(fn)) {
     fnPromiseMap.set(fn, fn.call(this));
   }

package/src/{builtins/@ori.js → origami/ori.js}

@@ -4,9 +4,9 @@ import {
   toString,
 } from "@weborigami/async-tree";
 import { compile } from "@weborigami/language";
-import builtins from "../builtins/@builtins.js";
+import builtinsTree from "../builtinsTree.js";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 import { toYaml } from "../common/serialize.js";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
 
 const TypedArray = Object.getPrototypeOf(Uint8Array);
 
@@ -23,16 +23,18 @@ export default async function ori(
   expression,
   options = { formatResult: true }
 ) {
-  assertTreeIsDefined(this, "ori");
+  assertTreeIsDefined(this, "origami:ori");
 
   // In case expression has come from a file, cast it to a string.
   expression = toString(expression);
 
   // Run in the context of `this` if defined, otherwise use the builtins.
-  const tree = this ?? builtins;
+  const tree = this ?? builtinsTree;
 
-  // Parse
-  const fn = compile.expression(expression);
+  // Compile the expression. Avoid caching scope references so that, e.g.,
+  // passing a function to the `watch` builtin will always look the current
+  // value of things in scope.
+  const fn = compile.expression(expression, { scopeCaching: false });
 
   // Execute
   let result = await fn.call(tree);
@@ -89,6 +91,3 @@ async function formatResult(result) {
 
   return text;
 }
-
-ori.usage = `@ori <text>\tEvaluates the text as an Origami expression`;
-ori.documentation = "https://weborigami.org/language/@ori.html";

package/src/origami/origami.js

@@ -0,0 +1,29 @@
+// Use a dynamic import to avoid circular dependencies
+export const builtins = import("../internal.js").then(
+  (internal) => internal.builtinsTree
+);
+
+export { extension } from "@weborigami/async-tree";
+export { toFunction } from "../common/utilities.js";
+
+export { default as help } from "../help/help.js"; // Alias
+export { default as basename } from "./basename.js";
+export { default as config } from "./config.js";
+export { default as json } from "./json.js";
+export { default as jsonParse } from "./jsonParse.js";
+export { default as naturalOrder } from "./naturalOrder.js";
+export { default as once } from "./once.js";
+export { default as ori } from "./ori.js";
+export { default as pack } from "./pack.js";
+export { default as post } from "./post.js";
+export { default as project } from "./project.js";
+export { default as regexMatch } from "./regexMatch.js";
+export { default as repeat } from "./repeat.js";
+export { default as shell } from "./shell.js";
+export { default as slash } from "./slash.js";
+export { default as stdin } from "./stdin.js";
+export { default as string } from "./string.js";
+export { default as unpack } from "./unpack.js";
+export { default as version } from "./version.js";
+export { default as yaml } from "./yaml.js";
+export { default as yamlParse } from "./yamlParse.js";