pandoc.ts

/*
 * pandoc.ts
 *
 * This module handles spawning Pandoc, passing it arguments, and streaming
 * to/from STDIN/STDOUT buffers if desired.
 *
 * Loosely based on https://github.com/eshinn/node-pandoc (MIT licensed)
 *
 */

import { stat, Stats } from 'fs';
import { spawn, ChildProcess } from 'child_process';
import * as path from 'path';
import * as fs from 'fs';
import { lookpath } from 'lookpath';

// Pandoc CLI syntax
// pandoc -f markdown -s -t html -o output.html input.md
// -f/--from: format of source file (listed at the end, if omitted it's STDIN)
// -t/--to: format of destination file (listed with -o or STDOUT)
// -s produces a standalone document (eg HEAD tags for HTML)

type AbsoluteFilePath = string;
type URLString = string;

// A list of markdown formats: markdown (Pandoc), commonmark, markdown_mmd (MultiMarkdown),
// gfm (GitHub markdown), commonmark_x (extended CommonMark)
// Not all input formats are here for now
// JSON is the JSON serialisation of the Pandoc AST which can be used for filtering
export type InputFormat = 'markdown' | 'commonmark' | 'docx' | 'csv' | 'html'
  | 'json' | 'latex' | 'odt';

export const inputExtensions = ['md', 'docx', 'csv', 'html', 'tex', 'odt'];

// Subset of output formats, will add more later
// Note: you need a `-o -` in the command to output odt, docx, epub or pdf output (presumably as they are binary formats or something)
export type OutputFormat = 'asciidoc' | 'beamer' | 'commonmark_x' | 'docx' | 'epub'
  | 'html' | 'pdf' | 'json' | 'latex' | 'odt' | 'pptx' | 'revealjs'
  | 'beamer' | 'rtf' | 'docuwiki' | 'mediawiki';

// List of [pretty name, pandoc format name, file extension, shortened pretty name]
export const outputFormats = [
    ['AsciiDoc (adoc)', 'asciidoc', 'adoc', 'AsciiDoc'],
    ['Word Document (docx)', 'docx', 'docx', 'Word'],
    ['Pandoc Markdown', 'markdown', 'pandoc.md', 'markdown'],  // X.md -> X.pandoc.md to avoid conflict
    ['HTML (without Pandoc)','html','html', 'HTML'],
    ['LaTeX', 'latex', 'tex', 'LaTeX'],
    ['OpenDocument (odt)', 'odt', 'odt', 'OpenDocument'],
    ['PowerPoint (pptx)', 'pptx', 'pptx', 'PowerPoint'],
    ['ePub', 'epub', 'epub', 'ePub'],
    ['PDF (via LaTeX)', 'pdf', 'pdf', 'PDF'],
    ['Reveal.js Slides', 'revealjs', 'reveal.html', 'Reveal.js'],
    ['Beamer Slides', 'beamer', 'beamer.tex', 'Beamer'],
    ['reStructured Text (RST)', 'rst', 'rst', 'RST'],
    ['DokuWiki', 'dokuwiki', 'txt', 'DokuWiki'],
    ['MediaWiki', 'mediawiki', 'mediawiki', 'MediaWiki'],
];

export interface PandocInput {
    file: AbsoluteFilePath | URLString | 'STDIN',  // if STDIN, the contents parameter must exist
    format?: InputFormat,  // -f/--from format, if left blank it's inferred by Pandoc
    contents?: string,
    metadataFile?: string,  // path to YAML file
    pandoc?: string, // optional path to Pandoc if it's not in the current PATH variable
    pdflatex?: string, // ditto for pdflatex
}

export interface PandocOutput {
    file: AbsoluteFilePath | 'STDOUT', // if STDOUT, the promise will resolve to a string
    format?: OutputFormat,  // -t/--to format, inferred if blank
}

export function needsLaTeX(format: OutputFormat): boolean {
    return format === 'pdf';
}

export function needsPandoc(format: OutputFormat): boolean {
    return format !== 'html';
}

