duckscript

| duckscript | SDK | CLI | | ----------- | ------- | ----------- | | | | |

Simple, extendable and embeddable scripting language.

Overview
- Language Goals
Installation
- Homebrew
- Binary Release
Duckscript Tutorial
Duckscript Command Implementation Tutorial
- Commands
- Access The Context
Duckscript Embedding Tutorial
- Setting Up The Context
- Running The Script
Editor Support
Contributing
Release History
License

Overview

Duckscript is a simple, extendable and embeddable scripting language. The language itself has only few rules and most common language features are implemented as commands rather than part of the language itself.

Language Goals

Duckscript scripting language goals are:

Simple - This is probably the simplest language you will ever see.
Extendable - Instead of having common features such as functions and conditional blocks be a part of the language, they are actually part of the API. So they can easily be replaced/modified or you can add more 'feature' like commands on your own.
Embeddable - One of the main purposes of this language is to allow other libraries/executables/apps have scripting capability by embedding duckscript. Embedding is easy (for rust) and requires only few lines of code.

Installation

If you have rust, just run the following command

cargo install --force duckscript_cli

This will install duckscript script runner, the standard duckscript SDK and the duckscript CLI. You should then have a duck executable in your ~/.cargo/bin directory. Make sure to add ~/.cargo/bin directory to your PATH variable.

Homebrew

brew install duckscript

More details in the brew page

Binary Release

Binary releases are available in the github releases page. The following binaries are available for each release:

x86_64-unknown-linux-musl
x86_64-apple-darwin
x86_64-pc-windows-msvc

Duckscript Tutorial

The following sections will teach you how to write and run duck scripts.

Hello World Example

Let's take a really simple example (all examples are located in the examples directory:

# print the text "Hello World"
echo Hello World

Running this script is done using the duck executable as follows:

duck ./examples/hello_world.ds

We will understand more and break this down in the following sections.

Running the duck command without any arguments will open up the repl mode.

Commands

Commands are the basis of everything in duckscript. Commands may execute some action (like printing "Hello World" to the console) or serve as flow control (such as functions or if/else conditions). In order to invoke an action, simply write the action name:

echo

The basic syntax of a command line is:

[:label] [output variable =] [command [arguments]]

Passing Arguments

Commands may accept arguments, for example the command echo may accept any number of arguments and it will print all of them. Arguments are separated with the space character. So in the example:

# print the text "Hello World"
echo Hello World

The echo command got 2 arguments: "Hello" and "World". If your argument contains a space, you can wrap the entire argument with the " character as follows:

# print the text "Hello World"
echo "Hello World"

In which case the echo command got only one argument: "Hello World" and prints it. You can escape the " character using the "\" character, for example:

# print the text 'hello "world"'
echo "hello \"world\""

In the above example, the echo command got one argument: 'hello "world"' and prints it. The "\" is also used to escape the following:

\n - End of line
\r - Carriage return
\t - Tab character

Storing Output

Commands may return an output which can be stored in a variable. Variables in duckscript have no strict type. In the following example, the set command takes one argument and stores it in the out variable.

out = set "Hello World"

Duckscript has only global scope, so once you have stored a value in a variable, you may use it anywhere in your script.

Using Variables - Binding

Stored variables can be later on used as arguments for other commands. In order to use a variable, we need to wrap it as follows: ${variable}. The following example uses the set command to store a value in the out variable and then prints it:

out = set "Hello World"

# This will print: "The out variable holds the value: Hello World"
echo The out variable holds the value: ${out}

# This will print: "To use the out variable just write: ${out}"
echo To use the out variable just write: \${out}

In this example, although out holds the value Hello World which contains a space, it is still considered as a single input argument to the echo command. In the second echo command we prevented the variable name from being replaced by escaping it using the \ character.

Using Variables - Spread Binding

Spread binding provides a way to convert a variable value into multiple command arguments. For example:

out = set "Hello World"

The out variable holds the value "Hello World". If we were to create an array from it using the array command as follows:

list = array ${out}

The array would be of size 1 and its only entry value would be "Hello World". So it is the same as if we wrote:

list = array "Hello World"

But what if we want to split the value to multiple parts separated by spaces? For that we have the spread binding which is defined as follows: %{variable}. For example:

list = array %{out}

Which would act the same as:

list = array Hello World

And now our array is of size 2 with first entry "Hello" and second entry "World".

Labels

Labels are simple textual names you can give to a specific line. Commands like goto can then be used to make the script execution jump from its current position to the label position. For example:

goto :good

echo error!!!!

:good echo yay!!!!

Comments

Comments are not executed and are simply in the code for documentation purposes. A document line must start with the # character. You can also have a comment after the command and the command will ignore it. For example:

# This is just a comment

echo This will print # But this will not

Pre Processing

Pre processing is the phase that duckscript is parsing the script content. It is possible to run specific commands at that phase to modify the script during the parsing phase.

The basic syntax of a pre processing command line is:

!command [arguments]

<a name="tutorial-pre-processing-incl

Duckscript

Install / Use

README