Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

Whack Red is an entire development suite for client-side WHATWG/W3C web and server-side NodeJS projects using the ShockScript language.

Whack Red implements a reactive UI model — called Whack DS — over the DOM with support for a more intricate and dynamically inserted CSS dialect during runtime.

The manifest format

This section describes the manifest format file whack_red.toml, placed at a project’s root directory.

A manifest may describe a package and a workspace simultaneously.

Example

[package]
name = "me.matt.eval"
version = "0.1.0"
runtime = "http://www.w3.org/1994/web"

[compiler-options]
main-class = "me.matt.eval.Main"

Package section

[package]
# The package ID.
#
# Patterns (may use subnamespaces):
#
# - `com.<company>.<project-name>`
# - `org.<organisation>.<project-name>`
# - `net.<organisation>.<project-name>`
# - `me.<author>.<project-name>`
# - `goog.<project-name>`
# - `<project-name>`
#
name = "com.company.project-name"

# SemVer-compatible version number.
#
version = "0.1.0"

# Target platform.
#
# Supported values:
#
# - "http://www.w3.org/1994/generic"
#   - Compatible with web and NodeJS.
# - "http://www.w3.org/1994/web" (web browser)
# - "http://www.nodejs.org/2009" (NodeJS)
#
runtime = "http://www.w3.org/1994/javascript"

# Author list.
#
authors = ["matt <me@matt.me>"]

# Homepage URL.
#
homepage = "https://project.com"

# Source repository URL.
#
repository = "https://github/example/project"

# License type.
#
# Examples:
#
# "MIT", "Apache-2.0", "MIT OR Apache-2.0"
#
license = "MIT OR Apache-2.0"

# Description.
#
description = "Package description."

# Keywords.
#
keywords = []

# Categories.
#
categories = []

# Files to exclude/include when publishing.
# (Similiar to .gitignore entries, possibly with an exclamation prefix.)
#
ignore = []

# Shared objects (.so or .dll) to contribute alongside
# the program. This may be used when creating
# native applications, by combining the Tauri technology
# with client-side Whack Red.
#
# Entries in this option can interpolate `{target}`
# for the arfifact directory.
#
# Entries not found here are ignored; for instance,
# you could have a .dll on Windows, but not on other platforms.
#
shared-objects = [
    "{target}/so/org.makers.plus/libcore.so",
]

# Plain metadata ignored by Whack Red
[package.metadata]
plain = 0

Workspace section

[workspace]
members = [
    "packages/foo",
    "packages/bar",
]

Dependencies sections

# Dependencies.
#
[dependencies]
me.matt.foo = "0.1"
me.matt.bar = { path = "../bar", version = "0.1" }
# git dependencies may have a `rev`, `tag` or `branch` keys.
#
# rev examples:
#
# - rev = "4c59b707" (a commit by its SHA1 hash)
# - rev = "refs/pull/493/head" (HEAD commit of PR 493)
#
# tag examples:
#
# - tag = "1.10.3"
#
# branch examples:
#
# - branch = "master"
#
# If it's a workspace, then Whack Red will look for the
# matching member, inheriting any dependencies.
#
me.matt.qux = { git = "https://github.com/matt/qux", version = "0.1" }

# Development dependencies. *Used by unit-testing.*
#
[dev-dependencies]
com.alpha.lets-go = "1"

# Build dependencies. *Used by build scripts.*
#
[build-dependencies]
com.omega.game = "1"

# NPM dependencies, for internal use
# in Whack Red facade packages.
#
[npm-dependencies]
"decimal.js" = "1"

Compiler options section

[compiler-options]
# Directory at which to find ShockScript source files.
# (Defaults to "src".)
#
source-path = "src"

# Main component or class, for an application package.
#
main-component = "me.matt.eval.Main"

# following: "error", "warn" or "allow"
unreachable-code = "warn"
unused = "warn"

Terminal section

Used for contributing terminal applications, installable through whackred terminal install.

[[terminal]]
name = "mycmd1"
main-class = "me.matt.eval.terminal.MyCommand1"

[[terminal]]
name = "mycmd2"
main-class = "me.matt.eval.terminal.MyCommand2"

Unit-testing sections

