### Run Pug Example with Node.js

Source: https://github.com/pugjs/pug/blob/master/packages/pug/examples/README.md

Execute a Pug example file using Node.js. Ensure you have Node.js installed.

```bash
node attributes.js
```

--------------------------------

### Open Pug Example in Browser

Source: https://github.com/pugjs/pug/blob/master/packages/pug/examples/README.md

View a Pug example by opening the corresponding HTML file in a web browser. This is useful for front-end related examples.

```html
browser.html
```

--------------------------------

### Install pug-strip-comments

Source: https://github.com/pugjs/pug/blob/master/packages/pug-strip-comments/README.md

Install the pug-strip-comments package using npm.

```bash
npm install pug-strip-comments
```

--------------------------------

### Install Pug CLI

Source: https://github.com/pugjs/pug/blob/master/packages/pug/README.md

Install the Pug command-line interface globally after installing Node.js.

```bash
$ npm install pug-cli -g
```

--------------------------------

### Install pug-lexer

Source: https://github.com/pugjs/pug/blob/master/packages/pug-lexer/README.md

Install the pug-lexer module using npm.

```bash
npm install pug-lexer
```

--------------------------------

### Install pug-filters

Source: https://github.com/pugjs/pug/blob/master/packages/pug-filters/README.md

Install the pug-filters package using npm.

```bash
npm install pug-filters
```

--------------------------------

### Pug Syntax Example

Source: https://github.com/pugjs/pug/blob/master/packages/pug/README.md

A basic example demonstrating Pug's whitespace-sensitive syntax for creating HTML structures.

```pug
doctype html
html(lang="en")
  head
    title= pageTitle
    script(type='text/javascript').
      if (foo) bar(1 + 5)
  body
    h1 Pug - node template engine
    #container.col
      if youAreUsingPug
        p You are amazing
      else
        p Get on it!
      p.
        Pug is a terse and simple templating language with a
        strong focus on performance and powerful features.
```

--------------------------------

### Install pug-attrs

Source: https://github.com/pugjs/pug/blob/master/packages/pug-attrs/README.md

Install the pug-attrs package using npm.

```bash
npm install pug-attrs
```

--------------------------------

### Basic Include Example

Source: https://github.com/pugjs/pug/blob/master/packages/pug/test/cases/includes.html

Demonstrates a simple include of another Pug template file. Ensure the included file exists in the correct path relative to the main template.

```pug
include _bar.pug
```

--------------------------------

### Install Pug Dependencies

Source: https://github.com/pugjs/pug/blob/master/packages/pug/test/README.md

Installs the necessary dependencies for the Pug project using npm.

```bash
npm install
```

--------------------------------

### Install Pug Package

Source: https://github.com/pugjs/pug/blob/master/packages/pug/README.md

Install the Pug template engine package using npm.

```bash
$ npm install pug
```

--------------------------------

### Pug Parser AST Output Example

Source: https://github.com/pugjs/pug/blob/master/packages/pug-parser/README.md

An example of the Abstract Syntax Tree (AST) generated by the pug-parser for a simple Pug input.

```json
{
  "type": "Block",
  "nodes": [
    {
      "type": "Tag",
      "name": "div",
      "selfClosing": false,
      "block": {
        "type": "Block",
        "nodes": [],
        "line": 1,
        "filename": "my-file.pug"
      },
      "attrs": [
        {
          "name": "data-foo",
          "val": "\"bar\"",
          "line": 1,
          "column": 5,
          "filename": "my-file.pug",
          "mustEscape": true
        }
      ],
      "attributeBlocks": [],
      "isInline": false,
      "line": 1,
      "column": 1,
      "filename": "my-file.pug"
    }
  ],
  "line": 0,
  "filename": "my-file.pug"
}
```

--------------------------------

### Pug API Usage

Source: https://github.com/pugjs/pug/blob/master/README.md

Shows how to use the Pug API to compile and render templates. Requires the 'pug' module to be installed.

```javascript
var pug = require('pug');

// compile
var fn = pug.compile('string of pug', options);
var html = fn(locals);

// render
var html = pug.render('string of pug', merge(options, locals));

// renderFile
var html = pug.renderFile('filename.pug', merge(options, locals));
```

--------------------------------

### String Substitution Example

Source: https://github.com/pugjs/pug/blob/master/packages/pug/test/cases/includes.html

Illustrates how string substitutions can be used within Pug templates, particularly for special characters. This example shows a mapping of escape sequences to their literal string representations.

```javascript
console.log("foo\nbar")

var STRING_SUBSTITUTIONS = {
  // table of character substitutions
  '\t': '\\t',
  '\r': '\\r',
  '\n': '\\n',
  '"': '\\"',
  '\\': '\\\\'
};
```

