Quickstart Tutorial

We will create a simple script greet that allows the following calls to it:

$ greet hello "World"
Hello, World!
$ greet hi "you"
Hi, you!

This is the kind of project, bashing is best suited for: having multiple so-called tasks (in our case hello, hi, ...) accessible using a common top-level script (greet). This tutorial applies to:

$ bashing version
bashing 0.1.4 (bash 4.2.25(1)-release)

Initializing the Project

This is easy. Go to the location you want to create your project directory in and call:

$ bashing new greet
Initializing ./greet ...
Successfully initialized './greet'.
$ cd greet

Your project will have the following structure:

$ tree --dirsfirst
.
├── src
│   ├── hidden-tasks
│   ├── lib
│   └── tasks
│       └── hello.sh
└── bashing.project

4 directories, 2 files

As you can see, a dummy task named hello is already created. You can run it immediately (without first creating a standalone script, that is):

$ bashing run hello
Hello, World!

Library Files

The directory ./src/lib is meant for dependencies. The files included within will be placed before any task in the standalone script, making them easily available. Ideally, they should not have any side-effects when called (e.g. printing, file creation, ...) but of course they can do whatever they want.

Libraries can depend on each other, since Bash's top-level definitions (variable, functions, ...) reside in a global dynamic scope, making them readable/callable to anything once they are declared.

We will use a simple library function - placed inside of ./src/lib/print.sh - to built the string <Greeting>, <Recipient>! from two input parameters:

#!/bin/bash

function printGreeting() {
    local g="$1"
    local r="$2"
    echo "${g}, ${r}!"
}

Tasks

Now, let's modify src/tasks/hello.sh to use the library function:

#!/bin/bash
printGreeting "Hello" "$1"

Test it immediately using:

$ bashing run hello "dude"
Hello, dude!

bashing's run task is probably the one you might use a lot during development since it enables you to dynamically and instantaneously check the result of any changes you made to your tasks.

You can add a new task either by creating a file ./src/tasks/<task>.sh or by using bashing's new.task:

$ bashing new.task hi
Created Task 'hi'.
$ bashing run hi
Hello from Task 'hi'

Modify ./src/tasks/hi.sh to read:

#!/bin/bash
printGreeting "Hi" "$1"

And run it:

$ bashing run hi "my friend"
Hi, my friend!

Generate a standalone Script

To generate the single-file greeting tool of your dreams, issue the following command:

$ bashing uberbash
Creating /git/public/shell/greet/target/greet-0.1.0-SNAPSHOT.sh ...
Uberbash created successfully.

You can have a look at the file ./target/greet-0.1.0-SNAPSHOT.sh and you will see that it consists of a little bit of metadata, followed by our library function printGreeting and the two tasks we designed, encapsulated in functions (this is why task scripts have certain restrictions). Finally, there is a function __run that dispatches to the right task using the first (remaining) element on the command line. (Tasks are run in the background to prevent them from killing the script if an error occurs.)

Let's call our script:

$ cd target
$ ./greet-0.1.0-SNAPSHOT.sh
Usage: greet <task> [...]

    hello    :  (no help available)
    help     :  display this help message
    hi       :  (no help available)
    version  :  display version

That's nice, isn't it. Bashing has already created a help message for us detailing which tasks are available. Now, what about their functionality?

$ ./greet-0.1.0-SNAPSHOT.sh hello "you"
Hello, you!
$ ./greet-0.1.0-SNAPSHOT.sh hi "man"
Hi, man!

Finally a convenient way to greet people!

Installing Projects

To copy an uberbash script to ~/.bin use the install task. Provided you added that directory to your $PATH the script will then be available anywhere:

$ bashing install
Creating /git/public/shell/greet/target/greet-0.1.0-SNAPSHOT.sh ...
Uberbash created successfully.
Deploying to /home/yannick/.bin/greet ...
Deployed successfully.

$ greet
Usage: greet <task> [...]

    hello    :  (no help available)
    help     :  display this help message
    hi       :  (no help available)
    version  :  display version

$ greet hi "nice to meet you"
Hi, nice to meet you!

Help Strings

You can add custom help messages to tasks by including a line with # <help>...</help> into their source file. Let's do this for our hello and hi tasks:

#!/bin/bash
# <help>says hello</help>
printGreeting "Hello" "$1"

#!/bin/bash
# <help>says hi</help>
printGreeting "Hi" "$1"

Now, run uberbash and call the script:

$ ./target/greet-0.1.0-SNAPSHOT.sh
Usage: greet <task> [...]

    hello    :  says hello
    help     :  display this help message
    hi       :  says hi
    version  :  display version