Merge pull request #374 from stasm/fluent-dedent

Add the fluent-dedent package

Author: stasm

fluent-dedent/.esdoc.json

@@ -0,0 +1,16 @@
+{
+    "source": "./src",
+    "destination": "../html/dedent",
+    "plugins": [
+        {
+            "name": "esdoc-standard-plugin"
+        },
+        {
+            "name": "esdoc-ecmascript-proposal-plugin",
+            "option": {
+                "objectRestSpread": true,
+                "asyncGenerators": true
+            }
+        }
+    ]
+}

fluent-dedent/.gitignore

@@ -0,0 +1,2 @@
+/index.js
+/compat.js

fluent-dedent/.npmignore

@@ -0,0 +1,5 @@
+.nyc_output
+coverage
+docs
+test
+makefile

fluent-dedent/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## Unreleased
+
+This is the first release of `@fluent/dedent` as an independent package. It's
+based on the `ftl` template tag from the `fluent` package, but the behavior
+has changed and the code has been refactored.
+
+The behavior in this version is largely based on the [multiline strings
+specification in Swift][1]. See the `README.md` for more details.
+
+[1]: https://docs.swift.org/swift-book/LanguageGuide/StringsAndCharacters.html

fluent-dedent/README.md

@@ -0,0 +1,98 @@
+# @fluent/dedent
+
+`@fluent/dedent` provides a template literal tag to dedent Fluent code.
+Fluent Syntax is indentation-sensitive, and `@fluent/dedent` offers a
+convenient way to include Fluent snippets in source code keeping the current
+level of indentation and without compromising the readability.
+
+
+## Installation
+
+`@fluent/dedent` can be used both on the client-side and the server-side.  You can
+install it from the npm registry or use it as a standalone script (as the
+`FluentDedent` global).
+
+    npm install @fluent/dedent
+
+
+## How to use
+
+`@fluent/dedent`'s default export is meant to be used as a template literal
+tag. By convention, the tag is often called `ftl`.
+
+```javascript
+import ftl from "@fluent/dedent";
+
+let messages = ftl`
+    hello = Hello, world!
+    welcome = Welcome, {$userName}!
+    `;
+```
+
+The position of the closing backtick defines how much indent will be removed
+from each line of the content. If the indentation is not sufficient in any of
+the non-blank lines of the content, a `RangeError` is thrown.
+
+```javascript
+import ftl from "@fluent/dedent";
+
+let messages = ftl`
+    hello = Hello, world!
+  welcome = Welcome, {$userName}!
+    `;
+
+// → RangeError("Insufficient indentation in line 2.")
+```
+
+Content must start on a new line and must end on a line of its own. The
+closing delimiter must appear on a new line. The first and the last line of
+the input will be removed from the output. If any of them contains
+non-whitespace characters, a `RangeError` is thrown.
+
+```javascript
+import ftl from "@fluent/dedent";
+
+let message1 = "hello = Hello, world!";
+let message2 = ftl`
+    hello = Hello, world!
+    `;
+
+assert(message1 === message2);
+```
+
+If you wish to include the leading or trailing line breaks in the output, put
+extra blank lines in the input.
+
+```javascript
+import ftl from "@fluent/dedent";
+
+let message = ftl`
+
+    hello = Hello, world!
+
+    `;
+
+assert(message === "\nhello = Hello, world!\n");
+```
+
+
+## Compatibility
+
+For legacy browsers, the `compat` build has been transpiled using Babel's [env
+preset][].
+
+```javascript
+import ftl from '@fluent/dedent/compat';
+```
+
+
+## Learn more
+
+Find out more about Project Fluent at [projectfluent.org][], including
+documentation of the Fluent file format ([FTL][]), links to other packages and
+implementations, and information about how to get involved.
+
+
+[env preset]: https://babeljs.io/docs/plugins/preset-env/
+[projectfluent.org]: http://projectfluent.org
+[FTL]: http://projectfluent.org/fluent/guide/

fluent-dedent/makefile

@@ -0,0 +1,29 @@
+PACKAGE := @fluent/dedent
+GLOBAL  := FluentDedent
+
+include ../common.mk
+
+build: index.js compat.js
+
+index.js: $(SOURCES)
+	@rollup $(CURDIR)/src/index.js \
+	    --config $(ROOT)/bundle_config.js \
+	    --banner "/* $(PACKAGE)@$(VERSION) */" \
+	    --amd.id $(PACKAGE) \
+	    --name $(GLOBAL) \
+	    --output.file $@
+	@echo -e " $(OK) $@ built"
+
+compat.js: $(SOURCES)
+	@rollup $(CURDIR)/src/index.js \
+	    --config $(ROOT)/compat_config.js \
+	    --banner "/* $(PACKAGE)@$(VERSION) */" \
+	    --amd.id $(PACKAGE) \
+	    --name $(GLOBAL) \
+	    --output.file $@
+	@echo -e " $(OK) $@ built"
+
+clean:
+	@rm -f $(PACKAGE).js compat.js
+	@rm -rf .nyc_output coverage
+	@echo -e " $(OK) clean"