--------------------------------

### Compiled HTML Output

Source: https://github.com/pugjs/pug/blob/master/packages/pug/README.md

The HTML output generated from the preceding Pug syntax example.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Pug</title>
    <script type="text/javascript">
      if (foo) bar(1 + 5)
    </script>
  </head>
  <body>
    <h1>Pug - node template engine</h1>
    <div id="container" class="col">
      <p>You are amazing</p>
      <p>Pug is a terse and simple templating language with a strong focus on performance and powerful features.</p>
    </div>
  </body>
</html>
```

--------------------------------

### Parse Pug Tokens to AST

Source: https://github.com/pugjs/pug/blob/master/packages/pug-parser/README.md

Convert Pug tokens into an Abstract Syntax Tree (AST) using the `parse` function. This example demonstrates tokenizing a simple HTML tag and then parsing those tokens.

```javascript
var lex = require('pug-lexer');

var filename = 'my-file.pug';
var src = 'div(data-foo="bar")';
var tokens = lex(src, {filename});

var ast = parse(tokens, {filename, src});

console.log(JSON.stringify(ast, null, '  '))
```

--------------------------------

### Pug Token Structure

Source: https://github.com/pugjs/pug/blob/master/packages/pug-lexer/README.md

Example of the JSON structure representing tokens generated by pug-lexer.

```json
[
  {
    "type": "tag",
    "line": 1,
    "val": "div",
    "selfClosing": false
  },
  {
    "type": "attrs",
    "line": 1,
    "attrs": [
      {
        "name": "data-foo",
        "val": "\"bar\"",
        "escaped": true
      }
    ]
  },
  {
    "type": "eos",
    "line": 1
  }
]
```

--------------------------------

### Basic Nested Filter

Source: https://github.com/pugjs/pug/blob/master/packages/pug/test/cases/filters.nested.html

This snippet shows a simple example of a nested filter. The outer filter processes the content, and the inner filter is applied to the result.

```pug
<!CDATA[!function(){console.log("test")}();]]>
```

--------------------------------

### Convert Strong Tags to Text Nodes

Source: https://github.com/pugjs/pug/blob/master/packages/pug-walk/README.md

This example shows how to convert simple `<strong>` HTML elements within a Pug AST into plain text nodes. It checks for tags with a single Text node child and replaces the tag with its content.

```javascript
var lex = require('pug-lexer');
var parse = require('pug-parser');

// Convert all simple <strong> elements to text
// ============================================

var source = 'p abc #[strong NO]\nstrong on its own line';
var dest = 'p abc #[| NO]\n| on its own line';

var ast = parse(lex(source));

ast = walk(ast, function before(node, replace) {
  // Find all <strong> tags
  if (node.type === 'Tag' && node.name === 'strong') {
    var children = node.block.nodes;

    // Make sure that the Tag only has one child -- the text
    if (children.length === 1 && children[0].type === 'Text') {
      // Replace the Tag with the Text
      replace({ type: 'Text', val: children[0].val, line: node.line });
    }
  }
}, {
  includeDependencies: true
});

assert.deepEqual(parse(lex(dest)), ast);
```

--------------------------------

### Self-Invoking Nested Filter

Source: https://github.com/pugjs/pug/blob/master/packages/pug/test/cases/filters.nested.html

This example demonstrates a nested filter that is immediately invoked. It includes a self-executing anonymous function within the filter.

```pug
<!CDATA[(function(){!function(){console.log("test")}()}).call(this);]]>
```

--------------------------------

### Generate JavaScript Function String

Source: https://github.com/pugjs/pug/blob/master/packages/pug-code-gen/README.md

Generate a JavaScript function string from a Pug AST. This example demonstrates common options like `compileDebug`, `pretty`, `inlineRuntimeFunctions`, and `templateName`. The generated function string can then be wrapped into an executable function.

```javascript
var lex = require('pug-lexer');
var parse = require('pug-parser');
var wrap = require('pug-runtime/wrap');
var generateCode = require('pug-code-gen');

var funcStr = generateCode(parse(lex('p Hello world!')), {
  compileDebug: false,
  pretty: true,
  inlineRuntimeFunctions: false,
  templateName: 'helloWorld'
});
//=> 'function helloWorld(locals) { ... }'

var func = wrap(funcStr, 'helloWorld');
func();
//=> '\n<p>Hello world!</p>'
```

--------------------------------

### Compile Attributes to Object

Source: https://github.com/pugjs/pug/blob/master/packages/pug-attrs/README.md

Compiles an array of attribute objects into a JavaScript object. This example shows object mode, where attribute values are directly represented or escaped using a runtime function.

```javascript
var compileAttrs = require('pug-attrs');
var pugRuntime = require('pug-runtime');

