# biscotti

> .

Latest version **3.0.0** (published 2019-01-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install biscotti
pnpm add biscotti
yarn add biscotti
bun add biscotti
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2019-01-21 |
| First published | 2018-03-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 42.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Dan Yoder |
| Maintainers | dyoder, freeformflow |
| Keywords | markdown, coffeescript, embed, interactive, notebook |

## Links

- npm: https://www.npmjs.com/package/biscotti
- Repository: https://github.com/pandastrike/biscotti
- Homepage: https://github.com/pandastrike/biscotti#readme
- Issues: https://github.com/pandastrike/biscotti/issues
- npm.io page: https://npm.io/package/biscotti

## Dependencies (3)

- [coffeescript](https://npm.io/package/coffeescript.md) ^2.3.2
- [panda-generics](https://npm.io/package/panda-generics.md) ^4.2.0
- [panda-parchment](https://npm.io/package/panda-parchment.md) ^4.2.0

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 3.0.0 (latest) — 2019-01-21
- 2.0.1 — 2018-04-14
- 2.0.0 — 2018-03-29
- 1.3.0 — 2018-03-29
- 1.2.2 — 2018-03-09
- 1.2.1 — 2018-03-09
- 1.2.0 — 2018-03-09
- 1.1.1 — 2018-03-08
- 1.1.0 — 2018-03-07
- 1.0.1 — 2018-03-07
- 1.0.0 — 2018-03-07

## README

# Biscotti

Like Legos for building domain-specific languages (DSLs).

For example, suppose we want an HTML DSL. We can implement one that uses CoffeeScript and VDOM like this:

```coffee
import {loader, fallback, buffer, include,
  filters, sandbox, engine} from "biscotti"
import {HTML} from "panda-vdom"

render = do ->

  globals = Object.assign {}, {require}, HTML

  engine [
    sandbox: sandbox globals
    loader
      coffeescript:
        index: true
        extensions: [ ".vhtml" ]
    do fallback
    include isBuffered: false
    buffer
    filters.string
  ]

export {render as default}
```

You could then call the resulting `render` function:

```coffee
# will load ./html/index.vhtml
render path: "./vhtml"
```

You _probably_ don't want to use this directly. Instead, check out the various engines we've written that use Biscotti:

- [biscotti-coffee](https://github.com/pandastrike/biscotti-coffee)
- [biscotti-cpp](https://github.com/pandastrike/biscotti-cpp)
- [biscotti-html](https://github.com/pandastrike/biscotti-html)
- [biscotti-css](https://github.com/pandastrike/biscotti-css)

## Usage

The `engine` function takes an array containing an initial definition of the engine and a list of mixins that will add capabilities to it. Typically, that initial definition defines the `sandbox` property, whose value must be a _sandbox_, which is a V8 VM. It returns a render function that takes an options object with either a `path` (and option `encoding`) or a `content` property.

## Mixins

Mixins include:

- `loader` - A dictionary of file types and descriptions for loading a file given a path. The `index` property determines whether to try adding `index` to the path. The `extensions` property is a list of extensions to try.

- `fallback` - Defines the assumptions to make if no path is given. The default is to assume a CoffeeScript file. You can pass an options object with a `language` property to provide a different fallback.

- `include` — Adds an `include` method to the sandbox's globals. This allows a given file to include another file using a relative path. Effectively allows for the equivalent of partials, or partial templates.

- `buffer` — Adds functions to the sandbox's globals allowing included files to add values to a buffer. This way you can return values from the files your engine processes. The `get` function returns the buffer, in case you want to manipulate it from within a file. The `append` function adds to it. The `$$` function is equivalent to `append`. The `$` modifies another function so that it's return value is appended to the buffer.

- `filters` — Includes various post-processing functions for transforming the buffer into a usable return value. `filters.string` converts each element into a string and appends it to single return string.

- `embedded` — Allows you to process arbitrary text, embedding code between delimiters. You must provide an options object with the delimiters as `open` and `close` (which will default to `open` if undefined).  

## Language Support

Biscotti supports JavaScript and CoffeeScript out of the box. You can add support for additional languages by adding definitions to the sanbox's generic `run` method. See the code for the [`sandbox`](./src/sandbox.coffee) and [`embedded`](./src/embedded.coffee) mixins for examples.

---
_Source: https://npm.io/package/biscotti · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._