packages/html-to-text/src/text-formatters.js
import { get, numberToLetterSequence, numberToRoman, trimCharacter, trimCharacterEnd } from '@html-to-text/base/src/util';
import { tableToString } from './table-printer';
// eslint-disable-next-line import/no-unassigned-import
import '@html-to-text/base/src/typedefs';
/**
* Process a line-break.
*
* @type { FormatCallback }
*/
function formatLineBreak (elem, walk, builder, formatOptions) {
builder.addLineBreak();
}
/**
* Process a `wbr` tag (word break opportunity).
*
* @type { FormatCallback }
*/
function formatWbr (elem, walk, builder, formatOptions) {
builder.addWordBreakOpportunity();
}
/**
* Process a horizontal line.
*
* @type { FormatCallback }
*/
function formatHorizontalLine (elem, walk, builder, formatOptions) {
builder.openBlock({ leadingLineBreaks: formatOptions.leadingLineBreaks || 2 });
builder.addInline('-'.repeat(formatOptions.length || builder.options.wordwrap || 40));
builder.closeBlock({ trailingLineBreaks: formatOptions.trailingLineBreaks || 2 });
}
/**
* Process a paragraph.
*
* @type { FormatCallback }
*/
function formatParagraph (elem, walk, builder, formatOptions) {
builder.openBlock({ leadingLineBreaks: formatOptions.leadingLineBreaks || 2 });
walk(elem.children, builder);
builder.closeBlock({ trailingLineBreaks: formatOptions.trailingLineBreaks || 2 });
}
/**
* Process a preformatted content.
*
* @type { FormatCallback }
*/
function formatPre (elem, walk, builder, formatOptions) {
builder.openBlock({
isPre: true,
leadingLineBreaks: formatOptions.leadingLineBreaks || 2
});
walk(elem.children, builder);
builder.closeBlock({ trailingLineBreaks: formatOptions.trailingLineBreaks || 2 });
}
/**
* Process a heading.
*
* @type { FormatCallback }
*/
function formatHeading (elem, walk, builder, formatOptions) {
builder.openBlock({ leadingLineBreaks: formatOptions.leadingLineBreaks || 2 });
if (formatOptions.uppercase !== false) {
builder.pushWordTransform(str => str.toUpperCase());
walk(elem.children, builder);
builder.popWordTransform();
} else {
walk(elem.children, builder);
}
builder.closeBlock({ trailingLineBreaks: formatOptions.trailingLineBreaks || 2 });
}
/**
* Process a blockquote.
*
* @type { FormatCallback }
*/
function formatBlockquote (elem, walk, builder, formatOptions) {
builder.openBlock({
leadingLineBreaks: formatOptions.leadingLineBreaks || 2,
reservedLineLength: 2
});
walk(elem.children, builder);
builder.closeBlock({
trailingLineBreaks: formatOptions.trailingLineBreaks || 2,
blockTransform: str => ((formatOptions.trimEmptyLines !== false) ? trimCharacter(str, '\n') : str)
.split('\n')
.map(line => '> ' + line)
.join('\n')
});
}
function withBrackets (str, brackets) {
if (!brackets) { return str; }
const lbr = (typeof brackets[0] === 'string')
? brackets[0]
: '[';
const rbr = (typeof brackets[1] === 'string')
? brackets[1]
: ']';
return lbr + str + rbr;
}
function pathRewrite (path, rewriter, baseUrl, metadata, elem) {
const modifiedPath = (typeof rewriter === 'function')
? rewriter(path, metadata, elem)
: path;
return (modifiedPath[0] === '/' && baseUrl)
? trimCharacterEnd(baseUrl, '/') + modifiedPath
: modifiedPath;
}
/**
* Process an image.
*
* @type { FormatCallback }
*/
function formatImage (elem, walk, builder, formatOptions) {
const attribs = elem.attribs || {};
const alt = (attribs.alt)
? attribs.alt
: '';
const src = (!attribs.src)
? ''
: pathRewrite(attribs.src, formatOptions.pathRewrite, formatOptions.baseUrl, builder.metadata, elem);
const text = (!src)
? alt
: (!alt)
? withBrackets(src, formatOptions.linkBrackets)
: alt + ' ' + withBrackets(src, formatOptions.linkBrackets);
builder.addInline(text, { noWordTransform: true });
}
/**
* Process an anchor.
*
* @type { FormatCallback }
*/
function formatAnchor (elem, walk, builder, formatOptions) {
function getHref () {
if (formatOptions.ignoreHref) { return ''; }
if (!elem.attribs || !elem.attribs.href) { return ''; }
let href = elem.attribs.href.replace(/^mailto:/, '');
if (formatOptions.noAnchorUrl && href[0] === '#') { return ''; }
href = pathRewrite(href, formatOptions.pathRewrite, formatOptions.baseUrl, builder.metadata, elem);
return href;
}
const href = getHref();
if (!href) {
walk(elem.children, builder);
} else {
let text = '';
builder.pushWordTransform(
str => {
if (str) { text += str; }
return str;
}
);
walk(elem.children, builder);
builder.popWordTransform();
const hideSameLink = formatOptions.hideLinkHrefIfSameAsText && href === text;
if (!hideSameLink) {
builder.addInline(
(!text)
? href
: ' ' + withBrackets(href, formatOptions.linkBrackets),
{ noWordTransform: true }
);
}
}
}
/**
* @param { DomNode } elem List items with their prefixes.
* @param { RecursiveCallback } walk Recursive callback to process child nodes.
* @param { BlockTextBuilder } builder Passed around to accumulate output text.
* @param { FormatOptions } formatOptions Options specific to a formatter.
* @param { () => string } nextPrefixCallback Function that returns increasing index each time it is called.
*/
function formatList (elem, walk, builder, formatOptions, nextPrefixCallback) {
const isNestedList = get(elem, ['parent', 'name']) === 'li';
// With Roman numbers, index length is not as straightforward as with Arabic numbers or letters,
// so the dumb length comparison is the most robust way to get the correct value.
let maxPrefixLength = 0;
const listItems = (elem.children || [])
// it might be more accurate to check only for html spaces here, but no significant benefit
.filter(child => child.type !== 'text' || !/^\s*$/.test(child.data))
.map(function (child) {
if (child.name !== 'li') {
return { node: child, prefix: '' };
}
const prefix = (isNestedList)
? nextPrefixCallback().trimStart()
: nextPrefixCallback();
if (prefix.length > maxPrefixLength) { maxPrefixLength = prefix.length; }
return { node: child, prefix: prefix };
});
if (!listItems.length) { return; }
builder.openList({
interRowLineBreaks: 1,
leadingLineBreaks: isNestedList ? 1 : (formatOptions.leadingLineBreaks || 2),
maxPrefixLength: maxPrefixLength,
prefixAlign: 'left'
});
for (const { node, prefix } of listItems) {
builder.openListItem({ prefix: prefix });
walk([node], builder);
builder.closeListItem();
}
builder.closeList({ trailingLineBreaks: isNestedList ? 1 : (formatOptions.trailingLineBreaks || 2) });
}
/**
* Process an unordered list.
*
* @type { FormatCallback }
*/
function formatUnorderedList (elem, walk, builder, formatOptions) {
const prefix = formatOptions.itemPrefix || ' * ';
return formatList(elem, walk, builder, formatOptions, () => prefix);
}
/**
* Process an ordered list.
*
* @type { FormatCallback }
*/
function formatOrderedList (elem, walk, builder, formatOptions) {
let nextIndex = Number(elem.attribs.start || '1');
const indexFunction = getOrderedListIndexFunction(elem.attribs.type);
const nextPrefixCallback = () => ' ' + indexFunction(nextIndex++) + '. ';
return formatList(elem, walk, builder, formatOptions, nextPrefixCallback);
}
/**
* Return a function that can be used to generate index markers of a specified format.
*
* @param { string } [olType='1'] Marker type.
* @returns { (i: number) => string }
*/
function getOrderedListIndexFunction (olType = '1') {
switch (olType) {
case 'a': return (i) => numberToLetterSequence(i, 'a');
case 'A': return (i) => numberToLetterSequence(i, 'A');
case 'i': return (i) => numberToRoman(i).toLowerCase();
case 'I': return (i) => numberToRoman(i);
case '1':
default: return (i) => (i).toString();
}
}
/**
* Given a list of class and ID selectors (prefixed with '.' and '#'),
* return them as separate lists of names without prefixes.
*
* @param { string[] } selectors Class and ID selectors (`[".class", "#id"]` etc).
* @returns { { classes: string[], ids: string[] } }
*/
function splitClassesAndIds (selectors) {
const classes = [];
const ids = [];
for (const selector of selectors) {
if (selector.startsWith('.')) {
classes.push(selector.substring(1));
} else if (selector.startsWith('#')) {
ids.push(selector.substring(1));
}
}
return { classes: classes, ids: ids };
}
function isDataTable (attr, tables) {
if (tables === true) { return true; }
if (!attr) { return false; }
const { classes, ids } = splitClassesAndIds(tables);
const attrClasses = (attr['class'] || '').split(' ');
const attrIds = (attr['id'] || '').split(' ');
return attrClasses.some(x => classes.includes(x)) || attrIds.some(x => ids.includes(x));
}
/**
* Process a table (either as a container or as a data table, depending on options).
*
* @type { FormatCallback }
*/
function formatTable (elem, walk, builder, formatOptions) {
return isDataTable(elem.attribs, builder.options.tables)
? formatDataTable(elem, walk, builder, formatOptions)
: formatBlock(elem, walk, builder, formatOptions);
}
function formatBlock (elem, walk, builder, formatOptions) {
builder.openBlock({ leadingLineBreaks: formatOptions.leadingLineBreaks });
walk(elem.children, builder);
builder.closeBlock({ trailingLineBreaks: formatOptions.trailingLineBreaks });
}
/**
* Process a data table.
*
* @type { FormatCallback }
*/
function formatDataTable (elem, walk, builder, formatOptions) {
builder.openTable();
elem.children.forEach(walkTable);
builder.closeTable({
tableToString: (rows) => tableToString(rows, formatOptions.rowSpacing ?? 0, formatOptions.colSpacing ?? 3),
leadingLineBreaks: formatOptions.leadingLineBreaks,
trailingLineBreaks: formatOptions.trailingLineBreaks
});
function formatCell (cellNode) {
const colspan = +get(cellNode, ['attribs', 'colspan']) || 1;
const rowspan = +get(cellNode, ['attribs', 'rowspan']) || 1;
builder.openTableCell({ maxColumnWidth: formatOptions.maxColumnWidth });
walk(cellNode.children, builder);
builder.closeTableCell({ colspan: colspan, rowspan: rowspan });
}
function walkTable (elem) {
if (elem.type !== 'tag') { return; }
const formatHeaderCell = (formatOptions.uppercaseHeaderCells !== false)
? (cellNode) => {
builder.pushWordTransform(str => str.toUpperCase());
formatCell(cellNode);
builder.popWordTransform();
}
: formatCell;
switch (elem.name) {
case 'thead':
case 'tbody':
case 'tfoot':
case 'center':
elem.children.forEach(walkTable);
return;
case 'tr': {
builder.openTableRow();
for (const childOfTr of elem.children) {
if (childOfTr.type !== 'tag') { continue; }
switch (childOfTr.name) {
case 'th': {
formatHeaderCell(childOfTr);
break;
}
case 'td': {
formatCell(childOfTr);
break;
}
default:
// do nothing
}
}
builder.closeTableRow();
break;
}
default:
// do nothing
}
}
}
export {
formatAnchor as anchor,
formatBlockquote as blockquote,
formatDataTable as dataTable,
formatHeading as heading,
formatHorizontalLine as horizontalLine,
formatImage as image,
formatLineBreak as lineBreak,
formatOrderedList as orderedList,
formatParagraph as paragraph,
formatPre as pre,
formatTable as table,
formatUnorderedList as unorderedList,
formatWbr as wbr,
};