function getBaz () { return 'baz<>'; }

var attrs = [
  {name: 'foo',  val: '"bar"',    mustEscape: true },
  {name: 'baz',  val: 'getBaz()', mustEscape: true },
  {name: 'quux', val: true,       mustEscape: false}
];
var result, finalResult;

// OBJECT MODE
result = compileAttrs(attrs, {
  terse:   true,
  format:  'object',
  runtime: function (name) { return 'pugRuntime.' + name; }
});
//=> '{"foo": "bar","baz": pugRuntime.escape(getBaz()),"quux": true}'

finalResult = Function('pugRuntime, getBaz',
  'return (' + result + ');'
);
finalResult(pugRuntime, getBaz);
//=>{ foo: 'bar', baz: 'baz&lt;&gt;', quux: true }
```

--------------------------------

### Modify Text Node Values

Source: https://github.com/pugjs/pug/blob/master/packages/pug-walk/README.md

Example demonstrating how to change the value of all Text nodes within a Pug AST. It shows direct modification of the node's `val` property and an alternative using the `replace` function.

```javascript
var lex = require('pug-lexer');
var parse = require('pug-parser');

// Changing content of all Text nodes
// ==================================

var source = '.my-class foo';
var dest = '.my-class bar';

var ast = parse(lex(source));

ast = walk(ast, function before(node, replace) {
  if (node.type === 'Text') {
    node.val = 'bar';

    // Alternatively, you can replace the entire node
    // rather than just the text.
    // replace({ type: 'Text', val: 'bar', line: node.line });
  }
}, {
  includeDependencies: true
});

assert.deepEqual(parse(lex(dest)), ast);
```

--------------------------------

### Compile Attributes to HTML String

Source: https://github.com/pugjs/pug/blob/master/packages/pug-attrs/README.md

Compiles an array of attribute objects into a JavaScript string that evaluates to an HTML attribute string. This example demonstrates HTML mode with terse boolean attributes and runtime function calls for dynamic values.

```javascript
var compileAttrs = require('pug-attrs');
var pugRuntime = require('pug-runtime');

function getBaz () { return 'baz<>'; }

var attrs = [
  {name: 'foo',  val: '"bar"',    mustEscape: true },
  {name: 'baz',  val: 'getBaz()', mustEscape: true },
  {name: 'quux', val: true,       mustEscape: false}
];
var result, finalResult;

// HTML MODE
result = compileAttrs(attrs, {
  terse:   true,
  format:  'html',
  runtime: function (name) { return 'pugRuntime.' + name; }
});
//=> '" foo=\"bar\"" + pugRuntime.attr("baz", getBaz(), true, true) + " quux"'

finalResult = Function('pugRuntime, getBaz',
  'return (' + result + ');'
);
finalResult(pugRuntime, getBaz);
// => ' foo="bar" baz="baz&lt;&gt;" quux'
```

--------------------------------

### Pug CLI Help

Source: https://github.com/pugjs/pug/blob/master/packages/pug/README.md

Display help information for the Pug command-line interface.

```bash
$ pug --help
```

--------------------------------

### load(ast, options)

Source: https://github.com/pugjs/pug/blob/master/packages/pug-load/README.md

Loads all dependencies of a given Pug AST. It adds `fullPath` and `str` properties to every `Include` and `Extends` node, and an `ast` property to `Include` and `Extends` nodes that are loading Pug. Dependencies are recursively loaded.

```APIDOC
## load(ast, options)

### Description
Loads all dependencies of a given Pug AST. It adds `fullPath` and `str` properties to every `Include` and `Extends` node, and an `ast` property to `Include` and `Extends` nodes that are loading Pug. Dependencies are recursively loaded.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **ast** (object) - The Pug AST to process.
* **options** (object) - Configuration options.
  * **lex** (function) - Required: The lexer function to use.
  * **parse** (function) - Required: The parser function to use.
  * **resolve** (function) - Optional: A function to override `load.resolve`. Defaults to `load.resolve`.
  * **read** (function) - Optional: A function to override `load.read`. Defaults to `load.read`.
  * **basedir** (string) - Optional: The base directory for absolute inclusion. Required when absolute inclusion is used.

### Request Example
```js
// Example usage within a larger context
var lex = require('pug-lexer');
var parse = require('pug-parser');
var load = require('pug-load');

var str = fs.readFileSync('bar.pug', 'utf8');
var ast = load(parse(lex(str, 'bar.pug'), 'bar.pug'), {
  lex: lex,
  parse: parse,
  resolve: function (filename, source, options) {
    console.log('"' + filename + '" file requested from "' + source + '".');
    return load.resolve(filename, source, options);
  }
});
```