export function needsStandaloneFlag(output: PandocOutput): boolean {
    return output.file.endsWith('html')
        || output.format === 'html'
        || output.format === 'revealjs'
        || output.format === 'latex'
        || output.format === 'beamer';
}

// Note: we apply Unicode stripping for STDIN, otherwise you're on your own
export function needsUnicodeStripped(output: PandocOutput): boolean {
    return output.format === 'latex'
        || output.format === 'pdf'
        || output.format === 'beamer';
}

// Note: extraParams is a list of strings like ['-o', 'file.md']
// This rejects if the file doesn't get created
export const pandoc = async (input: PandocInput, output: PandocOutput, extraParams?: string[])
    : Promise<{ result: string, command: string, error: string }> => new Promise(async (resolve, reject) => {
    const stdin = input.file === 'STDIN';
    const stdout = output.file === 'STDOUT';

    let pandoc: ChildProcess;
    let result = '';
    let error = '';

    const fileBaseName = (file: string): string => path.basename(file, path.extname(file));

    // Construct the Pandoc arguments list
    let args: string[] = [];

    if (input.format) {
        args.push('--from');
        args.push(input.format);
    }
    if (output.format) {
        args.push('--to');
        args.push(output.format);
    }
    if (needsStandaloneFlag(output))
        args.push('-s');
    if (!stdout) {
        args.push('-o');
        args.push(output.file);
    } else {
        args.push('-o');
        args.push('-');
    }
    // // Support Unicode in the PDF output if XeLaTeX is installed
    if (output.format === 'pdf' && await lookpath('xelatex'))
        args.push('--pdf-engine=xelatex');
    if (!stdin) {
        args.push(input.file);
    }
    // The metadata title is needed for ePub and standalone HTML formats
    // We use a metadata file to avoid being vulnerable to command injection
    if (input.metadataFile) args.push('--metadata-file', input.metadataFile);
    // Extra parameters
    if (extraParams) {
        extraParams = extraParams.flatMap(x => x.split(' ')).filter(x => x.length);
        args.push(...extraParams);
    }

    function start () {
        // Spawn a Pandoc child process
        // Assumes Pandoc is installed and that the arguments are valid
        // The arguments aren't sanitised, so be careful!
        const env = Object.assign(process.env);

        if (input.pdflatex) {
            // Workaround for Windows having different PATH delimiters
            // to *every other operating system in existence*
            // *sigh*
            if (process.platform === 'win32')
                env.PATH += ";"
            else
                env.PATH += ":";
            env.PATH += path.dirname(input.pdflatex);
        }
        pandoc = spawn(input.pandoc || 'pandoc', args, { env: process.env });

        if (stdin) {
            // TODO: strip some unicode characters but not others
            // Currently we're stripping footnote back arrows but no
            // other characters to avoid localisation issues
            const contents = input.contents.replace(/[\u21a9\ufe0e]/g, '');
            pandoc.stdin.write(contents);
            pandoc.stdin.end();
        }

        // Handlers
        pandoc.stdout.on('data', (data: any) => {
            result += data;
        });
        pandoc.stderr.on('data', (err: any) => {
            error += err;
        });
        pandoc.stdout.on('end', () => {
            const value = {
                result, error,
                command: 'pandoc ' + args.join(' ')
            };
            if (output.file !== 'STDOUT') {
                fs.stat(output.file, (err: NodeJS.ErrnoException | null, stats: fs.Stats) => {
                    // Call resolve if the file exists, reject otherwise
                    if (stats && stats.isFile()) {
                        resolve(value);
                    } else {
                        reject(error);
                    }
                });
            } else {
                // Call resolve iff there is a nonempty result
                (result.length ? resolve : reject)(value);
                if (result.length) {
                    resolve(value);
                } else {
                    reject(error);
                }
            }
        });
    }

    if (input.file === 'STDIN') {
        start();
    } else {
        // Check if the input file exists, and then start
        stat(input.file, (err: NodeJS.ErrnoException | null, stats: Stats) => {
            if (stats.isFile()) start();
            else reject(new Error('Input file does not exist'));
        });
    }
});