gfm-escape - npm Package Compare versions

Comparing version 0.0.1 to 0.1.0

package.json

 {
   "name": "gfm-escape",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Markdown and GFM escaper for converting plaintext into escaped Markdown",
@@ -21,3 +21,3 @@ "main": "dist/gfm-escape.cjs.js",
   "dependencies": {
-    "union-replacer": "^1.1.0"
+    "union-replacer": "^1.2.0"
   },
@@ -24,0 +24,0 @@ "devDependencies": {

README.md

@@ -53,3 +53,3 @@ # GfmEscape
 escaper = new GfmEscape(escapingOptions[, syntax])
-newStr = escaper.escape(str[, gfmContext[, metadata]])
+newStr = escaper.escape(input[, gfmContext[, metadata]])
 ```
@@ -77,8 +77,13 @@
      allowedTransformations: [ 'entities', 'commonmark' ],
-     allowAddHttpScheme: false
+     allowAddHttpScheme: false,
+     inImage: false,
   },
   table: true, // default false
   emphasisNonDelimiters: { // default true
-    maxIntrawordUnderscoreRun: false
+    maxIntrawordUnderscoreRun: false,
   },
+  linkTitle: { // default true
+    delimiters: [ '"', '\'', '()' ],
+    alwaysEscapeDelimiters: [],
+  },
 }
@@ -95,12 +100,25 @@ ```
   CommonMark autolink is an appropriate construct to use, we suggest to use
-  the `isEncodable(str)` and `wouldBeUnaltered(str)` methods on the
+  the `isEncodable(input)` and `wouldBeUnaltered(input)` methods on the
   `Syntax.cmAutolink` object.
 - `codeSpan`: text rendered `` `here` ``.
+- `linkTitle`: text rendered `[text](destination "here")` or
+  `[text](destination 'here')` or `[text](destination (here))`.
 
-When escaping, `gfmContext` is extra contextual information to be considered.
-The contexts have no defaults, i.e. they are falsy by default.
-The following contexts are available:
+`input`: the string to escape. Please note that correct escaping is currently
+only guaranteed when the input is trimmed and normalized in terms of whitespace.
+The library does not perfos qrm whitespace normalizing on its own, as it is often
+ensured by the source's origin, e.g. `textContent` of a normalized HTML DOM.
+Manual normalizing can be done with `input.trim().replace(/[ \t\n\r]+/g, ' ')`.
+If it is intended to keep the source somewhat organized in lines, the minimum
+treatment to make escaping safe would be `input.replace(/^[ \t\r\n]+|[ \t]+$/gm, '')`.
+In such case, the caller has a responsibility to place the output correctly in
+the generated document. I.e. to indent all the lines when the context requires
+indenting.
+
+`gfmContext`: extra contextual information to be considered. The contexts have
+no defaults, i.e. they are falsy by default. The following contexts are available:
 ```js
 {
   inLink: true, // indicates suppressing nested links
+  inImage: true, // similar to inLink for ![this image text](img.png)
   inTable: true, // indicates extra escaping of table contents
@@ -111,10 +129,31 @@ }
 metadata about the actual escaping. Currently `metadata` are used for
-`codeSpan` syntax, where two output parameters `delimiter` and `space` are passed:
+`codeSpan` syntax and `linkTitle` syntax.
 ```js
 const escaper = new GfmEscape({ table: true }, GfmEscape.Syntax.codeSpan);
-const x = {};
+const x = {}; // not necessary as the surrounding delimiter is always '`'
 const context = { inTable: true };
-const output = escaper.escape('`array|string`', context, x);
-console.log(`${x.delimiter}${x.space}${output}${x.space}${x.delimiter}`);
-// `` `array\|string` ``
+const escaped = escaper.escape('`array|string`', context, x);
+console.log(`\`${escaped}\``); // `` `array\|string` ``
+console.log(`${x.extraBacktickString.length} backtickts and ${x.extraSpace.length} spaces added.`);
+// 1 backticks and 1 spaces added.
+
+const linkTitleEscaper = new GfmEscape({}, GfmEscape.Syntax.linkTitle);
+const x = {}; // needed as we let GfmEscape decide the surrounding delimiter
+let escaped = escaper.escape('cool "link \'title\'"', context, x);
+console.log(`${x.startDelimiter}${escaped}${x.endDelimiter}`);
+// (cool "link 'title'")
+
+escaped = escaper.escape('average link title', context, x);
+console.log(`${x.startDelimiter}${escaped}${x.endDelimiter}`);
+// "average link title"
+
+const rigidLinkTitleEscaper = new GfmEscape({
+  linkTitle: {
+    delimiters: '"',
+  }
+}, GfmEscape.Syntax.linkTitle);
+// metadata not necessary, as the surronding delimiter will be always '"'
+escaped = escaper.escape('cool "link \'title\'"');
+console.log(`"${escaped}"`);
+// "cool \"link 'title'\""
 ```
@@ -164,2 +203,6 @@
   with the `commonmark` transformation.
+- `inImage`: suggest if extended autolink treatment should be applied within
+  image text. Although the CommonMark spec says links are interpreted and just
+  the stripped plain text part renders to the `alt` attribute, cmark-gfm actually
+  does not do it for extended autolinks, so the default is false.
 
@@ -193,3 +236,3 @@ _How to choose the options_:
 Suboptions:
-* `maxIntrawordUnderscoreRun`: if defined, it sets the maximum length of intraword
+- `maxIntrawordUnderscoreRun`: if defined, it sets the maximum length of intraword
   underscores to be kept as is. E.g. for `1` and input `joe_average or joe__average`,
@@ -205,2 +248,12 @@ the output would be `joe_average or joe\_\_average`. This is helpful for some renderers
 
+#### Escaping options: `linkTitle`
+
+Suboptions:
+- `delimiters`: array of allowed delimiter to be chosen from or a single delimiter.
+  Delimiters are `"`, `'` and `()`. When more delimiters are allowed, GfmEscape picks
+  the least interferring one. The picked delimiter is returned in metadata, as shown
+  in the example above.
+- `alwaysEscapeDelimiters`: array of delimiters that are always escaped.
+
+
 ## GFM escaping details
@@ -234,3 +287,3 @@
   can only come at the beginning of a line, after whitespace, or any of the
-  delimiting characters *, _, ~, and (_, it seems this applies just to extended
+  delimiting characters \*, \_, \~, and (_, it seems this applies just to extended
   www autolinks in cmark-gfm. E.g. `.https://orchi.tech` is recognized as an
@@ -256,2 +309,3 @@ autolink by this library. We follow this.
   from interpreting in rendered HTML. We use entity encoding instead, i.e. `&`.
+  The same applies to link titles.
 
@@ -258,0 +312,0 @@ ## TODO

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

237431

increased by6.84%

Lines of code

4789

increased by9.31%

Number of lines in readme file

307

increased by21.34%

Dependency changes

• Updatedunion-replacer@^1.2.0