### Response
#### Success Response (200)
* **ast** (object) - The modified Pug AST with loaded dependencies.
```

--------------------------------

### Import pug-walk

Source: https://github.com/pugjs/pug/blob/master/packages/pug-walk/README.md

Import the pug-walk module for use in your project. This is the initial step before utilizing its AST traversal capabilities.

```javascript
var walk = require('pug-walk');
```

--------------------------------

### load.file(filename, options)

Source: https://github.com/pugjs/pug/blob/master/packages/pug-load/README.md

Reads a Pug file, parses it, and loads all its dependencies. This is a convenience function for loading from a file.

```APIDOC
## load.file(filename, options)

### Description
Reads a Pug file, parses it, and loads all its dependencies. This is a convenience function for loading from a file.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **filename** (string) - The path to the Pug file.
* **options** (object) - Configuration options, same as for `load(ast, options)`.

### Request Example
```js
var fs = require('fs');
var lex = require('pug-lexer');
var parse = require('pug-parser');
var load = require('pug-load');

var ast = load.file('bar.pug', {
  lex: lex,
  parse: parse,
  resolve: function (filename, source, options) {
    console.log('"' + filename + '" file requested from "' + source + '".');
    return load.resolve(filename, source, options);
  }
});
```

### Response
#### Success Response (200)
* **ast** (object) - The Pug AST with loaded dependencies.
```

--------------------------------

### Build Custom Runtime Source

Source: https://github.com/pugjs/pug/blob/master/packages/pug-runtime/README.md

Shows how to generate a custom runtime source string for specific methods using `require('pug-runtime/build')`. This allows for inlining runtime functions into compiled templates.

```javascript
var build = require('pug-runtime/build');
var src = build(['attr']);

var attr = Function('', src + ';return pug_attr;')();
assert(attr('foo', 'bar', true, true) === ' foo="bar"');
```

--------------------------------

### Load Pug Dependencies from File

Source: https://github.com/pugjs/pug/blob/master/packages/pug-load/README.md

Load Pug dependencies directly from a file using `load.file`. This is the most concise method, handling reading, lexing, parsing, and loading internally, while still allowing custom resolve functions.

```javascript
var fs = require('fs');
var lex = require('pug-lexer');
var parse = require('pug-parser');
var load = require('pug-load');

// or you can do all that in only one step

var ast = load.file('bar.pug', {
  lex: lex,
  parse: parse,
  resolve: function (filename, source, options) {
    console.log('"' + filename + '" file requested from "' + source + '".');
    return load.resolve(filename, source, options);
  }
});
```

--------------------------------

### load.string(str, filename, options)

Source: https://github.com/pugjs/pug/blob/master/packages/pug-load/README.md

Parses a Pug string and loads all its dependencies. This is a convenience function that combines parsing and dependency loading.

```APIDOC
## load.string(str, filename, options)

### Description
Parses a Pug string and loads all its dependencies. This is a convenience function that combines parsing and dependency loading.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **str** (string) - The Pug template string.
* **filename** (string) - The filename associated with the string, used for resolving relative paths.
* **options** (object) - Configuration options, same as for `load(ast, options)`.

### Request Example
```js
var fs = require('fs');
var lex = require('pug-lexer');
var parse = require('pug-parser');
var load = require('pug-load');

var str = fs.readFileSync('bar.pug', 'utf8');
var ast = load.string(str, 'bar.pug', {
  lex: lex,
  parse: parse,
  resolve: function (filename, source, options) {
    console.log('"' + filename + '" file requested from "' + source + '".');
    return load.resolve(filename, source, options);
  }
});
```

### Response
#### Success Response (200)
* **ast** (object) - The Pug AST with loaded dependencies.
```

--------------------------------

### Direct Runtime Method Call

Source: https://github.com/pugjs/pug/blob/master/packages/pug-runtime/README.md

Demonstrates how to directly call runtime methods like `attr` using `require('pug-runtime')`. This is useful when certain elements are known at compile time.

```javascript
var runtime = require('pug-runtime');

assert(runtime.attr('foo', 'bar', true, true) === ' foo="bar"');
```

--------------------------------

### Compile Pug to JavaScript for Browser Use

Source: https://github.com/pugjs/pug/blob/master/packages/pug/README.md

Use this command-line instruction to pre-compile Pug templates into JavaScript files for client-side rendering. This is recommended for browser environments to reduce file size and improve performance.

```bash
$ pug --client --no-debug filename.pug
```

--------------------------------

### parse(tokens, options)

Source: https://github.com/pugjs/pug/blob/master/packages/pug-parser/README.md

Converts an array of Pug tokens into an Abstract Syntax Tree (AST). It accepts an optional options object to configure parsing behavior, such as specifying the filename, applying plugins, or providing the source string for error handling.

```APIDOC
## parse(tokens, options)

