@thi.ng/transclude 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Change Log
+
+- **Last updated**: 2022-12-16T12:52:26Z
+- **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org/) for commit guidelines.
+
+**Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
+and/or version bumps of transitive dependencies.
+
+## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/transclude@0.1.0) (2022-12-16)
+
+#### 🚀 Features
+
+- import as new pkg ([dc05320](https://github.com/thi-ng/umbrella/commit/dc05320))

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,100 @@
+<!-- This file is generated - DO NOT EDIT! -->
+
+# ![@thi.ng/transclude](https://media.thi.ng/umbrella/banners-20220914/thing-transclude.svg?f63d93c4)
+
+[![npm version](https://img.shields.io/npm/v/@thi.ng/transclude.svg)](https://www.npmjs.com/package/@thi.ng/transclude)
+![npm downloads](https://img.shields.io/npm/dm/@thi.ng/transclude.svg)
+[![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
+
+This project is part of the
+[@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo.
+
+- [About](#about)
+- [Status](#status)
+- [Related packages](#related-packages)
+- [Installation](#installation)
+- [Dependencies](#dependencies)
+- [API](#api)
+- [Authors](#authors)
+- [License](#license)
+
+## About
+
+Extensible functional template engine for text document generation, incl. various high-level Markdown features
+
+This package evolved from this monorepo's readme generator toolchain and
+currently is mainly used to generate all ~350 readme & changelog files in this
+repo, but otherwise is **not** bound to this project in any way.
+
+Please see
+[`/tools/src/readme.ts`](https://github.com/thi-ng/umbrella/blob/develop/tools/src/readme.ts)
+for a concrete usage example...
+
+## Status
+
+**ALPHA** - bleeding edge / work-in-progress
+
+[Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Btransclude%5D+in%3Atitle)
+
+## Related packages
+
+- [@thi.ng/hiccup-markdown](https://github.com/thi-ng/umbrella/tree/develop/packages/hiccup-markdown) - Markdown parser & serializer from/to Hiccup format
+- [@thi.ng/markdown-table](https://github.com/thi-ng/umbrella/tree/develop/packages/markdown-table) - Markdown table formatter/generator with support for column alignments
+- [@thi.ng/tangle](https://github.com/thi-ng/umbrella/tree/develop/packages/tangle) - Literate programming code block tangling / codegen utility, inspired by org-mode & noweb
+
+## Installation
+
+```bash
+yarn add @thi.ng/transclude
+```
+
+ES module import:
+
+```html
+<script type="module" src="https://cdn.skypack.dev/@thi.ng/transclude"></script>
+```
+
+[Skypack documentation](https://docs.skypack.dev/)
+
+For Node.js REPL:
+
+```js
+const transclude = await import("@thi.ng/transclude");
+```
+
+Package sizes (brotli'd, pre-treeshake): ESM: 1.86 KB
+
+## Dependencies
+
+- [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
+- [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
+- [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
+- [@thi.ng/file-io](https://github.com/thi-ng/umbrella/tree/develop/packages/file-io)
+- [@thi.ng/logger](https://github.com/thi-ng/umbrella/tree/develop/packages/logger)
+- [@thi.ng/strings](https://github.com/thi-ng/umbrella/tree/develop/packages/strings)
+- [@thi.ng/transducers](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers)
+
+## API
+
+[Generated API docs](https://docs.thi.ng/umbrella/transclude/)
+
+TODO
+
+## Authors
+
+- [Karsten Schmidt](https://thi.ng)
+
+If this project contributes to an academic publication, please cite it as:
+
+```bibtex
+@misc{thing-transclude,
+  title = "@thi.ng/transclude",
+  author = "Karsten Schmidt",
+  note = "https://thi.ng/transclude",
+  year = 2022
+}
+```
+
+## License
+
+&copy; 2022 Karsten Schmidt // Apache License 2.0

package/api.d.ts

@@ -0,0 +1,46 @@
+import type { Fn3, IObjectOf } from "@thi.ng/api";
+import type { ILogger } from "@thi.ng/logger";
+/**
+ * Template functions receive the current {@link TranscludeCtx} and array of
+ * (raw) template arguments and the path of the current file.
+ */
+export type TemplateFn<T = any> = Fn3<TranscludeCtx<T>, string[], string, string>;
+export interface TranscludeCtx<T = any> {
+    /**
+     * User provided data of type `T`
+     */
+    user: T;
+    logger: ILogger;
+    /**
+     * Object of all known templates in this context.
+     */
+    templates: IObjectOf<TemplateFn<T> | string>;
+    /**
+     * Global pre-processing functions, in order of application. Receives entire
+     * file contents as first and only template arg, MUST return entire updated
+     * file contents.
+     */
+    pre: TemplateFn<T>[];
+    /**
+     * Global post-processing functions, in order of application. Receives
+     * entire file contents as first and only template arg, MUST return entire
+     * updated file contents.
+     */
+    post: TemplateFn<T>[];
+    /**
+     * Current contents to be processed.
+     */
+    src: string;
+    /**
+     * Template tag match regexp.
+     */
+    match: RegExp;
+    /**
+     * Line ending to be used for templates generating lists or other multi-line
+     * content.
+     *
+     * @defaultValue "\n"
+     */
+    eol: string;
+}
+//# sourceMappingURL=api.d.ts.map

package/api.js

@@ -0,0 +1 @@
+export {};

package/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./api.js";
+export * from "./transclude.js";
+export * from "./tpl/file.js";
+export * from "./tpl/markdown.js";
+export * from "./tpl/pkg.js";
+export * from "./tpl/whitespace.js";
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,6 @@
+export * from "./api.js";
+export * from "./transclude.js";
+export * from "./tpl/file.js";
+export * from "./tpl/markdown.js";
+export * from "./tpl/pkg.js";
+export * from "./tpl/whitespace.js";

package/package.json

@@ -0,0 +1,112 @@
+{
+  "name": "@thi.ng/transclude",
+  "version": "0.1.0",
+  "description": "Extensible functional template engine for text document generation, incl. various high-level Markdown features",
+  "type": "module",
+  "module": "./index.js",
+  "typings": "./index.d.ts",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thi-ng/umbrella.git"
+  },
+  "homepage": "https://github.com/thi-ng/umbrella/tree/develop/packages/transclude#readme",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/postspectacular"
+    },
+    {
+      "type": "patreon",
+      "url": "https://patreon.com/thing_umbrella"
+    }
+  ],
+  "author": "Karsten Schmidt (https://thi.ng)",
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "yarn clean && tsc --declaration",
+    "clean": "rimraf '*.js' '*.d.ts' '*.map' doc tpl",
+    "doc": "typedoc --excludePrivate --excludeInternal --out doc src/index.ts",
+    "doc:ae": "mkdir -p .ae/doc .ae/temp && api-extractor run --local --verbose",
+    "doc:readme": "yarn doc:stats && tools:readme",
+    "doc:stats": "tools:module-stats",
+    "pub": "yarn npm publish --access public",
+    "test": "testament test"
+  },
+  "dependencies": {
+    "@thi.ng/api": "^8.6.0",
+    "@thi.ng/checks": "^3.3.5",
+    "@thi.ng/errors": "^2.2.6",
+    "@thi.ng/file-io": "^0.3.22",
+    "@thi.ng/logger": "^1.4.5",
+    "@thi.ng/strings": "^3.3.20",
+    "@thi.ng/transducers": "^8.3.26"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.33.7",
+    "@thi.ng/testament": "^0.3.7",
+    "rimraf": "^3.0.2",
+    "tools": "^0.0.1",
+    "typedoc": "^0.23.22",
+    "typescript": "^4.9.4"
+  },
+  "keywords": [
+    "engine",
+    "functional",
+    "generator",
+    "json",
+    "markdown",
+    "npm",
+    "template",
+    "text",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "browser": {
+    "process": false,
+    "setTimeout": false
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "files": [
+    "./*.js",
+    "./*.d.ts",
+    "tpl"
+  ],
+  "exports": {
+    ".": {
+      "default": "./index.js"
+    },
+    "./api": {
+      "default": "./api.js"
+    },
+    "./tpl/file": {
+      "default": "./tpl/file.js"
+    },
+    "./tpl/markdown": {
+      "default": "./tpl/markdown.js"
+    },
+    "./tpl/pkg": {
+      "default": "./tpl/pkg.js"
+    },
+    "./tpl/whitespace": {
+      "default": "./tpl/whitespace.js"
+    },
+    "./transclude": {
+      "default": "./transclude.js"
+    }
+  },
+  "thi.ng": {
+    "related": [
+      "hiccup-markdown",
+      "markdown-table",
+      "tangle"
+    ],
+    "status": "alpha",
+    "year": 2022
+  },
+  "gitHead": "f445a9cc8022bcdebbf6ff91fd66ced016d72f01\n"
+}

package/tpl/file.d.ts

@@ -0,0 +1,20 @@
+import type { TemplateFn } from "../api.js";
+/**
+ * Parametric template function. Includes file given as template argument:
+ * `{{include header.md}}`
+ *
+ * @param ctx
+ * @param args
+ * @param currPath
+ */
+export declare const includeFile: TemplateFn;
+/**
+ * Pre-processing stage parametric template function. Includes file given as
+ * template argument: `<!-- include header.md -->`.
+ *
+ * @param ctx
+ * @param args
+ * @param currPath
+ */
+export declare const preincludeFile: TemplateFn;
+//# sourceMappingURL=file.d.ts.map

package/tpl/file.js

@@ -0,0 +1,20 @@
+import { readText } from "@thi.ng/file-io";
+import { resolve } from "path";
+/**
+ * Parametric template function. Includes file given as template argument:
+ * `{{include header.md}}`
+ *
+ * @param ctx
+ * @param args
+ * @param currPath
+ */
+export const includeFile = ({ logger }, args, currPath) => readText(resolve(resolve(currPath, ".."), args[2].trim()), logger);
+/**
+ * Pre-processing stage parametric template function. Includes file given as
+ * template argument: `<!-- include header.md -->`.
+ *
+ * @param ctx
+ * @param args
+ * @param currPath
+ */
+export const preincludeFile = ({ logger }, [src], currPath) => src.replace(new RegExp(`<!-- include (.+) -->`, "g"), (_, path) => readText(resolve(resolve(currPath, ".."), path.trim()), logger));

package/tpl/markdown.d.ts

@@ -0,0 +1,31 @@
+import type { TemplateFn } from "../api.js";
+export declare const image: (url: string, alt?: string) => string;
+export declare const link: (title: string, href: string) => string;
+export declare const list: (items: string[], eol?: string) => string;
+export interface TOCOpts {
+    /**
+     * Min headline level
+     *
+     * @defaultValue 2
+     */
+    min: number;
+    /**
+     * Max headline level
+     *
+     * @defaultValue 4
+     */
+    max: number;
+    /**
+     *
+     */
+    title: string;
+}
+/**
+ * Higher order, configurable post-processing template function. Injects a table
+ * of contents for the first `<!-- toc -->` occurrence. See {@link TOCOpts} for
+ * config options.
+ *
+ * @param opts
+ */
+export declare const toc: (opts?: Partial<TOCOpts>) => TemplateFn;
+//# sourceMappingURL=markdown.d.ts.map

package/tpl/markdown.js

@@ -0,0 +1,35 @@
+import { repeat } from "@thi.ng/strings/repeat";
+import { slugifyGH } from "@thi.ng/strings/slugify";
+import { split } from "@thi.ng/strings/split";
+import { comp } from "@thi.ng/transducers/comp";
+import { filter } from "@thi.ng/transducers/filter";
+import { map } from "@thi.ng/transducers/map";
+import { str } from "@thi.ng/transducers/str";
+import { transduce } from "@thi.ng/transducers/transduce";
+export const image = (url, alt = "") => `![${alt}](${url})`;
+export const link = (title, href) => `[${title}](${href})`;
+export const list = (items, eol = "\n") => transduce(map((x) => `- ${x}`), str(eol), items);
+/**
+ * Higher order, configurable post-processing template function. Injects a table
+ * of contents for the first `<!-- toc -->` occurrence. See {@link TOCOpts} for
+ * config options.
+ *
+ * @param opts
+ */
+export const toc = (opts) => ({ src, eol }) => {
+    const { min, max, match, disable, title } = {
+        min: 2,
+        max: 4,
+        match: "<!-- toc -->",
+        disable: /<\!-- notoc -->/i,
+        ...opts,
+    };
+    const isHeading = new RegExp(`^#{${min},${max}}\\s`);
+    const reHeading = new RegExp(`^(#{${min},${max}})\\s(.+)`);
+    const toc = transduce(comp(filter((line) => isHeading.test(line) && !disable.test(line)), map((hd) => {
+        const [_, level, title] = reHeading.exec(hd);
+        const indent = repeat("  ", Math.max(0, level.length - min));
+        return `${indent}- ${link(title, `#${slugifyGH(title)}`)}`;
+    })), str(eol), split(src));
+    return src.replace(match, title ? title + toc : toc);
+};

package/tpl/pkg.d.ts

@@ -0,0 +1,87 @@
+import type { Fn, IObjectOf } from "@thi.ng/api";
+import type { TemplateFn } from "../api.js";
+export interface Package {
+    name: string;
+    description: string;
+    version: string;
+    author: string | User;
+    license: string;
+    homepage: string;
+    contributors?: (string | User)[];
+    dependencies?: IObjectOf<string>;
+    devDependencies?: IObjectOf<string>;
+    keywords?: string[];
+}
+export interface User {
+    name: string;
+    email?: string;
+    url?: string;
+}
+export declare const LICENSES: IObjectOf<{
+    name: string;
+    url: string;
+}>;
+/**
+ * Returns the unscoped name of a package, i.e. the name without the package's
+ * group ID (if any).
+ *
+ * @param name
+ */
+export declare const shortName: (name: string) => string;
+/**
+ * Returns name of the author, given in any format supported by NPM.
+ *
+ * @param author
+ */
+export declare const author: (author: string | User) => string;
+/**
+ * Similar to {@link author}, but if an URL is available, returns a Markdown
+ * link to the author's URL, else just the name.
+ *
+ * @param author
+ */
+export declare const authorLink: (author: string | User) => string;
+/**
+ * Formats the {@link Package.contributors} as Markdown list.
+ *
+ * @param people
+ * @param eol
+ */
+export declare const contributors: (people: (string | User)[], eol?: string) => string;
+/**
+ * Similar to {@link contributors}, but formatted as list of links.
+ *
+ * @param people
+ * @param eol
+ */
+export declare const contributorLinks: (people: (string | User)[], eol?: string) => string;
+/**
+ * Returns the name for given SPDX license ID (only those in
+ * {@link LICENSES} are supported).
+ *
+ * @param spdxID
+ */
+export declare const license: (spdxID: string) => string;
+/**
+ * Similar to {@link license}, but returns Markdown link to license.
+ *
+ * @param spdxID
+ */
+export declare const licenseLink: (spdxID: string) => string;
+export interface PackageTemplateOpts {
+    /**
+     * Headline for list of contributors (only used if any present).
+     */
+    hdContributors: string;
+}
+export type PackageTemplates<T> = Record<"pkg.name" | "pkg.shortName" | "pkg.version" | "pkg.description" | "pkg.link" | "pkg.author" | "pkg.authorLink" | "pkg.contributors" | "pkg.contributorLinks" | "pkg.allAuthors" | "pkg.allAuthorLinks" | "pkg.license" | "pkg.licenseLink", TemplateFn<T>>;
+/**
+ * Higher order function returning various useful NPM package.json related
+ * templates. The user provided `pkg` function is used to look up the loaded
+ * {@link Package} data within the {@link TranscludeCtx.user} object.
+ *
+ * @param pkg
+ * @param opts
+ */
+export declare const packageTemplates: <T = any>(pkg: Fn<T, Package>, opts?: Partial<PackageTemplateOpts>) => PackageTemplates<T>;
+//# sourceMappingURL=pkg.d.ts.map

package/tpl/pkg.js

@@ -0,0 +1,219 @@
+import { isString } from "@thi.ng/checks/is-string";
+import { link, list } from "./markdown.js";
+export const LICENSES = {
+    "Apache-2.0": {
+        name: "Apache License 2.0",
+        url: "https://spdx.org/licenses/Apache-2.0.html",
+    },
+    "BSD-2-Clause": {
+        name: 'BSD 2-Clause "Simplified" License',
+        url: "https://spdx.org/licenses/BSD-2-Clause.html",
+    },
+    "BSD-3-Clause": {
+        name: 'BSD 3-Clause "New" or "Revised" License',
+        url: "https://spdx.org/licenses/BSD-3-Clause.html",
+    },
+    "CC-BY-4.0": {
+        name: "Creative Commons Attribution 4.0 International",
+        url: "https://spdx.org/licenses/CC-BY-4.0.html",
+    },
+    "CC-BY-NC-4.0": {
+        name: "Creative Commons Attribution Non Commercial 4.0 International",
+        url: "https://spdx.org/licenses/CC-BY-NC-4.0.html",
+    },
+    "CC-BY-NC-ND-4.0": {
+        name: "Creative Commons Attribution Non Commercial No Derivatives 4.0 International",
+        url: "https://spdx.org/licenses/CC-BY-NC-ND-4.0.html",
+    },
+    "CC-BY-NC-SA-4.0": {
+        name: "Creative Commons Attribution Non Commercial Share Alike 4.0 International",
+        url: "https://spdx.org/licenses/CC-BY-NC-SA-4.0.html",
+    },
+    "CC-BY-ND-4.0": {
+        name: "Creative Commons Attribution No Derivatives 4.0 International",
+        url: "https://spdx.org/licenses/CC-BY-ND-4.0.html",
+    },
+    "CC-BY-SA-4.0": {
+        name: "Creative Commons Attribution Share Alike 4.0 International",
+        url: "https://spdx.org/licenses/CC-BY-SA-4.0.html",
+    },
+    "CPAL-1.0": {
+        name: "Common Public Attribution License 1.0",
+        url: "https://spdx.org/licenses/CPAL-1.0.html",
+    },
+    "CPL-1.0": {
+        name: "Common Public License 1.0",
+        url: "https://spdx.org/licenses/CPL-1.0.html",
+    },
+    "ECL-2.0": {
+        name: "Educational Community License v2.0",
+        url: "https://spdx.org/licenses/ECL-2.0.html",
+    },
+    "EPL-2.0": {
+        name: "Eclipse Public License 2.0",
+        url: "https://spdx.org/licenses/EPL-2.0.html",
+    },
+    EUDatagrid: {
+        name: "EU DataGrid Software License",
+        url: "https://spdx.org/licenses/EUDatagrid.html",
+    },
+    "EUPL-1.2": {
+        name: "European Union Public License 1.2",
+        url: "https://spdx.org/licenses/EUPL-1.2.html",
+    },
+    "GFDL-1.3-or-later": {
+        name: "GNU Free Documentation License v1.3 or later",
+        url: "https://spdx.org/licenses/GFDL-1.3-or-later.html",
+    },
+    "GPL-3.0-or-later": {
+        name: "GNU General Public License v3.0 or later",
+        url: "https://spdx.org/licenses/GPL-3.0-or-later.html",
+    },
+    ISC: { name: "ISC License", url: "https://spdx.org/licenses/ISC.html" },
+    "LGPL-3.0-or-later": {
+        name: "GNU Lesser General Public License v3.0 or later",
+        url: "https://spdx.org/licenses/LGPL-3.0-or-later.html",
+    },
+    MIT: { name: "MIT License", url: "https://spdx.org/licenses/MIT.html" },
+    "MPL-2.0": {
+        name: "Mozilla Public License 2.0",
+        url: "https://spdx.org/licenses/MPL-2.0.html",
+    },
+    "OFL-1.1": {
+        name: "SIL Open Font License 1.1",
+        url: "https://spdx.org/licenses/OFL-1.1.html",
+    },
+    Unlicense: {
+        name: "The Unlicense",
+        url: "https://spdx.org/licenses/Unlicense.html",
+    },
+    "UPL-1.0": {
+        name: "Universal Permissive License v1.0",
+        url: "https://spdx.org/licenses/UPL-1.0.html",
+    },
+    Zlib: { name: "zlib License", url: "https://spdx.org/licenses/Zlib.html" },
+};
+/**
+ * Returns the unscoped name of a package, i.e. the name without the package's
+ * group ID (if any).
+ *
+ * @param name
+ */
+export const shortName = (name) => {
+    const idx = name.indexOf("/");
+    return idx > 0 ? name.substring(idx + 1) : name;
+};
+/**
+ * Returns name of the author, given in any format supported by NPM.
+ *
+ * @param author
+ */
+export const author = (author) => isString(author) ? author.split(/\s*[<\(]/)[0] : author.name;
+/**
+ * Similar to {@link author}, but if an URL is available, returns a Markdown
+ * link to the author's URL, else just the name.
+ *
+ * @param author
+ */
+export const authorLink = (author) => {
+    if (isString(author)) {
+        const [name, a, b] = author.split(/\s*[<\(]/);
+        const href = b ? (b[b.length - 1] == ")" ? b : a) : a ? a : "";
+        return href.length && href[href.length - 1] === ")"
+            ? link(name, href.substring(0, href.length - 1))
+            : name;
+    }
+    return author.url ? link(author.name, author.url) : author.name;
+};
+/**
+ * Formats the {@link Package.contributors} as Markdown list.
+ *
+ * @param people
+ * @param eol
+ */
+export const contributors = (people, eol = "\n") => list(people.map(author), eol);
+/**
+ * Similar to {@link contributors}, but formatted as list of links.
+ *
+ * @param people
+ * @param eol
+ */
+export const contributorLinks = (people, eol = "\n") => list(people.map(authorLink), eol);
+/**
+ * Returns the name for given SPDX license ID (only those in
+ * {@link LICENSES} are supported).
+ *
+ * @param spdxID
+ */
+export const license = (spdxID) => LICENSES[spdxID].name || `${spdxID} license`;
+/**
+ * Similar to {@link license}, but returns Markdown link to license.
+ *
+ * @param spdxID
+ */
+export const licenseLink = (spdxID) => {
+    const license = LICENSES[spdxID];
+    return license ? link(license.name, license.url) : `${spdxID} license`;
+};
+/**
+ * Higher order function returning various useful NPM package.json related
+ * templates. The user provided `pkg` function is used to look up the loaded
+ * {@link Package} data within the {@link TranscludeCtx.user} object.
+ *
+ * @param pkg
+ * @param opts
+ */
+export const packageTemplates = (pkg, opts) => {
+    const $opts = {
+        hdContributors: "### Contributors\n\n",
+        ...opts,
+    };
+    const tpls = {
+        "pkg.name": ({ user }) => pkg(user).name,
+        "pkg.shortName": ({ user }) => shortName(pkg(user).name),
+        "pkg.version": ({ user }) => "v" + pkg(user).version,
+        "pkg.description": ({ user }) => pkg(user).description,
+        "pkg.link": ({ user }) => link(pkg(user).name, pkg(user).homepage),
+        "pkg.author": ({ user }) => author(pkg(user).author),
+        "pkg.authorLink": ({ user }) => authorLink(pkg(user).author),
+        "pkg.contributors": ({ user, eol }) => {
+            const people = pkg(user).contributors;
+            return people
+                ? $opts.hdContributors + contributors(people, eol)
+                : "";
+        },
+        "pkg.contributorLinks": ({ user, eol }) => {
+            const people = pkg(user).contributors;
+            return people
+                ? $opts.hdContributors + contributorLinks(people, eol)
+                : "";
+        },
+        "pkg.allAuthors": ({ user, eol }) => {
+            const $pkg = pkg(user);
+            const $author = author($pkg.author);
+            const res = [];
+            if ($pkg.contributors) {
+                res.push($author + " (Main author)", ...$pkg.contributors.map(author));
+            }
+            else {
+                res.push($author);
+            }
+            return list(res, eol);
+        },
+        "pkg.allAuthorLinks": ({ user, eol }) => {
+            const $pkg = pkg(user);
+            const $author = authorLink($pkg.author);
+            const res = [];
+            if ($pkg.contributors) {
+                res.push($author + " (Main author)", ...$pkg.contributors.map(authorLink));
+            }
+            else {
+                res.push($author);
+            }
+            return list(res, eol);
+        },
+        "pkg.license": ({ user }) => license(pkg(user).license),
+        "pkg.licenseLink": ({ user }) => licenseLink(pkg(user).license),
+    };
+    return tpls;
+};

package/tpl/whitespace.d.ts

@@ -0,0 +1,16 @@
+import type { TemplateFn } from "../api";
+/**
+ * Post-processing stage template function. Replaces all leading tabs (per line
+ * indentation) with `size` spaces.
+ *
+ * @param size
+ */
+export declare const tabsToSpaces: (size?: number) => TemplateFn;
+/**
+ * Post-processing stage template function. Compacts successive empty lines to a
+ * max. of 1 empty line.
+ *
+ * @param ctx
+ */
+export declare const compactEmptyLines: TemplateFn;
+//# sourceMappingURL=whitespace.d.ts.map

package/tpl/whitespace.js

@@ -0,0 +1,17 @@
+/**
+ * Post-processing stage template function. Replaces all leading tabs (per line
+ * indentation) with `size` spaces.
+ *
+ * @param size
+ */
+export const tabsToSpaces = (size = 4) => {
+    const indent = " ".repeat(size);
+    return ({ src }) => src.replace(/^\t+/gm, (x) => indent.repeat(x.length));
+};
+/**
+ * Post-processing stage template function. Compacts successive empty lines to a
+ * max. of 1 empty line.
+ *
+ * @param ctx
+ */
+export const compactEmptyLines = ({ src, eol }) => src.replace(/(\r?\n){2,}/g, eol.repeat(2)).trim() + eol;

package/transclude.d.ts

@@ -0,0 +1,25 @@
+import type { SomeRequired } from "@thi.ng/api";
+import type { TranscludeCtx } from "./api.js";
+type Mandatory = "src" | "templates" | "user";
+export declare const transclude: <T>(ctx: SomeRequired<TranscludeCtx<T>, Mandatory>, path: string) => {
+    match: RegExp;
+    pre: import("./api.js").TemplateFn<T>[];
+    logger: import("@thi.ng/logger").ILogger;
+    post: import("./api.js").TemplateFn<T>[];
+    eol: string;
+    user: T;
+    src: string;
+    templates: import("@thi.ng/api").IObjectOf<string | import("./api.js").TemplateFn<T>>;
+};
+export declare const transcludeFile: <T>(path: string, ctx: SomeRequired<TranscludeCtx<T>, "user" | "templates">) => {
+    match: RegExp;
+    pre: import("./api.js").TemplateFn<T>[];
+    logger: import("@thi.ng/logger").ILogger;
+    post: import("./api.js").TemplateFn<T>[];
+    eol: string;
+    user: T;
+    src: string;
+    templates: import("@thi.ng/api").IObjectOf<string | import("./api.js").TemplateFn<T>>;
+};
+export {};
+//# sourceMappingURL=transclude.d.ts.map

package/transclude.js

@@ -0,0 +1,38 @@
+import { readText } from "@thi.ng/file-io/text";
+import { ConsoleLogger } from "@thi.ng/logger";
+import { resolve } from "path";
+const DEFAULT_LOGGER = new ConsoleLogger("transclude");
+export const transclude = (ctx, path) => {
+    const $ctx = {
+        logger: DEFAULT_LOGGER,
+        match: /\{\{([a-z0-9.]+)([^}]*)\}\}/gi,
+        pre: [],
+        post: [],
+        eol: "\n",
+        ...ctx,
+    };
+    $ctx.pre.reduce((acc, fn) => ($ctx.src = fn($ctx, [acc], path)), $ctx.src);
+    $ctx.src = $ctx.src.replace($ctx.match, (...xs) => {
+        const [orig, id] = xs;
+        const tpl = $ctx.templates[id];
+        if (tpl !== undefined) {
+            return typeof tpl === "function" ? tpl($ctx, xs, path) : tpl;
+        }
+        else {
+            $ctx.logger.warn(`skipping unknown tpl ID: "${id}"`);
+            return orig;
+        }
+    });
+    $ctx.post.reduce((acc, fn) => ($ctx.src = fn($ctx, [acc], path)), $ctx.src);
+    return $ctx;
+};
+export const transcludeFile = (path, ctx) => {
+    const $ctx = {
+        logger: DEFAULT_LOGGER,
+        src: "",
+        ...ctx,
+    };
+    path = resolve(path);
+    $ctx.src = readText(path, $ctx.logger);
+    return transclude($ctx, path);
+};