Cardinal JavaScript Syntax Highlighter

Common errors

• Error: Cannot parse code

  cause The input string or file contains invalid JavaScript syntax that cardinal's parser cannot understand, or JSX without the `jsx: true` option.
  fix Review the code for syntax errors. If using JSX, ensure the `{ jsx: true }` option is provided to the `highlight` function. Wrap calls to `highlight` or `highlightFileSync` in a `try...catch` block to handle parsing errors gracefully.

• TypeError: require is not a function

  cause Attempting to use `require('cardinal')` in an ES Module context, where `require` is not natively available.
  fix Since `cardinal` is a CommonJS module, it should be used in a CommonJS environment or through a compatible loader/bundler. If you must use it in an ESM project, consider dynamic `import()` or transpilation if your toolchain supports it, or wrap it in a separate CJS file and import that wrapper.

Warnings

• gotcha The `json` option in `opts` is obsoleted. Cardinal now automatically understands both JSON and JavaScript, making this option redundant and its usage potentially ignored or deprecated.
  Fix: Remove the `json: true` option from your `opts` object. Cardinal will correctly process JSON input without it.
• gotcha JSX syntax support requires explicitly setting `jsx: true` in the options object. By default, JSX will not be highlighted, and `cardinal` will throw a parsing error if encountered.
  Fix: When highlighting code that includes JSX, pass `{ jsx: true }` in the options parameter to `highlight`, `highlightFileSync`, or `highlightFile`.
• gotcha When using `cardinal` as part of a UNIX pipe, such as `cat file.js | grep console | cdl`, lines that are not parsable as valid JavaScript may be printed without highlighting.
  Fix: Ensure that the piped input contains only valid JavaScript segments if full highlighting is expected. Invalid lines will gracefully fall back to unhighlighted output.
• breaking The package `cardinal` has not been updated in approximately eight years. This means it is no longer actively maintained, and users should not expect bug fixes, security updates, or compatibility with newer JavaScript language features or Node.js versions beyond its last stable release. Relying on it in new projects might introduce unaddressed vulnerabilities or compatibility issues.
  Fix: Evaluate alternatives if active maintenance, modern JavaScript syntax support, or security updates are critical for your project. If using, thoroughly test with your specific Node.js version and JavaScript syntax.

Install

• npm install cardinal npm
• yarn add cardinal yarn
• pnpm add cardinal pnpm

Imports

• highlight
  wrong:

  import { highlight } from 'cardinal';

  correct:

  const cardinal = require('cardinal');
  const highlightedCode = cardinal.highlight(codeString);

  Cardinal is a CommonJS module. Direct ES Module imports will typically fail without a compatibility layer or bundler due to its age and lack of native ESM support.
• highlightFileSync
  wrong:

  import cardinal from 'cardinal';
  const highlightedFile = cardinal.highlightFileSync('./myFile.js');

  correct:

  const cardinal = require('cardinal');
  const highlightedFile = cardinal.highlightFileSync('./myFile.js');

  The primary export is the module itself, containing the `highlightFileSync` method. Importing named exports like `highlightFileSync` directly is not supported.
• highlightFile
  wrong:

  import { highlightFile } from 'cardinal';

  correct:

  const cardinal = require('cardinal');
  cardinal.highlightFile('./myFile.js', (err, highlighted) => {
    if (err) console.error(err);
    else console.log(highlighted);
  });

  This function provides an asynchronous way to highlight file content, using a Node.js-style callback pattern, consistent with its CommonJS design.

Quickstart

This quickstart demonstrates how to use `cardinal` to highlight both a JavaScript code string and a JavaScript file, using both synchronous and asynchronous API calls. It also shows how to apply options like line numbers and themes, and includes basic error handling for parsing failures.

const cardinal = require('cardinal');
const fs = require('fs');
const path = require('path');

const codeToHighlight = `
function greet(name) {
  const message = 'Hello, ' + name + '!';
  // A comment about the greeting
  console.log(message);
}

greet('World');
`;

const filePath = path.join(__dirname, 'example.js');
fs.writeFileSync(filePath, codeToHighlight);

console.log('--- Synchronous String Highlight ---');
try {
  const highlightedString = cardinal.highlight(codeToHighlight, { linenos: true });
  console.log(highlightedString);
} catch (e) {
  console.error('Error highlighting string:', e.message);
}

console.log('\n--- Synchronous File Highlight ---');
try {
  const highlightedFile = cardinal.highlightFileSync(filePath, { theme: 'github', linenos: false });
  console.log(highlightedFile);
} catch (e) {
  console.error('Error highlighting file sync:', e.message);
}

console.log('\n--- Asynchronous File Highlight ---');
cardinal.highlightFile(filePath, { jsx: true }, (err, highlighted) => {
  if (err) {
    console.error('Error highlighting file async:', err.message);
  } else {
    console.log(highlighted);
  }
  fs.unlinkSync(filePath); // Clean up temp file
});