### Description
Converts Pug tokens to an abstract syntax tree (AST).

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **tokens** (array) - Required - An array of tokens generated by pug-lexer.
- **options** (object) - Optional - Configuration options for parsing.
  - **filename** (string) - Optional - The name of the Pug file; used in AST nodes and error handling.
  - **plugins** (array) - Optional - An array of plugins to be applied in order.
  - **src** (string) - Optional - The source of the Pug file; used in error handling.

### Request Example
```javascript
var lex = require('pug-lexer');
var parse = require('pug-parser');

var filename = 'my-file.pug';
var src = 'div(data-foo="bar")';
var tokens = lex(src, {filename: filename});

var ast = parse(tokens, {filename: filename, src: src});

console.log(JSON.stringify(ast, null, '  '))
```

### Response
#### Success Response (200)
- **ast** (object) - The generated Abstract Syntax Tree.

#### Response Example
```json
{
  "type": "Block",
  "nodes": [
    {
      "type": "Tag",
      "name": "div",
      "selfClosing": false,
      "block": {
        "type": "Block",
        "nodes": [],
        "line": 1,
        "filename": "my-file.pug"
      },
      "attrs": [
        {
          "name": "data-foo",
          "val": "\"bar\"",
          "line": 1,
          "column": 5,
          "filename": "my-file.pug",
          "mustEscape": true
        }
      ],
      "attributeBlocks": [],
      "isInline": false,
      "line": 1,
      "column": 1,
      "filename": "my-file.pug"
    }
  ],
  "line": 0,
  "filename": "my-file.pug"
}
```
```

--------------------------------

### Import pug-load

Source: https://github.com/pugjs/pug/blob/master/packages/pug-load/README.md

Import the pug-load module for use in your project.

```javascript
var load = require('pug-load');
```

--------------------------------

### Run Pug Tests

Source: https://github.com/pugjs/pug/blob/master/packages/pug/test/README.md

Executes the test suite for the Pug project using npm.

```bash
npm test
```

--------------------------------

### Manual Pug Dependency Loading

Source: https://github.com/pugjs/pug/blob/master/packages/pug-load/README.md

Manually load Pug dependencies by reading a file, lexing, parsing, and then loading the AST. This method allows for custom resolve functions.

```javascript
var fs = require('fs');
var lex = require('pug-lexer');
var parse = require('pug-parser');
var load = require('pug-load');

// you can do everything very manually

var str = fs.readFileSync('bar.pug', 'utf8');
var ast = load(parse(lex(str, 'bar.pug'), 'bar.pug'), {
  lex: lex,
  parse: parse,
  resolve: function (filename, source, options) {
    console.log('"' + filename + '" file requested from "' + source + '".');
    return load.resolve(filename, source, options);
  }
});
```

--------------------------------

### Load Pug Dependencies from String

Source: https://github.com/pugjs/pug/blob/master/packages/pug-load/README.md

Load Pug dependencies from a string using `load.string`. This method simplifies the process by handling parsing internally and allows for custom resolve functions.

```javascript
var fs = require('fs');
var lex = require('pug-lexer');
var parse = require('pug-parser');
var load = require('pug-load');

// or you can do all that in just two steps

var str = fs.readFileSync('bar.pug', 'utf8');
var ast = load.string(str, 'bar.pug', {
  lex: lex,
  parse: parse,
  resolve: function (filename, source, options) {
    console.log('"' + filename + '" file requested from "' + source + '".');
    return load.resolve(filename, source, options);
  }
});
```

--------------------------------

### new parse.Parser(tokens, options)

Source: https://github.com/pugjs/pug/blob/master/packages/pug-parser/README.md

Constructor for a Parser class. This is generally not intended for direct use by developers unless they have specific advanced requirements.

```APIDOC
## new parse.Parser(tokens, options)

### Description
Constructor for a Parser class. This is not meant to be used directly unless you know what you are doing.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **tokens** (array) - Required - An array of tokens generated by pug-lexer.
- **options** (object) - Optional - Configuration options for parsing.
  - **filename** (string) - Optional - The name of the Pug file; used in AST nodes and error handling.
  - **plugins** (array) - Optional - An array of plugins to be applied in order.
  - **src** (string) - Optional - The source of the Pug file; used in error handling.

### Request Example
```javascript
// Example usage is not provided as this constructor is not meant for direct use.
// Developers should typically use the `parse` function instead.
```

