0e9b061f / heretag

A heredoc implementation for JS, using template literals

heretag v1.1.8

A heredoc implementation using template literals.

Example

Consider phlebas.js:

// phlebas.js

const here = require('heretag')

const phlebas = here(`
            IV. Death by Water

    Phlebas the Phoenician, a fortnight dead,
    Forgot the cry of gulls, and the deep sea swell
    And the profit and loss.
                          A current under sea
    Picked his bones in whispers. As he rose and fell
    He passed the stages of his age and youth
    Entering the whirlpool.
                          Gentile or Jew
    O you who turn the wheel and look to windward,
    Consider Phlebas, who was once handsome and tall as you.
`)

console.log(phlebas)

Running this script will give the following result:

nn@Arkady:~$ node phlebas.js
        IV. Death by Water

Phlebas the Phoenician, a fortnight dead,
Forgot the cry of gulls, and the deep sea swell
And the profit and loss.
                      A current under sea
Picked his bones in whispers. As he rose and fell
He passed the stages of his age and youth
Entering the whirlpool.
                      Gentile or Jew
O you who turn the wheel and look to windward,
Consider Phlebas, who was once handsome and tall as you.

nn@Arkady:~$ ▮

Preserving Some Indentation

Suppose you want to preserve some level of indentation. To do so, specify a number as either the first or second argument to here. The given number of spaces will be preserved:

// preserve.js

const here = require('heretag')

const metasyntatic = here(4, `
            foo
              bar
                baz
              bat
            quz
`)

console.log(metasyntatic)

Four spaces of indentation will be preserved:

nn@Arkady:~$ node preserve.js
    foo
      bar
        baz
      bat
    quz

nn@Arkady:~$ ▮

Tagged Templates

here is also usable as a template tag:

here`
  foo
    bar
    baz
`

In this form, space can be preserved like this:

here(2)`
  foo
    bar
    baz
`

Newlines in Interpolated Variables

Most importantly, the tagged form of here handles newlines in interpolated variables gracefully. For example:

// inter-a.js

const here = require('heretag')

const example = "a\n  b\nc\n"
const inter = here`
  foo
    bar
    ${example}
  baz
`
console.log(inter)

Will produce:

nn@Arkady:~$ node inter-a.js
foo
  bar
  a
    b
  c
bat

nn@Arkady:~$ ▮

Conversely, with the standard form of here:

// inter-b.js

const here = require('heretag')

const example = "a\n  b\nc\n"
const inter = here(`
  foo
    bar
    ${example}
  baz
`)
console.log(inter)

Will produce mangled output:

nn@Arkady:~$ node inter-b.js
foo
  bar
  a
  b
c
bat

nn@Arkady:~$ ▮

Installation

npm install heretag

License

Copyright 2020-2024 0E9B061F
Available under the terms of the MIT License.