php-faketerm/SCRIPTING.md

# FakeBash Scripting

## Understanding the parser

The parser is CSV-based, and as such does not care about unquoted spaces.
For that reason, the following two examples are the same:

    write "Hello World"
    write H e l l o " " W o r l d
    write "Hello " World

You can use unicode with the syntax `u{CODE}`:

    write u{26c4} " A snowman!"

### Conventions

* Annotations are prefixed with an at-sign (`@`)
* Bookmarks are prefixed with a percent sign (`%`)
* Comments start with a hash sign (`#`) and cover the entire line


## Commands

### annotate - Add an anotation

Annotations can be added to point to any cell in the virtual terminal.

    annotate @useful-tip "This is a useful tip\nthat spans 2 lines"
    delay 2000
    unannotate @useful-tip

Annotations doesn't need to have a name and may have a position:

    annotate "This will annotate char 5 on line 1" 0 4

You can also use bookmarks for positioning the annotations:

    mark %where
    ...
    annotate "This will annotate the bookmark %where" at %where

### clearannotate - Remove all annotations

Removes all annontations in one go.

    clearannotate

### cursor - Cursor display control

Controls cursor visibility and rendering style. Use `cursor show` and
`cursor hide` to toggle the visiblity of the cursor. 

    cursor show
    cursor hide

You can configure the cursor blink rate, f.ex. setting it to 500ms with 
`cursor blink 500`, or change its style using `cursor style` followed by
the desired style.

    cursor blink <rate>
    cursor style {none|block|under|left}

To push (save) the current cursor position, use `cursor push`. Move
wherever and do what you need, followed by `cursor pop`. Don't forget
to pop if you push!

    cursor push
    cursor pop


### delay - Wait for time to pass

Only useful if you have `set fps` to a non-zero value, this command will
simulate time passing and render any frames needed.

    delay 100

### log - Log debug info

This command just sends output to the console for debugging.

    log "The parameter is " $1

### mark - Set a bookmark

    mark %here

### moveto - Go to position or bookmark

    mark %somewhere
    write "Hello"
    moveto %somewhere
    write "Goodbye"
    
    moveto 0 0

### savepng - Save the terminal as a png

    savepng output.png

### set - Set options

The `set` command is used to configure Faketerm.

Terminal-related:

    set terminal 80x25      # Width and height of window

Typing related:

    set typedelay 250       # Delay in ms when using the type command
    set typejitter 100      # Random amount of +/- ms when using type

Animation:

    set fps 30              # Enable rendering of frames
    set video out.mp4       # Convert frames to a video/gif

Annotations:

    set annotationsize 3    # Font size for annotations


### sub - Subroutine

The `sub` command defines a subroutine, all the way up to the
`endsub` command. Subroutines can take indexed arguments. The
arguments are not checked, and empty arguments are replaced with
empty strings.

    sub hello
        write "Hello, " $1 <return>
    endsub

    hello "World"

### type - Simulate typing to the fake terminal

This command works just like `write`, only it writes character by character.

    type "Hello World"

### unannotate - Remove an annotation

Removes an annotation

    unannotate @id

### write - Write to the fake terminal

Write output to the current cursor position of the virtual terminal. Extra 
tags can be added as arguments, but be aware there are no closing tags.

    write <sgr bold> "Hello World" <sgr> <return>

Supported tags are:

    <sgr> - Set output style, no parameters resets style.
    <home> - Move to the beginning of the current line
    <move> - Move the cursor
    <erase> - Erase line or screen
    <return> - Move to the beginning of the next line

### writefile - Write a file to the fake terminal

This command writes the output of a file line by line to the fake terminal
with an optional delay between each line.

    writefile "command-output.txt" 100

## Write and Type tags

The following can be used with the <sgr> tag:

    sgr fg:<color>
        bg:<color>
        bold
        underline

The following with the <move> tag:

    move [steps] <direction>

The following with the <erase> tag:

    erase {screen|to-eol|to-bol|to-top|to-bottom}