floe v0.0.1

Floe

This project is in the planning stages. The specification for this project is in flux and development has not begun.

Floe is an extendable build tool that leverages it's own Domain-specific language and interpreter.

Getting Started

Already know what you're doing? Skip to the Table of Contents.

Installation

To install

npm install -g floe

Your First Steps

Floe is built on, primarily, two concepts: steps and tasks. A step is the basic element of all Floe Scripts, and a task is a way to group related steps together.

For our first Floe Script we'll watch for file changes and print a log each time a file is changed. Start by creating a new file called my-first-script.floe and populating it with the contents below.

0.1

import "core" as core

@emit
step core.file-watcher $watcher {
  directory: "./"
}

@listen $watcher
step core.print {
  print: "Changed!"
  print: $watcher.changedFiles
}

So, what is this doing?

The first line of our script tells Floe the file's syntax version is 0.1. Next we import the core floe library. This dependency is bundled with the floe executable.

We create a step that will execute our file-watcher function and name it $watcher. We specify that this particular step can emit events. Each time a file changes that we're watching floe will "emit" this event to any steps that are listening. The file-watcher function requires a single parameter—the directory to watch.

Last, we create another step that listens to the $watcher step. This step simply prints the file(s) that changed.

To run your first Floe Script you'll need to have floe installed globally, then from the command line you can run,

floe run ./my-first-script.floe

Your First Task

Let's take our previous print statement and abstract it to a task. We'll create a new file called print-utilities.floe

0.1

import "core" as core

task file-printer {
  parameter $files {
    required: true
  }
  
  step core.print {
    print: "Changed!"
    print: $files
  }
}

Wrapping our original print step in a task {} creates a task we can reuse anywhere in our project. We required that in this scope we expect a $files parameter to be passed in.

We're almost done! By default tasks are exported, so we can now import this in our original my-first-script.floe file.

0.1

import "core" as core
import "./print-utilities" as print-utilities <-- We import our new module here.

@emit
step core.file-watcher $watcher {
  directory: "./"
}

@listen $watcher
step print-utilities.file-printer {           <-- We use our task like we would any other step!
  files: $watcher.changedFiles
}

If executed the output will yield the same as before. While this was a fruitless abstraction we did learn how to abstract steps to a task!

Learn More

View the documentation's Table of Contents to learn more of the basics and some advanced topics.