Sheldon
Sheldon is a Bash 4.3+ library that is intuitive and easy to use, developed with Test Driven Development (TDD).
Install / Use
/learn @housni/SheldonREADME
Sheldon - a Bash 4.3+ library
Sheldon is a Bash 4.3+ library that is intuitive and easy to use, developed using Test Driven Development (TDD).
- Bash 4.3+
- Uses Test Driven Development
- Intuitive
- Easy
Table of Contents
- Overview
- Install
- Getting Started
- Help/Manual
- Examples
- Special Variables
- Features
- Philosophy
- Developer
- Uninstall
- License
Overview
(Back to top) | Why Sheldon? ↓
Sheldon is named after Sheldon Cooper from The Big Bang Theory :)
As a DevOps Engineer, I had many Bash utility functions that I had written over the years. I kept sourcing the various files in order to use them. I then decided to put them all together into an easily usable way, and so, Sheldon was born. BAZINGA!
Sheldon is a combination of Bash functions that do a lot of the heavy lifting of common scripting tasks. The functions are implemented in pure Bash, where possible, without external dependencies. This ensures that if a dependency is missing in an environment, a command won't fail. While Bash might be relatively slow in execution, it's certainly going to run faster than if you had to first install a dependency and then use it.
For example, if you wanted to manipulate JSON objects during your CI build process, you might use jq, which is a fantastic tool. However, this usually involves installing jq and then using it. Sheldon can work with simple JSON objects which means, you wouldn't have any dependencies and you can use Sheldon without external dependencies (except gawk which is quite a common tool on most servers) to process your simple JSON objects. An example of this can be seen at examples/resolve_apache_conf/resolve_apache_conf.sh.
Why Sheldon?
Many Bash libraries and frameworks out there require you to learn a few specific conventions in order to use them. You usually can't install the framework and start coding without first getting familiar with a few of those conventions.
Sheldon is a simple, light-weight fella. You'll feel like you're using regular Bash except you'll be writing fewer lines of code because a lot of common complex tasks have already been implemented in this library with a lot more to come! All this makes Sheldon easy to use even for someone who only knows the basics of Bash.
Install
(Back to top) | Requirements ↓ | Install with GNU Make (recommended) ↓ | Install from Source ↓
There are various ways to install Sheldon. Install with GNU Make (recommended) is the recommended and easiest way. All the installation process does is, it copies the Sheldon library files to /usr/local, by default.
Requirements
- Bash 4.3+
- GNU Make (for the recommended installation method)
gawk(only if you plan to use theSheldon.Transform.JSON.loads()function)
Why Bash version 4.3? I wanted Sheldon to use associative arrays and the only way to do that without using eval (which I wanted to avoid as much as possible) is by passing arrays by reference which was a feature only introduced in version 4.3.
Install with GNU Make (recommended)
- Run linters and unit tests against the code (optional but recommended)
$ make check - Install to
/usr/local, by default$ make install - Start using Sheldon
Install from Source
- Clone the repo
$ git clone git@github.com:housni/sheldon.git - Copy it to
/usr/local/lib$ cp -r ./lib/sheldon /usr/local/lib - Start using Sheldon
Getting Started
(Back to top) | Basic ↓ | Advanced ↓
In order to start using Sheldon, you'll need to:
- Bootstrap
- Turn on "strict mode"
Bootstrapping is done by sourcing /usr/local/lib/sheldon/bootstrap.sh in your shell script and then, optionally but preferably, enabling "strict mode":
#!/usr/bin/env bash
# Sourcing Sheldons bootstrap file.
. /usr/local/lib/sheldon/bootstrap.sh
# Enable strict mode to prevent lazy code.
Sheldon.Core.Sheldon.strict
# Start using Sheldon here.
Strict mode is not required but it's very highly recommended. It will essentially cause Bash to warn you of things that could lead to potential bugs in your code like undefined variables. It will also cause your script to terminate in the case of a command exiting with a non-zero exit status.
Basic
(Back to top) | Getting Started ↑
In basic.sh below,, the String.join() function is used to combine space delimited text using a forward slash.
#!/usr/bin/env bash
# Sourcing Sheldons bootstrap file.
. /usr/local/lib/sheldon/bootstrap.sh
# Enable strict mode to prevent lazy code.
Sheldon.Core.Sheldon.strict
# Import Sheldons "String" module
import Sheldon.Util.String as String
declare path
declare -i length
# Join arguments passed into this script with '/'
path=$($String.join '/' $@)
# Get length of $path
length=$($String.length "$path")
echo "Path is '$path' with length '$length'."
exit 0
Output:
$ ./basic.sh foo bar baz
Path is 'foo/bar/baz' with length '11'.
Advanced
(Back to top) | Getting Started ↑
The examples/resolve_apache_conf/resolve_apache_conf.sh script is a well commented example that shows a relatively advanced use of Sheldon.
Help/Manual
See Sheldon > Projects > Documentation
Examples
Some useful examples:
Special Variables
__SHELDON is a special variable and is used internally so it should not be overwritten.
Features
(Back to top) | Simple JSON support ↓ | Makefile is friendly ↓ | Own test framework ↓ | Custom rule checker ↓ | Intuitive interface ↓ | Easy to use ↓
Simple JSON support
Using its JSON module, Sheldon can convert an associative Bash array into a simple JSON object using the Sheldon.Transform.JSON.dumps() function. Conversely, Sheldon can also convert a simple JSON object into an associative Bash array using the Sheldon.Transform.JSON.loads() function.
Makefile is friendly
The Makefile is very well documented and the help target has a lot to offer in terms of helping you figure out what the Makefile can do.
For more details, look at help or just type make HELP_TARGET=help help in your terminal while in the root directory.
Own test framework
Sheldon needed a simple yet effective way to run tests against its code base. Instead of using a full-blown test framework, I put together the TestFrameworkInAFile.sh script which is quite easy to use and lets you run setUp() and tearDown() before and after tests, respectively.
Custom rule checker
Sheldon developers have to follow a naming convention. As human beings, we will make mistakes which
