@cto.af/linewrap-cli 1.0.0

package/README.md

@@ -0,0 +1,88 @@
+# @cto.af/linewrap-cli
+
+A command-line interface (CLI) for the
+[@cto.af/linewrap](https://github.com/cto-af/linewrap) project.
+
+## Installation
+
+```sh
+npm install -g @cto.af/linewrap-cli
+```
+
+### Invocation
+
+```txt
+Usage: linewrap [options] [...file]
+
+Wrap some text, either from file, stdin, or given on the command line.  Each
+chunk of text is wrapped independently from one another, and streamed to stdout
+(or an outFile, if given).  Command line arguments with -t/--text are processed
+before files.
+
+Arguments:
+  ...file                        files to wrap and concatenate.  Use "-" for
+                                 stdin. Default: "-"
+
+Options:
+  -7,--example7                  turn on the extra rules from Example 7 of UAX
+                                 #14
+  -c,--firstCol <value>          If outdentFirst is specified, how many columns
+                                 was the first line already indented?  If NaN,
+                                 use the indent width, in graphemes.  If
+                                 outdentFirst is false, this is ignored Default:
+                                 "NaN"
+  -e,--encoding <encoding>       encoding for files read or written.  stdout is
+                                 always in the default encoding. (choices:
+                                 "ascii", "utf8", "utf-8", "utf16le", "ucs2",
+                                 "ucs-2", "base64", "base64url", "latin1",
+                                 "binary", "hex") Default: "utf8"
+  --ellipsis <string>            What string to use when a word is longer than
+                                 the max width, and in overflow mode "clip"
+                                 Default: "…"
+  -h,--help                      display help for command
+  --html                         escape output for HTML
+  --hyphen <string>              What string to use when a word is longer than
+                                 the max width, and in overflow mode "any"
+                                 Default: "-"
+  -i,--indent <string|number>    indent each line with this text.  If a number,
+                                 indent that many spaces Default: ""
+  --indentChar <string>          if indent is a number, that many indentChars
+                                 will be inserted before each line Default: " "
+  --indentEmpty                  if the input string is empty, should we still
+                                 indent? Default: false
+  --isNewline <regex>            a regular expression to replace newlines in the
+                                 input.  Empty to leave newlines in place.
+                                 Default: "[^\\S\\r\\n\\v\\f\\x85\\u2028\
+                                 \u2029]*[\\r\\n\\v\\f\\x85\\u2028\\u2029]+\\s*"
+  -l,--locale <iso location>     locale for grapheme segmentation.  Has very
+                                 little effect at the moment
+  --newline <string>             how to separate the lines of output Default:
+                                 "\n"
+  --newlineReplacement <string>  when isNewline matches, replace with this
+                                 string Default: " "
+  -o,--outFile <file>            output to a file instead of stdout
+  --outdentFirst                 Do not indent the first output line Default:
+                                 false
+  --overflow <style>             what to do with words that are longer than
+                                 width. (choices: "visible", "clip",
+                                 "anywhere") Default: "visible"
+  -t,--text <value>              wrap this chunk of text.  If used, stdin is not
+                                 processed unless "-" is used explicitly.  Can
+                                 be specified multiple times. Default: []
+  -v,--verbose                   turn on super-verbose information.  Not useful
+                                 for anything but debugging underlying libraries
+  -w,--width <columns>           maximum line length Default: "(your terminal
+                                 width or 80)"
+```
+
+## Examples
+
+```sh
+linewrap -w 4 -t "foo bar"
+echo -n "foo bar" | linewrap -w 4
+linewrap -o outputFileName.txt -w 4 inputFileName.txt
+```
+
+---
+[![Tests](https://github.com/cto-af/linewrap-cli/actions/workflows/node.js.yml/badge.svg)](https://github.com/cto-af/linewrap-cli/actions/workflows/node.js.yml)
+[![codecov](https://codecov.io/gh/cto-af/linewrap-cli/branch/main/graph/badge.svg?token=D0hvqMS3Wx)](https://codecov.io/gh/cto-af/linewrap-cli)

package/bin/linewrap.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+import {inspect, promisify} from 'util'
+import {LineWrap} from '@cto.af/linewrap'
+import {fileURLToPath} from 'url'
+import fs from 'fs'
+import os from 'os'
+import {parseArgsWithHelp} from 'minus-h'
+
+/**
+ * @type {Parameters<generateHelp>[0]}
+ */
+const config = {
+  options: {
+    encoding: {
+      short: 'e',
+      type: 'string',
+      default: 'utf8',
+      argumentName: 'encoding',
+      description: 'encoding for files read or written.  stdout is always in the default encoding.',
+      choices: ['ascii', 'utf8', 'utf-8', 'utf16le', 'ucs2', 'ucs-2', 'base64', 'base64url', 'latin1', 'binary', 'hex'],
+    },
+    ellipsis: {
+      type: 'string',
+      default: LineWrap.DEFAULT_OPTIONS.ellipsis,
+      argumentName: 'string',
+      description: 'What string to use when a word is longer than the max width, and in overflow mode "clip"',
+    },
+    example7: {
+      short: '7',
+      type: 'boolean',
+      description: 'turn on the extra rules from Example 7 of UAX #14',
+    },
+    firstCol: {
+      short: 'c',
+      type: 'string',
+      default: 'NaN',
+      description: 'If outdentFirst is specified, how many columns was the first line already indented?  If NaN, use the indent width, in graphemes.  If outdentFirst is false, this is ignored',
+    },
+    html: {type: 'boolean', description: 'escape output for HTML'},
+    hyphen: {
+      type: 'string',
+      default: LineWrap.DEFAULT_OPTIONS.hyphen,
+      argumentName: 'string',
+      description: 'What string to use when a word is longer than the max width, and in overflow mode "any"',
+    },
+    indent: {
+      short: 'i',
+      type: 'string',
+      default: '',
+      argumentName: 'string|number',
+      description: 'indent each line with this text.  If a number, indent that many spaces',
+    },
+    indentChar: {
+      type: 'string',
+      default: LineWrap.DEFAULT_OPTIONS.indentChar,
+      argumentName: 'string',
+      description: 'if indent is a number, that many indentChars will be inserted before each line',
+    },
+    indentEmpty: {
+      type: 'boolean',
+      default: LineWrap.DEFAULT_OPTIONS.indentEmpty,
+      description: 'if the input string is empty, should we still indent?',
+    },
+    isNewline: {
+      type: 'string',
+      default: LineWrap.DEFAULT_OPTIONS.isNewline.source,
+      argumentName: 'regex',
+      description: 'a regular expression to replace newlines in the input.  Empty to leave newlines in place.',
+    },
+    locale: {
+      short: 'l',
+      type: 'string',
+      // This would make the tests depend on current locale:
+      // default: LineWrap.DEFAULT_OPTIONS.locale,
+      argumentName: 'iso location',
+      description: 'locale for grapheme segmentation.  Has very little effect at the moment',
+    },
+    newline: {
+      type: 'string',
+      default: os.EOL,
+      argumentName: 'string',
+      description: 'how to separate the lines of output',
+    },
+    newlineReplacement: {
+      type: 'string',
+      argumentName: 'string',
+      default: LineWrap.DEFAULT_OPTIONS.newlineReplacement,
+      description: 'when isNewline matches, replace with this string',
+    },
+    outdentFirst: {
+      type: 'boolean',
+      default: !LineWrap.DEFAULT_OPTIONS.indentFirst,
+      description: 'Do not indent the first output line',
+    },
+    outFile: {
+      short: 'o',
+      type: 'string',
+      argumentName: 'file',
+      description: 'output to a file instead of stdout',
+    },
+    overflow: {
+      type: 'string',
+      default: 'visible',
+      argumentName: 'style',
+      description: 'what to do with words that are longer than width.',
+      choices: ['visible', 'clip', 'anywhere'],
+    },
+    text: {
+      short: 't',
+      type: 'string',
+      multiple: true,
+      default: [],
+      description: 'wrap this chunk of text.  If used, stdin is not processed unless "-" is used explicitly.  Can be specified multiple times.',
+    },
+    verbose: {
+      short: 'v',
+      type: 'boolean',
+      description: 'turn on super-verbose information.  Not useful for anything but debugging underlying libraries',
+    },
+    width: {
+      short: 'w',
+      type: 'string',
+      default: String(process.stdout.columns ?? 80),
+      argumentName: 'columns',
+      description: 'maximum line length',
+    },
+  },
+  allowPositionals: true,
+  argumentName: '...file',
+  argumentDescription: 'files to wrap and concatenate.  Use "-" for stdin. Default: "-"',
+  description: 'Wrap some text, either from file, stdin, or given on the command line.  Each chunk of text is wrapped independently from one another, and streamed to stdout (or an outFile, if given).  Command line arguments with -t/--text are processed before files.',
+}
+
+/**
+ * Read stdin to completion with the configured encoding.
+ *
+ * @returns {Promise<string>}
+ */
+function readStdin(opts, stream) {
+  // Below, d will be a string
+  stream.setEncoding(opts.encoding)
+  return new Promise((resolve, reject) => {
+    let s = ''
+    stream.on('data', d => (s += d))
+    stream.on('end', () => resolve(s))
+    stream.on('error', reject)
+  })
+}
+
+const ESCAPES = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&apos;',
+  '\xA0': '&nbsp;',
+}
+
+/**
+ * Escape HTML
+ *
+ * @param {string} str String containing prohibited characters.
+ * @returns {string} Escaped string.
+ * @private
+ */
+function htmlEscape(str) {
+  return str.replace(/[&<>\xA0]/g, m => ESCAPES[m])
+}
+
+const {
+  exit, stdin, stdout, stderr,
+} = process
+
+export async function main(
+  extraConfig,
+  options,
+  process = {exit, stdin, stdout, stderr}
+) {
+  const {values, positionals} = parseArgsWithHelp({
+    ...config,
+    ...extraConfig,
+  }, {
+    width: config.options.width.default,
+    ...options,
+  })
+
+  if ((values.text.length === 0) && (positionals.length === 0)) {
+    positionals.push('-')
+  }
+
+  // Always a valid string, due to choices enforcement
+  /** @type synbol */
+  const overflow = {
+    visible: LineWrap.OVERFLOW_VISIBLE,
+    clip: LineWrap.OVERFLOW_CLIP,
+    anywhere: LineWrap.OVERFLOW_ANYWHERE,
+  }[values.overflow]
+
+  const outstream = values.outFile ?
+    fs.createWriteStream(values.outFile, values.encoding) :
+    process.stdout // Don't set encoding, will confuse terminal.
+
+  /** @type {ConstructorParameters<typeof LineWrap>[0]} */
+  const opts = {
+    escape: values.html ? htmlEscape : s => s,
+    ellipsis: values.ellipsis,
+    example7: Boolean(values.example7),
+    firstCol: parseInt(values.firstCol, 10),
+    hyphen: values.hyphen,
+    indent: parseInt(values.indent, 10) || values.indent,
+    indentChar: values.indentChar,
+    indentEmpty: values.indentEmpty,
+    indentFirst: !values.outdentFirst,
+    locale: values.locale,
+    newline: values.newline,
+    newlineReplacement: values.newlineReplacement,
+    overflow,
+    trim: !values.noTrim,
+    verbose: values.verbose,
+    width: parseInt(values.width, 10),
+  }
+  if (typeof values.isNewline === 'string') {
+    opts.isNewline = (values.isNewline.length === 0) ?
+      null :
+      new RegExp(values.isNewline, 'gu')
+  }
+  if (values.verbose) {
+    process.stdout.write(inspect(opts))
+  }
+  const w = new LineWrap(opts)
+
+  for (const t of values.text) {
+    outstream.write(w.wrap(t))
+    outstream.write(values.newline)
+  }
+
+  for (const f of positionals) {
+    const t = f === '-' ?
+      await readStdin(values, process.stdin) :
+      await fs.promises.readFile(f, values.encoding)
+
+    outstream.write(w.wrap(t))
+    outstream.write(values.newline)
+  }
+
+  // Be careful to wait for the file to close, to ensure tests run
+  // correctly.
+  await promisify(outstream.end.bind(outstream))()
+}
+
+if (fileURLToPath(import.meta.url) === process.argv[1]) {
+  main().catch(e => {
+    console.error(e)
+    process.exit(1)
+  })
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@cto.af/linewrap-cli",
+  "version": "1.0.0",
+  "description": "Wrap lines using the Unicode Line Breaking algorithm from UAX #14",
+  "type": "module",
+  "bin": {
+    "linewrap": "bin/linewrap.js"
+  },
+  "scripts": {
+    "test": "c8 mocha",
+    "lint": "eslint . --ext js,cjs",
+    "build": "npm run lint && npm run test && npm pack --dry-run"
+  },
+  "keywords": [
+    "uax14",
+    "word-wrap",
+    "wordwrap",
+    "linebreak",
+    "unicode",
+    "grapheme",
+    "cluster",
+    "cli",
+    "command-line"
+  ],
+  "author": "Joe Hildebrand <joe-github@cursive.net>",
+  "license": "MIT",
+  "repository": "cto-af/linewrap-cli",
+  "dependencies": {
+    "@cto.af/linewrap": "1.0.3",
+    "minus-h": "1.1.1"
+  },
+  "devDependencies": {
+    "@cto.af/eslint-config": "1.1.2",
+    "@types/node": "20.3.0",
+    "c8": "7.14.0",
+    "eslint": "8.42.0",
+    "mocha": "10.2.0"
+  },
+  "engines": {
+    "node": ">= 16"
+  }
+}