Writing the Bible

Adding Code to the Bible.

  • The code must use only bash built-ins.
    • A fallback to an external program is allowed if the code doesn’t always work.
    • Example Fallback: ${HOSTNAME:-$(hostname)}
  • If possible, wrap the code in a function.
    • This allows tests to be written.
    • It also allows shellcheck to properly lint it.
    • An added bonus is showing a working use-case.
  • Write some examples.
    • Show some input and the modified output.

Special meanings for code blocks.

Use sh for functions that should be linted and unit tested.

  1. ```sh
  2. # Shellcheck will lint this and the test script will source this.
  3. func() {
  4.     # Usage: func "arg"
  5.     :
  6. }
  7. ```

Use shell for code that should be ignored.

  1. ```shell
  2. # Shorter file creation syntax.
  3. :>file
  4. ```

Writing tests

The test file is viewable here: https://github.com/dylanaraps/pure-bash-bible/blob/master/test.sh

Example test:

  1. test_upper() {
  2.     result="$(upper "HeLlO")"
  3.     assert_equals "$result" "HELLO"
  4. }

Steps:

  1. Write the test.
    • Naming is test_func_name
    • Store the function output in a variable ($result or ${result[@]}).
    • Use assert_equals to test equality between the variable and the expected output.
  2. The test script will automatically execute it. :+1:

Running the tests

Running test.sh also runs shellcheck on the code.

  1. cd pure-bash-bible
  2. ./test.sh