### Response
#### Success Response (200)
- **Parser instance** (object) - An instance of the Parser class.

#### Response Example
```json
// No specific JSON response example is provided for the constructor itself.
```
```

--------------------------------

### Pug API: Render File

Source: https://github.com/pugjs/pug/blob/master/packages/pug/README.md

Render a Pug template file directly to HTML, merging 'options' and 'locals'. The 'filename' option is required when using includes.

```javascript
var html = pug.renderFile('filename.pug', merge(options, locals));
```

--------------------------------

### Import Pug Parser

Source: https://github.com/pugjs/pug/blob/master/packages/pug-parser/README.md

Import the pug-parser module for use in your project.

```javascript
var parse = require('pug-parser');
```

--------------------------------

### load.read(filename, options)

Source: https://github.com/pugjs/pug/blob/master/packages/pug-load/README.md

Callback used to return the contents of a file. This function is intended to be overridden.

```APIDOC
## load.read(filename, options)

### Description
Callback used by `pug-load` to return the contents of a file. This function is not meant to be called from outside of `pug-load`, but rather for you to override.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **filename** (string) - The name of the file to read.
* **options** (object) - Configuration options passed from the main load function.

### Request Example
```js
// Example of overriding load.read
var load = require('pug-load');

load.read = function (filename, options) {
  console.log('Reading file: ' + filename);
  // Custom file reading logic here
  return 'pug template content';
};
```

### Response
#### Success Response (200)
* **fileContent** (string) - The content of the file.
```

--------------------------------

### Wrap Browser-Compiled Code for Node.js

Source: https://github.com/pugjs/pug/blob/master/packages/pug-runtime/README.md

Explains how to use `require('pug-runtime/wrap')` to make runtime functions available when testing browser-compiled Pug templates in a Node.js environment. It shows how to wrap compiled code and optionally specify a template function name.

```javascript
var pug = require('pug');
var wrap = require('pug-runtime/wrap');

var pugSrc = 'p= content';
// By default compileClient automatically embeds the needed runtime functions,
// rendering this module useless.
var compiledCode = pug.compileClient(pugSrc, {
  externalRuntime: true
});
//=> 'function template (locals) { ... pug.escape() ... }'

var templateFunc = wrap(compiledCode);
templateFunc({content: 'Hey!'});
//=> '<p>Hey!</p>'

// Change template function name to 'heyTemplate'
compiledCode = pug.compileClient(pugSrc, {
  externalRuntime: true,
  name: 'heyTemplate'
});
//=> 'function heyTemplate (locals) { ... }'

templateFunc = wrap(compiledCode, 'heyTemplate');
templateFunc({content: 'Hey!'});
//=> '<p>Hey!</p>'
```

--------------------------------

### load.resolve(filename, source, options)

Source: https://github.com/pugjs/pug/blob/master/packages/pug-load/README.md

Callback used to resolve the full path of an included or extended file. This function is intended to be overridden.

```APIDOC
## load.resolve(filename, source, options)

### Description
Callback used by `pug-load` to resolve the full path of an included or extended file given the path of the source file. This function is not meant to be called from outside of `pug-load`, but rather for you to override.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **filename** (string) - The path of the file to resolve.
* **source** (string) - The name of the parent file that includes `filename`.
* **options** (object) - Configuration options passed from the main load function.

### Request Example
```js
// Example of overriding load.resolve
var load = require('pug-load');

load.resolve = function (filename, source, options) {
  console.log('Resolving: ' + filename + ' from ' + source);
  // Custom resolution logic here
  return '/path/to/resolved/file';
};
```

### Response
#### Success Response (200)
* **resolvedPath** (string) - The full path to the resolved file.
```

--------------------------------

### lex(str, options)

Source: https://github.com/pugjs/pug/blob/master/packages/pug-lexer/README.md

Converts a Pug string into an array of tokens. It accepts the Pug source string and an optional options object for configuration.

```APIDOC
## lex(str, options)

### Description
Converts Pug string to an array of tokens.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
`options` can contain the following properties:

- `filename` (string): The name of the Pug file; it is used in error handling if provided.
- `plugins` (array): An array of plugins, in the order they should be applied.

### Request Example
```javascript
var lex = require('pug-lexer');
console.log(JSON.stringify(lex('div(data-foo="bar")', {filename: 'my-file.pug'}), null, '  '))
```

### Response
#### Success Response (200)
An array of tokens representing the parsed Pug string.

