content-tag-utils

Utilities for writing tools that work with content-tag and converting bytes-indexes to character-indexes.

Aimed at sharing logic between:

- eslint w/ ember-eslint-parser
- prettier w/ prettier-plugin-ember-template-tag
- ember-template-lint

> [!NOTE]
> This utility is meant for local tooling and not the browser, or transforming runtime code. No sourcemaps are involved. (Sourcemaps should be used when transforming code meant for runtime).

Install

``bash
npm add content-tag-utils
`

Using from source / github, via package.json:

`js
{
"dependencies": {
"content-tag-utils": "github:NullVoxPopuli/content-tag-utils"
}
}
`

Usage

`js
import {
transform,
transformSync,
coordinatesOf,
Transformer,
} from "content-tag-utils";
`

and

`js
import { unprocess } from 'content-tag-utils/unprocess';
`

$3

A general utility for working with content-tag, keeping tracked of each template as you apply transformations.
Transformations are recorded and then applied later when calling .toString().

For example:

`js
import { Transformer } from "content-tag-utils";

let file =
export const Foo =
;

let t = new Transformer(file);

// apply some transformations, with their coordinates
await t.asyncMap((contents, coordinates => {
/ ... /
return 'new content';
});
t.map((contents, coordinates) => {
/ ... /
return 'new content 2';
});

// iterate over the templates, with their coordinates
await t.asyncEach((contents, coordinates => {
/ ... /
});
t.each((contents, coordinates) => {
/ ... /
});

// get the output
t.toString();

// can also do more transformations and get the output again later
await t.transform(/ ... / )
t.toString();
`

Properties / Methods:

- t.toString() returns a string of the original file with all applied transforms
- t.toString({ placeholders: true }) returns a string of original file, but as valid JS with placeholder markers - also applies transforms if anyone were done.
- t.parseResults output from content-tag , but frozen / read-only - these are used as keys for other methods
- t.map()
- t.each()
- t.asyncMap()
- t.asyncEach()
- t.transformOneSync()
- t.transformOne()
- t.reverseInnerCoordinatesOf() Given in-template coordinates, returns the coordinates in the context of the file
- t.stringUtils Collection of utilities for working with parseResults
- t.stringUtils.contentBefore(parseResult) return the string contents before the passed parse result, before the opening ):

`gjs
export const Foo =
`

$3

For a given source document (gjs or gts), and a single parseResult (one of the entries from the array returned from content-tag's parse), what is the line/column number of the first character for that parseResult, and the columnOffset (useful for extracting templates to do work on and then put back, or giving pointers to errors present in the template).

`js
import { coordinatesOf } from "content-tag-utils";
import { Preprocessor } from "content-tag";

let p = new Preprocessor();

let file =
export const Foo =
;

let parsed = p.parse(file);

let result = coordinatesOf(file, parsed[0]);
`

result (all values are character-indexes):

`gjs
{
line: 2,
column: 29,
columnOffset: 0,

start: 30,
end: 47,
}
`

$3

Given inner coordinates scoped to a template, this function returns the coordinates in the overall source file.

`js
import { reverseInnerCoordinates } from 'content-tag-utils';

let file =
export const Foo =
;
// e.g.: a lint result
let innerCoordinates = {
line: 2,
column: 4,
endColumn: 5,
endLine: 2,
// extraneous, but may be present in your tool
error: 'no capital letters!',
};

const templateInfos = extractTemplates(file);
const result = reverseInnerCoordinates(templateInfos[0]!, innerCoordinates);
`

result:

`gjs
{
column: 4,
endColumn: 5,
endLine: 3,
line: 3,
}
`

$3

Converts a js or ts file that used to be gjs or gts back to gjs or gts.


`js
import { unprocess } from 'content-tag-utils/unprocess';

let file =
import { template as template_fd9b2463e5f141cfb5666b64daa1f11a } from "@ember/template-compiler";
import type { TOC } from '@ember/component/template-only';
export default template_fd9b2463e5f141cfb5666b64daa1f11a(\hi there\, {
eval () {
return eval(arguments[0]);
}
}) satisfies TOC<{
}>;
;

let result = unprocess(file);
`

result:

`gjs
export default ;
``