fluent-dedent/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@fluent/dedent",
+  "description": "A template literal tag for dedenting Fluent code",
+  "version": "0.1.0",
+  "homepage": "https://projectfluent.org",
+  "author": "Mozilla <[email protected]>",
+  "license": "Apache-2.0",
+  "contributors": [
+    {
+      "name": "Staś Małolepszy",
+      "email": "[email protected]"
+    }
+  ],
+  "directories": {
+    "lib": "./src"
+  },
+  "main": "./index.js",
+  "module": "./src/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/projectfluent/fluent.js.git"
+  },
+  "keywords": [
+    "dedent",
+    "fluent",
+    "ftl"
+  ],
+  "engines": {
+    "node": ">=8.9.0"
+  }
+}

fluent-dedent/src/index.js

@@ -0,0 +1,45 @@
+// A blank line may contain spaces and tabs.
+const RE_BLANK = /^[ \t]*$/;
+
+/**
+ * Template literal tag for dedenting Fluent code.
+ *
+ * Strip the indent of the last line from each line of the input. Remove the
+ * first and the last line from the output. The snippet must start on a new
+ * line and it must end on a line of its own, with the closing delimiter on a
+ * next line.
+ *
+ * @param {Array<string>} strings
+ * @param {...any} values
+ * @returns string
+ */
+export default function ftl(strings, ...values) {
+  let code = strings.reduce((acc, cur) => acc + values.shift() + cur);
+  let lines = code.split("\n");
+  let [first, commonIndent] = [lines.shift(), lines.pop()];
+
+  if (!RE_BLANK.test(first)) {
+    throw new RangeError("Content must start on a new line.");
+  }
+  if (!RE_BLANK.test(commonIndent)) {
+    throw new RangeError("Closing delimiter must appear on a new line.");
+  }
+
+  function dedent(line, idx) {
+    let lineIndent = line.slice(0, commonIndent.length);
+    if (lineIndent.length === 0) {
+      // Empty blank lines are preserved even if technically they are not
+      // indented at all. This also short-circuits the dedentation logic when
+      // commonIndent.length is 0, i.e. when all indents should be kept.
+      return line;
+    }
+    if (lineIndent !== commonIndent) {
+      // The indentation of the line must match commonIndent exacty.
+      throw new RangeError(`Insufficient indentation in line ${idx + 1}.`);
+    }
+    // Strip commonIndent.
+    return line.slice(commonIndent.length);
+  }
+
+  return lines.map(dedent).join("\n");
+}

fluent-dedent/test/blank_test.js

@@ -0,0 +1,64 @@
+"use strict";
+
+import assert from "assert";
+import ftl from "../src/index";
+
+suite("blank lines", function() {
+  test("leading", function() {
+    assert.equal(
+      ftl`
+
+        foo
+        `,
+      "\nfoo"
+    );
+  });
+
+  test("middle", function() {
+    assert.equal(
+      ftl`
+        foo
+
+        bar
+        `,
+      "foo\n\nbar"
+    );
+  });
+
+  test("trailing", function() {
+    assert.equal(
+      ftl`
+        foo
+
+        `,
+      "foo\n"
+    );
+  });
+
+  test("containing the same amount of spaces as the common indent", function() {
+    assert.equal(
+      ftl`
+      
+      `,
+      ""
+    );
+  });
+
+  test("containing too few spaces", function() {
+    assert.throws(
+      () => ftl`
+  
+      `,
+      /Insufficient indentation in line 1/
+    );
+  });
+
+  test("containing too many spaces", function() {
+    assert.equal(
+      ftl`
+        
+      `,
+      "  "
+    );
+  });
+});

fluent-dedent/test/content_test.js

@@ -0,0 +1,56 @@
+"use strict";
+
+import assert from "assert";
+import ftl from "../src/index";
+
+suite("content lines", function() {
+  test("no indent", function () {
+    assert.equal(
+      ftl`
+foo
+bar
+`,
+      "foo\nbar"
+    );
+  });
+
+  test("zero indent", function () {
+    assert.equal(
+      ftl`
+        foo
+    bar
+`,
+      "        foo\n    bar"
+    );
+  });
+
+  test("small indent", function () {
+    assert.equal(
+      ftl`
+        foo
+    bar
+    `,
+      "    foo\nbar"
+    );
+  });
+
+  test("same indent", function () {
+    assert.equal(
+      ftl`
+        foo
+        bar
+        `,
+      "foo\nbar"
+    );
+  });
+
+  test("larger indent", function () {
+    assert.throws(
+      () => ftl`
+          foo
+        bar
+          `,
+      /Insufficient indentation in line 2/
+    );
+  });
+});