duckscript

duckscript

Simple, extendable and embeddable scripting language.

• Overview
  • Language Goals
• Installation
  • Homebrew
  • Binary Release
• Duckscript Tutorial
  • Hello World Example
  • Commands
    • Passing Arguments
    • Storing Output
    • Using Variables - Binding
    • Using Variables - Spread Binding
  • Labels
  • Comments
  • Pre Processing
    • !include_files
    • !print
  • Standard API
    • Commands Instead Of Language Features
    • Full SDK Docs
  • Final Notes
• 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]

!include_files

The include_files command enables you to load script files into the position of the pre processor command.

Basically it enables you to include many scripts and generate one bigger script for runtime.

The include files command accepts any number of files and all will be loaded by the order they are defined.

For example:

# load the hello_world.ds script here
!include_files ./hello_world.ds

# load 2 scripts here. The hello_world.ds is loaded again.
!include_files ./hello_world.ds ./use_variable.ds

Important to note that the script paths included are relative to the script file including them and not to the current working directory.

!print

The print pre processing command allows to print any number of arguments, which could be useful for debugging.

In the following example, although the print command comes after the echo command, it will execute first as it is invoked in the parsing phase and not in the script execution phase which comes later:

# this will print "Hello World during script execution"
echo Hello World during script execution

# this will print "Hello World during parsing"
!print Hello World during parsing

Standard API

Duckscript is split to several modules and while the script runner does not require it, by default it will come with the standard duckscript API called the duckscript SDK.

This SDK holds the most common commands, some which execute actions (such as echo) and some which serve as flow control (such as function).

The SDK enables users to develop their scripts and have a good starting point without the need to develop the commands on their own (as that is a bit more complex).

Commands Instead Of Language Features

As mentioned before, duckscript is really simple and only has few basic rules.

In order to provide a more richer development experience, common language features such as functions and conditional blocks have been implemented as commands.

This is an example of the function command:

fn print_first_and_second_argument
    echo ${1} ${2}
    return printed
end

fn run_flow
    status = print_first_and_second_argument Hello World
    echo The printout status is: ${status}
end

run_flow

This example demonstrates how functions as a concept do not need to be part of the language and can be implemented by anyone as a command.

This also means that other developers can replace the function command with their implementation to provide additional/different functionality.

Below an example of loops using the for/in command:

values = range 1 10

for i in ${values}
    for j in ${values}
        echo i: ${i} j: ${j}
    end
end

release ${values}

Below an example of if/else command:

echo Enter Full Name:
name = read

if is_empty ${name}
    echo You did not enter any value
else
    echo Your name is: ${name}
end

value = set false
if ${value}
    echo should not be here
elseif true or false
    echo in else if but not done yet

    value = set true

    if not true and false
        echo nested if

        value = set "some text"

        if starts_with ${value} "some"
            echo after command
        else
            echo should not be here
        end
    end
else