readme.md

snip-text

Snip and extract parts from text content. Useful for automatically testing and updating code snippets in your documentation. I created this simple tool to make sure my code examples are actually working. The package exports a simple function (snip) that finds specific 'snip marks' in text content and extracts named snippets to a javascript object.

Suppose you have a .js file that contains code examples for your documentation, embedded into unit tests:

examples.js

describe("Code examples", () => {
    describe("Feature 1", () => {
        it("example", () => {
            sinon.spy(console, "log");
            try {
                // --- snippet: snippet 1 ---
                var obj = myAwesomeFeature();
                console.log(obj.result);
                // Output:
                // expected output
                // --- snip ---
            } finally {
                console.log.restore();
            }
            assert(console.log.calledWith("expected output"));
        });    
    });        

    describe("Feature 2", () => {
        it("example", () => {

            // --- snippet: snippet 2 ---
            var obj = myOtherFeature("foo");
            // obj now contains property bar with value 'baz'
            // --- snip ---
            assert(obj.bar == 'baz');
        });    
    });     
});

When you pass the contents of this file (as a string) to snip, it will produce the following object:

{
	"snippet 1": "var obj = myAwesomeFeature();\nconsole.log(obj.result);\n// Output:\n// expected output",
	"snippet 2": "var obj = myOtherFeature(\"foo\");\n// obj now contains property bar with value 'baz'"
}

Now you can use a tool like gulp-template to insert the extracted code snippets into your documentation.

A snippet can consist of multiple parts. Snip marks in the content toggle snipping on/off for the last named snippet:

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
--- snippet: Lipsum ---
Maecenas suscipit risus tincidunt lectus pretium, vitae pellentesque eros malesuada.
Praesent eget libero sed massa blandit mattis ac et dolor.
--- snip ---
Phasellus eget velit non dui pharetra laoreet.
Etiam sodales velit vitae risus commodo, in sagittis velit gravida.
--- snip ---
Maecenas gravida orci id purus suscipit faucibus.

Passing this text to snip will produce an object with the Lipsum property containing the following text:

Maecenas suscipit risus tincidunt lectus pretium, vitae pellentesque eros malesuada.
Praesent eget libero sed massa blandit mattis ac et dolor.
Maecenas gravida orci id purus suscipit faucibus.

The function that recognises snip marks can be overriden. By default, snip looks for a line that starts with non-word characters, followed by at least 3 dashes, then followed by either the text 'snip' or the text 'snippet' or 'snippet:' followed by any string without dashes (the snippet name)

The following lines are all recognised as snip markers:

--- snip ---
-------snip
    // --- snip 
    /* ------- snippet: foo -------------*/

The following lines are not snip markers:

-- snip (at least 3 dashes required)
// don't --- snip this (alphanumeric characters before the dashes)
// snippet: foo ---- (no leading dashes)

If the first snip marker in the text content does not have a name specified, snip will use a single space (" ") as the snippet name.

Snip markers with a name always turn snipping on for the specified snippet, ie. snipping this text:

--- snippet: Lipsum
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Maecenas suscipit risus tincidunt lectus pretium, vitae pellentesque eros malesuada.
--- snippet: Lipsum
Praesent eget libero sed massa blandit mattis ac et dolor.
Phasellus eget velit non dui pharetra laoreet.
--- snip ---
Etiam sodales velit vitae risus commodo, in sagittis velit gravida.
Maecenas gravida orci id purus suscipit faucibus.

will produce a snippet called "Lipsum" with the following content:

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Maecenas suscipit risus tincidunt lectus pretium, vitae pellentesque eros malesuada.
Praesent eget libero sed massa blandit mattis ac et dolor.
Phasellus eget velit non dui pharetra laoreet.

For a complete example on how to use snip-text to automatically insert unit-tested code examples into your project documentation (using gulp), see my other project: SequentialTaskQueue, and have a look at gulpfile.js

Using the snip function

Pass the text contents as a string to snip:

var snippets = snip(text, options);

The optional options parameter is used to control some features of snip:

unindent

Type: boolean

Default: false

Removes leading white space from the snippets (used to produce the first example in this document).

tabSize

Type: number

Default: 4

Used with the unindent option, specifies the number of spaces that tab characters are translated to.

joiner

Type: string

Default: "\n"

Specifies the string with which the lines of the snippet will be joined.

matcher

Type: (line: string) => boolean | string

Replaces the default function for recognising snip markers. The function should return a thruthful value if the line is a snip marker. If the returned value is a string, it will be used as the snippet name.