Template Compilation

/**
 * Compile a Pug template string into a function
 * @param str - Pug template source code
 * @param options - Compilation options
 * @returns Template function that accepts locals and returns HTML string
 */
function compile(str, options);

const pug = require('pug');

// Basic compilation
const template = pug.compile('p Hello #{name}!');
const html = template({ name: 'World' });
// Result: <p>Hello World!</p>

// With options
const template2 = pug.compile(`
doctype html
html
  head
    title= title
  body
    h1= heading
    p= message
`, {
  pretty: true,
  compileDebug: false
});

const html2 = template2({
  title: 'My App',
  heading: 'Welcome',
  message: 'Hello from Pug!'
});

/**
 * Compile a Pug template file into a function
 * @param path - Path to Pug template file
 * @param options - Compilation options
 * @returns Template function with caching support
 */
function compileFile(path, options);

const pug = require('pug');

// Compile from file
const template = pug.compileFile('./views/layout.pug');
const html = template({ user: 'Alice', posts: [] });

// With caching enabled
const template2 = pug.compileFile('./views/user.pug', {
  cache: true,
  pretty: true
});

// Template will be cached and reused on subsequent calls
const html2 = template2({ user: { name: 'Bob', email: 'bob@example.com' } });

/**
 * Compiled template function
 * @param locals - Variables to make available in the template
 * @returns Rendered HTML string
 */
type TemplateFunction = (locals?: any) => string;

/**
 * Template functions include a dependencies property for file-based templates
 */
interface CompiledTemplate extends TemplateFunction {
  /** Array of file paths that this template depends on (includes/extends) */
  dependencies?: string[];
}

interface CompilationOptions {
  /** Used for error reporting and resolving includes/extends */
  filename?: string;
  /** Include debugging information (default: true) */
  compileDebug?: boolean;
  /** Add pretty-indentation to output (default: false) */
  pretty?: boolean;
  /** Base directory for resolving includes and extends */
  basedir?: string;
  /** Set default doctype if not specified in template */
  doctype?: string;
  /** Custom filters for template processing */
  filters?: { [name: string]: Function };
  /** Options passed to filters */
  filterOptions?: any;
  /** Aliases for filter names */
  filterAliases?: { [alias: string]: string };
  /** Variables to make available globally in templates */
  globals?: string[];
  /** Use self namespace for locals (default: false) */
  self?: boolean;
  /** Inline runtime functions in generated code */
  inlineRuntimeFunctions?: boolean;
  /** Array of compilation plugins */
  plugins?: PugPlugin[];
  /** Include source maps in debug builds */
  includeSources?: boolean;
  /** Name for the generated template function */
  templateName?: string;
  /** Debug compilation process to console */
  debug?: boolean;
}

// parent.pug
const parentTemplate = pug.compile(`
doctype html
html
  head
    title= title
  body
    block content
`);

// child.pug extends parent.pug
const childTemplate = pug.compileFile('./child.pug', {
  basedir: './views'
});

const template = pug.compile('p: :markdown # Hello World', {
  filters: {
    markdown: function(text) {
      return require('markdown-it')().render(text);
    }
  }
});

const myPlugin = {
  postParse: function(ast, options) {
    // Modify the AST after parsing
    return ast;
  }
};

const template = pug.compile('p Hello World', {
  plugins: [myPlugin]
});

try {
  const template = pug.compile('invalid pug syntax here {{}}');
} catch (err) {
  console.error('Compilation error:', err.message);
  console.error('Line:', err.line);
  console.error('Column:', err.column);
}