Macrame enables running a time intensive function in the background while the script displays an animated ‘working’ spinner. There are several spinner styles to choose from and all spinner text is customizable using the MacrameText methods.

#Quickref

$macrame = new Macrame();

// an example function to run with a spinner
$wait = function($seconds) {
    sleep($seconds);
    return "a value";
};

$result = $macrame->spinner()->run($wait, [1]); // mixed. default spinner. returns 'a value'

$spinner = $macrame->spinner();
$result = $spinner->run($wait, [1]); // mixed. default spinner. returns 'a value'

$result = $macrame->spinner->prompt("enter text: ")->run($wait, [1]) // mixed. adds prompt to spinner

$result = $macrame->spinner("star")->run($wait, [1])                   // mixed. use a different spinner animation
$result = $macrame->spinner->colour("red")->run($wait, [1])            // mixed. sets colour red
$result = $macrame->spinner->color("red")->run($wait, [1])             // mixed. synonym for colour
$result = $macrame->spinner->backgroundColour("red")->run($wait, [1])  // mixed. sets background colour red
$result = $macrame->spinner->backgroundColor("red")->run($wait, [1])   // mixed. synonym for backgroundColour
$result = $macrame->spinner->style("bold")->run($wait, [1])            // mixed. sets style bold
$result = $macrame->spinner->speed("fast")->run($wait, [1])            // mixed. sets animation speed

#Creating a spinner

Spinners are created and run using the MacrameSpinner class returned from Macrame’s spinner() method.

$spinner = $macrame->spinner();

The spinner() method accepts the name of the custom spinner as an optional argument. If no argument is provided, the default spinner is used.

#Running a function with a spinner

The purpose of the spinner feature is to allow script writers to run a function ‘in the background’ while displaying an animated spinner to the user.

Setting and running a function with a spinner is done with the run() method.

$result = $macrame->spinner()->run($function, $argsArray);

The run() method accepts two arguments:

• The function to run as callable
• An optional array of arguments to pass to the function

The return value of run() is the return value of the passed function.

$macrame = new Macrame();

$wait = function($seconds) {
    sleep($seconds);
    return "a value";
};

$result = $macrame->spinner()->run($wait, [1]); // "a value"

The above example will display the default animated spinner to the user for one second and return the value “a value” to the variable $result.

To use the method of an object as the callable argument to run(), pass it as a two-element array of the object and a string of the method name:

class someClass {
    public function wait(Int $seconds):String
    {   
        sleep($seconds);
        return "a value";
    }   
}

$someObject = new someClass();

$result = $macrame->spinner()->run([$someObject, 'wait'], [1]);

#Choosing a spinner animation

Macrame offers a number of different spinner animations. To use a spinner animation, pass its name as a string argument to the spinner() method:

$macrame->spinner('star'); // use the 'star' spinner animation

The available spinner animations are:

#Adding custom text to the spinner

A custom string can be prepended to the spinner animation by using the prompt() method.

$macrame->spinner()->prompt("please wait ");

#Styling the spinner

The spinner animation and the optional prompt can be styled using the styling methods from MacrameText.

For example, to have a bold, red spinner on a white background

$macrame->spinner()->colour('red')->style('bold')->backgroundColour('white');

For more details on styling, refer to the MacrameText documentation page.

#Setting the animation speed

The speed of the animation can be set using the speed() method.

The speed() method accepts as an argument one of:

• 'slow'
• 'medium'
• 'fast'
• 'very fast'

$macrame->spinner()->speed('fast')

the default speed is ‘slow’.