#### Response Example
```json
[
  {
    "type": "tag",
    "line": 1,
    "val": "div",
    "selfClosing": false
  },
  {
    "type": "attrs",
    "line": 1,
    "attrs": [
      {
        "name": "data-foo",
        "val": "\"bar\"",
        "escaped": true
      }
    ]
  },
  {
    "type": "eos",
    "line": 1
  }
]
```
```

--------------------------------

### Client-Side Pug Rendering

Source: https://github.com/pugjs/pug/blob/master/packages/pug/test/browser/index.html

This snippet demonstrates how to use Pug's `render` function in the browser. It takes input from a textarea, compiles it using Pug, and displays the output in another element. The rendering updates every 500 milliseconds.

```html
<p author != myName></p>

<var input = document.getElementById('input'); var output = document.getElementById('output'); setInterval(function () {
  pug.render(input.value, {myName: 'Forbes Lindesay', pretty: true}, function (err, res) {
    if (err) throw err;
    output.textContent = res;
  })
}, 500)
```

--------------------------------

### Require Pug-Linker Module

Source: https://github.com/pugjs/pug/blob/master/packages/pug-linker/README.md

Import the pug-linker module for use in your project.

```javascript
var link = require('pug-linker');
```

--------------------------------

### Require pug-code-gen

Source: https://github.com/pugjs/pug/blob/master/packages/pug-code-gen/README.md

Import the `generateCode` function from the `pug-code-gen` package.

```javascript
var generateCode = require('pug-code-gen');
```

--------------------------------

### Pug API: Render Template

Source: https://github.com/pugjs/pug/blob/master/packages/pug/README.md

Render a Pug template string directly to HTML, merging 'options' and 'locals'.

```javascript
var html = pug.render('string of pug', merge(options, locals));
```

--------------------------------

### filters.handleFilters

Source: https://github.com/pugjs/pug/blob/master/packages/pug-filters/README.md

Renders all Filter nodes in a Pug AST using user-specified filters or a JSTransformer.

```APIDOC
## filters.handleFilters(ast, filters)

### Description

Renders all `Filter` nodes in a Pug AST (`ast`), using user-specified filters (`filters`) or a JSTransformer.

### Method

Direct function call

### Parameters

- **ast** (object) - Required - The Pug AST to process.
- **filters** (object) - Required - User-specified filters or a JSTransformer.
```

--------------------------------

### Pug API: Compile Template

Source: https://github.com/pugjs/pug/blob/master/packages/pug/README.md

Compile a Pug template string into a function for later rendering. The 'options' object can include 'filename', 'compileDebug', and 'pretty'.

```javascript
var pug = require('pug');

// compile
var fn = pug.compile('string of pug', options);
var html = fn(locals);
```

--------------------------------

### load.validateOptions(options)

Source: https://github.com/pugjs/pug/blob/master/packages/pug-load/README.md

Callback used to ensure the options object is valid. This function is intended to be overridden if custom options are used.

```APIDOC
## load.validateOptions(options)

### Description
Callback used `pug-load` to ensure the options object is valid. If your overridden `load.resolve` or `load.read` uses a different `options` scheme, you will need to override this function as well. This function is not meant to be called from outside of `pug-load`, but rather for you to override.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **options** (object) - The options object to validate.

### Request Example
```js
// Example of overriding load.validateOptions
var load = require('pug-load');

load.validateOptions = function (options) {
  console.log('Validating options:', options);
  // Custom validation logic here
  if (!options.customSetting) {
    throw new Error('Custom setting is required!');
  }
};
```

### Response
#### Success Response (200)
No explicit return value, indicates options are valid.
```

--------------------------------

### Import pug-error

Source: https://github.com/pugjs/pug/blob/master/packages/pug-error/README.md

Import the pug-error module for use in your project.

```javascript
var error = require('pug-error');
```

--------------------------------

### Flatten Nested Blocks

Source: https://github.com/pugjs/pug/blob/master/packages/pug-walk/README.md

Demonstrates how to flatten deeply nested Block nodes in a Pug AST into a single, linear sequence of nodes. This utilizes the `after` callback to process inner blocks first.

```javascript
var ast = {
  type: 'Block',
  nodes: [
    { type: 'Text', val: 'a' },
    {
      type: 'Block',
      nodes: [
        { type: 'Text', val: 'b' },
        {
          type: 'Block',
          nodes: [ { type: 'Text', val: 'c' } ]
        },
        { type: 'Text', val: 'd' }
      ]
    },
    { type: 'Text', val: 'e' }
  ]
};

var dest = {
  type: 'Block',
  nodes: [
    { type: 'Text', val: 'a' },
    { type: 'Text', val: 'b' },
    { type: 'Text', val: 'c' },
    { type: 'Text', val: 'd' },
    { type: 'Text', val: 'e' }
  ]
};

// We need to use `after` handler instead of `before`
// handler because we want to flatten the innermost
// blocks first before proceeding onto outer blocks.

