update docs and examples with transforms

README.md

@@ -98,7 +98,7 @@ The result is an array of Block objects, see the full output on the [playground]
     description: 'the name parameter',
     // problems occured while parsing this tag section, subset of ../problems array
     problems: [],
-    // source lines processed for extracting this tag, subset of ../source array
+    // source lines processed for extracting this tag, "slice" of the ../source item reference
     source: [ ... ],
   }, ... ],
   // source is an array of `Line` items having the source
@@ -167,10 +167,10 @@ examples
 
 ## Stringifier
 
-The stringifier is an important piece used by other tools updating the source code. Basically, it assembles tokens back into lines using the provided formatter. Stringifier is using only `Block.source` field and doesn't care about the rest. Available formatters are `"none"` (default) and `"align"`. Also, you can provide your custom [Formatter](src/stringifier.ts) having completely different logic
+The stringifier is an important piece used by other tools updating the source code. It goes over `Block.source[].tokens` and assembles them back to a string. It might be used with various transforms applied to the parsed data before strngifying.
 
 ```js
-const { parse, stringify } = require('../../lib/');
+const { parse, stringify, transforms: {flow, align, indent} } = require('./lib/');
 
 const source = `
   /**
@@ -183,30 +183,21 @@ const source = `
    */`;
 
 const parsed = parse(source);
-
-console.log(stringify(parsed[0], { format: 'align' }));
+const transform = flow(align(), indent(0))
+console.log(stringify(transform(parsed[0])));
 ```
 
 ### Result
 
 ```
-  /**
-   * Description may go
-   * over multiple lines followed by @tags
-   *
-   * @my-tag {my.type} my-name description line 1
-                               description line 2
-   *                           description line 3
-   */
-```
-
-### options
-
-```ts
-interface Options {
-  // formatting strategy, see Formatter
-  format: 'none' | 'align' | Formatter;
-}
+/**
+ * Description may go
+ * over multiple lines followed by @tags
+ *
+ * @my-tag {my.type} my-name description line 1
+                             description line 2
+ *                           description line 3
+ */
 ```
 
 examples

src/index.ts

@@ -7,3 +7,5 @@ export function parse(source: string, options: Partial<ParserOptions> = {}) {
 }
 
 export const stringify = getStringifier();
+
+export * as transforms from './transforms/index';

tests/e2e/examples.js

@@ -1,7 +1,7 @@
 // This file is a source for playground examples.
 // Examples integrity is smoke-checked with examples.spec.js
 
-function parse_defaults(source, parse, stringify) {
+function parse_defaults(source, parse, stringify, transforms) {
   // Invoking parser with default config covers the most genearic cases.
   // Note how /*** and /* blocks are ignored
 
@@ -23,7 +23,7 @@ function parse_defaults(source, parse, stringify) {
   const stringified = parsed.map((block) => stringify(block));
 }
 
-function parse_line_numbering(source, parse, stringify) {
+function parse_line_numbering(source, parse, stringify, transforms) {
   // Note, line numbers are off by 5 from what you see in editor
   //
   // Try changeing start line back to 0, or omit the option
@@ -43,7 +43,7 @@ function parse_line_numbering(source, parse, stringify) {
     .join('\n');
 }
 
-function parse_spacing(source, parse, stringify) {
+function parse_spacing(source, parse, stringify, transforms) {
   // Note, when spacing option is set to 'compact' or omited, tag and block descriptions are collapsed to look like a single sentense.
   //
   // Try changeing it to 'preserve' or defining custom function
@@ -68,7 +68,7 @@ function parse_spacing(source, parse, stringify) {
     .join('\n');
 }
 
-function parse_escaping(source, parse, stringify) {
+function parse_escaping(source, parse, stringify, transforms) {
   // Note, @decorator is not parsed as another tag because block is wrapped into ###.
   //
   // Try setting alternative escape sequence
@@ -91,10 +91,10 @@ function parse_escaping(source, parse, stringify) {
     .join('\n');
 }
 
-function stringify_formatting(source, parse, stringify) {
-  // stringify preserves exact formatting be default, see how behavior is changes with:
-  // stringify(parsed[0], {format: 'none'}) -- default
-  // stringify(parsed[0], {format: 'align'}) -- align name, type, and description
+function stringify_formatting(source, parse, stringify, transforms) {
+  // stringify preserves exact formatting by default, but you can transform parsing result first
+  // transform = align() -- align name, type, and description
+  // transform = flow(align(), indent(4)) -- align, then place the block's opening marker at pos 4
 
   /**
    * Description may go
@@ -103,8 +103,11 @@ function stringify_formatting(source, parse, stringify) {
    * @param {any} value the value parameter
    */
 
+  const { flow, align, indent } = transforms;
+  const transform = flow(align(), indent(4));
+
   const parsed = parse(source);
-  const stringified = stringify(parsed[0], { format: 'align' });
+  const stringified = stringify(transform(parsed[0]));
 }
 
 (typeof window === 'undefined' ? module.exports : window).examples = [

tests/e2e/examples.spec.js

@@ -1,9 +1,9 @@
-const { parse, stringify } = require('../../lib');
+const { parse, stringify, transforms } = require('../../lib');
 const { examples } = require('./examples');
 
 const table = examples.map((fn) => [fn.name.replace(/_/g, ' '), fn]);
 
 test.each(table)('example - %s', (name, fn) => {
   const source = fn.toString();
-  expect(() => fn(source, parse, stringify)).not.toThrow();
+  expect(() => fn(source, parse, stringify, transforms)).not.toThrow();
 });