Home

Welcome to the Panda-9000 wiki.

The Panda 9000 is a reactive task framework, similar to Gulp or Grunt, except built on top of the Fairmont functional reactive programming (FRP) library.

Table of Contents

• Installation
• Usage
• Defining Tasks
• Helpers
• Reactive Programming
• Motivation
• Design
• API Reference
• Status

Installation

npm install -g panda-9000

Usage

p9k [<task-name>...]

If no arguments are given, the default task name is used.

Task definitions should be placed in the tasks/index directory.

Defining Tasks

To define tasks, place a CoffeeScript or JavaScript file in your project's task/index.coffee or tasks/index.js file.

For example, here's a simple hello, world task.

{task} = require "panda-9000"

task "hello-world", ->
  console.log "Hello, World"

Run the task like this:

p9k hello-world

Helpers

Panda-9000 provides a variety of built-in helpers you can use in tasks. Helpers are designed to be used within reactive flows using the Fairmont FRP library.

For example, here's a simple task that will take a list of CoffeeScript files in the src directory, compile them, and then write them out to lib with a .js extension.

{go, async, map, glob} = require "fairmont"
{task, context, coffee, write} = require "panda-9000"

task "coffee", async ->
  yield go [
    glob "**/*.coffee", "src"
    map context "src"
    tee coffee
    tee write "lib"
  ]

Run the task via the command-line, as before:

p9k coffee

See the API references for more details.

Reactive Programming

Panda-9000 tasks are typically defined as reactive flows using the Fairmont FRP library. You can read the Fairmont wiki to learn more.

Motivation

FRP provides a strong basis for composing collection operations. This can trivially be extended to handle asset pipelines. For example, here is a reactive flow, without any pipeline-specific code, for compiling Jade assets into HTML.

go [
  glob "**/*.jade"
  map (path) -> jade.compileFile path
  map apply
]

We can build on this by adding task helpers (ex: jade) and task dependency analysis. We no longer need a separate set of abstractions for defining tasks.

With Panda-9000, adding some helpers and a function for defining tasks, our example above looks like:

task "compile-jade", ->
  go [
    glob "**/*.jade", source
    map context source
    tee jade
    tee write target
  ]

This builds naturally on the foundation provided by Fairmont rather than requiring a completely separate set of abstractions (and codebase).

Design

Panda-9000 adds three pieces to the FRP foundation provided by Fairmont:

• reusable task helpers, for common actions like compiling Jade templates

• a task runner, which takes into account task dependencies

• a shared context object that allows helpers to interoperate

Tasks are typically defined as flows that include one or more helpers, each of which updates the context object. So a compilation helper might set the target.content property of the context object, which, in turn, is used by a helper that writes the content to a file.

Helpers have side-effects—namely, updating the context object. The advantage is increased modularity and possibilities for composition of helpers..

Reference

Panda-9000 Helpers are simply functions that take a task context as an argument and, optionally, modify it. They do not need to return the context as a result: the updated context is the result.

Some helpers may require properties be set on a task context before they will run. Others guarantee that certain properties will be set.

Task Context

source

Description of the source of an asset. May include path, extension, name, and content attributes.

target

Description of the target of an asset. May include path, extension, name, and content attributes.

path

The path of a source or target or the relative path of an asset (independent of source or target).

When used as a relative path, the extension is not included. This is so that subsequent helpers can construct a new (target) path using the relative path.

Example

• The context helper creates an initial context from a path. It sets the source property (including the path of the source), but also sets the path of the context itself to the relative path to a given directory.

• The jade helper uses the source.path to read the asset from a file.

• The write helper sets the target.path if it hasn't already been set.

directory

The directory of a source or target.

name

The name of a source or target.

extension

The extension of a source or target, including the period. Ex: .jpg.

content

The content associated with a source or target. May be a string or a readable stream.

Helpers

context path

Returns new context object given a path.

Sets: path, name, source.path, source.directory, source.name, source.extension.

Example

go [
  glob "src", "**/**.coffee"
  map createContext
  tee compileCoffee
  tee writeFile "lib"
]

write directory, context

Write a file based on the given directory and the target property of a given context.

Requires: target.content with either target.path or path and target.extension

Sets: target.path, unless it's set already.

jade context

Compile a Jade asset described by the source property of the given context.

Requires: source.content or source.path (from which to read the content).

Sets: target.content.

stylus context

Compile a Stylus asset described by the source property of the given context.

Sets: target.content.

coffee context

Compile a CoffeeScript asset described by the source property of the given context.

Sets: target.content.

Status

The Panda-9000 is currently alpha status, meaning it's under heavy development and not yet suitable for production use.