ast = walk(ast, null, function after(node, replace) {
  if (node.type === 'Block' && replace.arrayAllowed) {
    // Replace the block with its contents
    replace(node.nodes);
  }
});

assert.deepEqual(dest, ast);
```

--------------------------------

### Strip Both Unbuffered and Buffered Comments

Source: https://github.com/pugjs/pug/blob/master/packages/pug-strip-comments/README.md

Demonstrates how to configure pug-strip-comments to remove all types of comments (both unbuffered and buffered) for a cleaner Pug output.

```javascript
var lex = require('pug-lexer');
var stripComments = require('pug-strip-comments');

var tokens = lex('//- unbuffered\n// buffered');
// [ { type: 'comment', line: 1, val: ' unbuffered', buffer: false },
//   { type: 'newline', line: 2 },
//   { type: 'comment', line: 2, val: ' buffered', buffer: true },
//   { type: 'eos', line: 2 } ]

// Strip both (if you want Pug VERY clean)
stripComments(tokens, { filename: 'pug', stripBuffered: true });
// [ { type: 'newline', line: 2 },
//   { type: 'eos', line: 2 } ]
```

--------------------------------

### Create a Pug error object

Source: https://github.com/pugjs/pug/blob/master/packages/pug-error/README.md

Create a Pug error object with a unique code, message, and optional context like filename, line, and source code. The 'message' argument is stored in 'err.msg', while 'err.message' is a formatted string.

```javascript
var error = require('pug-error');

var err = error('MY_CODE', 'My message', {line: 3, filename: 'myfile', src: 'foo\nbar\nbaz\nbash\nbing'});
// { code: 'PUG:MY_CODE',
//   msg: 'My message',
//   line: 3,
//   column: undefined,
//   filename: 'myfile',
//   src: 'foo\nbar\nbaz\nbash\nbing',
//   message: 'myfile:3\n    1| foo\n    2| bar\n  > 3| baz\n    4| bash\n    5| bing\n\nMy message' }

throw err;
```

--------------------------------

### Lex Pug String to Tokens

Source: https://github.com/pugjs/pug/blob/master/packages/pug-lexer/README.md

Convert a Pug string into an array of tokens. The 'filename' option is used for error handling.

```javascript
console.log(JSON.stringify(lex('div(data-foo="bar")', {filename: 'my-file.pug'}), null, '  '))
```

--------------------------------

### Basic Usage: Strip Unbuffered Comments

Source: https://github.com/pugjs/pug/blob/master/packages/pug-strip-comments/README.md

Demonstrates how to use pug-strip-comments to remove only unbuffered comments, which is the default behavior. It first tokenizes Pug code and then applies the stripping function.

```javascript
var lex = require('pug-lexer');
var stripComments = require('pug-strip-comments');

var tokens = lex('//- unbuffered\n// buffered');
// [ { type: 'comment', line: 1, val: ' unbuffered', buffer: false },
//   { type: 'newline', line: 2 },
//   { type: 'comment', line: 2, val: ' buffered', buffer: true },
//   { type: 'eos', line: 2 } ]

// Only strip unbuffered comments (default)
stripComments(tokens, { filename: 'pug' });
// [ { type: 'newline', line: 2 },
//   { type: 'comment', line: 2, val: ' buffered', buffer: true },
//   { type: 'eos', line: 2 } ]
```

--------------------------------

### Strip Buffered Comments Only

Source: https://github.com/pugjs/pug/blob/master/packages/pug-strip-comments/README.md

Shows how to configure pug-strip-comments to remove only buffered comments, useful for specific scenarios like pranks.

```javascript
var lex = require('pug-lexer');
var stripComments = require('pug-strip-comments');

var tokens = lex('//- unbuffered\n// buffered');
// [ { type: 'comment', line: 1, val: ' unbuffered', buffer: false },
//   { type: 'newline', line: 2 },
//   { type: 'comment', line: 2, val: ' buffered', buffer: true },
//   { type: 'eos', line: 2 } ]

// Only strip buffered comments (when you want to play a joke on your coworkers)
stripComments(tokens, { filename: 'pug', stripUnbuffered: false, stripBuffered: true });
// [ { type: 'comment', line: 1, val: ' unbuffered', buffer: false },
//   { type: 'newline', line: 2 },
//   { type: 'eos', line: 2 } ]
```

--------------------------------

### IIFE with Math Object

Source: https://github.com/pugjs/pug/blob/master/packages/pug/test/cases/filters.include.html

An IIFE that defines and initializes a local 'math' object with a 'square' method.

```javascript
(function() {
  var math;
  math = {
    square: function(value) {
      return value * value;
    }
  };
}).call(this);
```