[[test]]
# Test ID.
#
# This may be omitted if there is only one [[test]]
# section, defaulting to "test".
#
# This is required internally.
name = "test"

# Runtime. Accepts the same values as `application.runtime`.
#
# Defaults to "http://www.nodejs.org/2009".
#
runtime = "http://www.nodejs.org/2009"

# Directory at which to find ShockScript unit-testing source files.
#
# Defaults to "test" if there is only one [[test]] section.
#
source-path = "test/es4"

If there is no [[test]] section and there is a test directory, then a virtual [[test]] section is added with the default options.

Formatting section

[formatting]
# Number of spaces per indentation-level.
#
# Default: 4
tab-width = 4

# Use tabs for indentation?
#
# Default: false
use-tabs = false

# Insert semicolons after statements?
#
# Default: true
#
semicolon = true

# Use single quote strings were appropriate?
#
# Default: false
#
single-quote = false

Application section

The application section is reserved for visual-interactive application frameworks.

[application]
# Human name (`en` is the default locale).
human-name."en" = "Application 1"
human-name."pt" = "Aplicativo 1"
# Description
description."en" = "Description"
description."pt" = "Descrição"
# Frames per second.
framerate = 30
# Background color.
background = "#fff"
# App-installation resources directory.
#
# This is used by the `app:` scheme for resolving
# assets from the app's installation directory.
#
# Default: res.
#
resources = "res"

# For web projects, indicates the
# absolute path of the web project in its host.
#
wwwroot = "/"

[application.initial-window]
# Window size
width = 800
height = 600

EyeExp

The architecture for icons and logotypes is called EyeExp.

The whack.eyexp.* package contains an EyeExp singleton-like instance which is accessed like a Map for getting, setting and deleting icons or logotypes. Setting an entry causes Whack to re-render dependent eyexp() functions in CSS. An entry consists of an URL and a monochrome boolean.

Monochrome resources are displayed filled with the CSS (?inherited) color property. Non-monochrome resources may be displayed with a very discrete shadow whose color is the CSS (?inherited) color, but that is an explicit shadow attribute that only works on <w:EyeExp/> components and not things like CSS background: eyexp(...);.

  • The <w:EyeExp/>’s shadow attribute only takes effect on non-monochrome resources.
  • The <w:EyeExp/> accepts size (square), width and height. The two latter are often most used for logotypes.

The convention is for EyeExp entries to have a name based on enum names, such as light_spark. enum types are not actually used as icons and logotypes have a very dynamic nature.

Some examples:

import whack.eyexp.EyeExp;


// EyeExp : EyeExpSingleton


EyeExp.flower = { url: Embed("flower.svg"), monochrome: true };


// e4x

(
    <w:EyeExp name="flower" size={37}/>

    <!-- as a css background -->

    <div s:background="eyexp(flower) noRepeat center / contain"
         s:width={37]
         s:height={37}/>
)

Runtimes

Dependency compatibility

Dependencies of incompatible runtime are forbidden.

  • The runtime http://www.w3.org/1994/generic is compatible with:
    • http://www.w3.org/1994/web
    • http://www.nodejs.org/2009

Environment variables

Environment variables used by the Whack Red SDK

  • WHACKRED_HOME - Path to the Whack Red SDK.

Environment variables Whack Red sets for packages

These environment variables are available for use with env::VAR_NAME expressions within Whack Red packages, their build scripts and unit-testing classes.

env::WHACKRED_MANIFEST_DIR
  • TARGET - Path to the artifact target directory based on platform and build profile.
  • WHACKRED_MANIFEST_DIR - Path to the directory containing the manifest of your package.
  • WHACKRED_MANIFEST_PATH - Path to the manifest file of your package.
  • WHACKRED_PKG_NAME - Package name.
  • WHACKRED_PKG_VERSION - Package SemVer version number.
  • WHACKRED_PKG_VERSION_MAJOR - Package major version number.
  • WHACKRED_PKG_VERSION_MINOR - Package minor version number.
  • WHACKRED_PKG_VERSION_PATCH - Package patch version number.

Using static DotEnv variables

For setting static DotEnv variables for ShockScript to use, create an .env file in your package’s directory, with contents like:

FOO=bar

You can then refer to that in ShockScript with expressions like:

env::FOO