shellia(7)

📦
version 5.10 · 4 versions
, in ubuntu resolute, ubuntu stonking

🎀 Name 🎀

okay so you clicked on shellia(7), the page from the shell library section, and bestie you're gonna love it 💖

shellia — a library for interactive shell scripts. periodt.

✨ SYNOPSIS ✨

. /usr/share/shellia/ia[.interactive|.check|.debug|]

💖 NAME 💖

shellia is a library that lets you run shell scripts interactive. and like, interactive is genuinely the most characteristic adjective for shellia, no cap — and the shortest abbreviation anybody could come up with for interactive is ia. why does it need to be that short? because most of the commands shellia brings to the party start with that tiny little prefix ia 🎀.

and the name itself? shellia is composed from shell and ia. it's giving portmanteau, it's giving branding, it's giving icon behavior 💅

also go peek at PREFIX in shellia(3) for the deets.

🌸 DESCRIPTION 🌸

shellia is a library that lets you run shell scripts silently or interactive, and it helps you check errors of commands that are combined in steps 🫶

this makes it easy to familiarize yourself with a shell script that uses shellia and find unexpected behaviour in the shell script. and when you're running the shell script silently, shellia can still check it step by step 💅

Shell scripts often become large with many subfunctions, calling many commands. and that leads to the following problems, where shellia can help:

  • It is not easy to run only parts of the script, to learn about an existing script, to find an error in a script, to change the order of parts of the script for testing, or to rerun only a part of the script that failed. 😭
  • It is not easy to find out, from which part of the script errors, warnings or messages that appear on stdout or stderr are created. and it is often not clear if output of a shell script is ok and can be ignored. 🙈
  • Often commands are started in a shell script without checking for Errors because this would make the scripts too complex. 💀
  • Many programs can only enable debug at start time. this can result in much debug output, also if only specific debug output is needed.

The shellia library can help with the following features:

  • run a script or parts of a script interactively ✨
  • check each command for unexpected output or returncode 🔍
  • jump to interactive mode if an error occurs or exit the script 🚪
  • helps to structure large scripts 🧚
  • in interactive mode shellia can toggled the debug output level 🎚️

🦋 NOTES 🦋

When building a ./script.using.shellia the following hints may be helpful:

🎀 Do not use a single command as a step 🎀

It is important to find the right size of a step to be uses in shellia. The idea of a step is not to check the execution of a single command. Instead a single command can be part of a function, that is called by a step. like, a step is a whole vibe, not a one-liner ✨

🎀 Input and Output of a step 🎀

Each step should be interactively runable by an end user of the script. This means the end user should be able to handle input and output of a step. This often means a step should not read stdin or send stdout to another step. For example a backup script could have one step to backup /home and another step to backup /usr. But a step that reads data from work disk and another step that writes backup data to a backup disk should better be combined in a single step. 🫶

🎀 Reasonable size of interactive steps 🎀

If the user of the script can not imagine what an interactive step does, this step may be to detailed and to small. If to many errors may happen in the interactive step, the step may be to large. For example, if you need to mount an external disk, this should be a separate interactive step. Because this can give errors, if the disk is not readable. And this errors can again lead to follow up errors. 😭

🎀 When to use check option -c and -C 🎀

Both options will check the output and the exit code of a step. All output has to be allowed with extended regular expressions in check-mode. To be able to control the exit code in the same way, the line exit=<exit code> (with <exit code> replace by the exit code), will be added, if the exit code is nonzero.

With option -c, per default every output to stdout and stderr is seen as one output and is displayed as an error. The developer can change this with ia_stdout and ia_ignore. This means with -c every output is checked, also output that would normally go to stdout. This makes it easy to find changed output from a command used, e.g. when upgrading to a new operating system version. 👑

With option -C, per default every output to stdout is unchanged and all output to stderr is seen as an error. The developer can ignore error output with ia_ignore. This means the developer has not to handle stdout, which can be good and bad. 😬

If a step calls a program, that produces stdout and stderr output, and it is most important to retain the order of the output, option -c should be used. With option -c the output of both streams would be combined by shellia to one stream. If it is important to know if output is from stdout or from stderr to decide if it is an error, option -C should be used. 💅

🎀 Use --quiet, --silent or similar if available 🎀

If commands are used with check option -c or -C, less ia_stdout or ia_stderr lines have to written, if the commands create less output. lowkey the move, fr fr 🤫

⭐ EXAMPLE ⭐

For example imagine a backup script, that writes to an external disk, that should then contain an encrypted and bootable backup.

This script may call the following steps, that are itself functions in the script.

The main part of the script could look like this:

   eval "$ia_init"
   ia_add "opencrypt <-i>"
   ia_add "mountbkup <-i>"
   ia_add "synccopy"
   ia_add "lvcopyvms <-i>
   ia_add "fixcrypttab"
   ia_add "fixfstab"
   ia_add "prepare_chroot"
   ia_add "fixinitrd"
   ia_add "run_grub"
   ia_add "clean_chroot"
   ia_add "umountbkup <-i>"
   ia_add "closecrypt <-i>"
   ia -C

🌈 SEE ALSO 🌈

shellia(1), shellia(3)

👑 Author 👑

bernd.schumacher@hpe.com

License: GNU General Public License, version 3

Bernd Schumacher <bernd.schumacher@hpe.com> (2007-2020)

and that's the whole page bestie 🫶 this was shellia(7), version 0.1, dated 2020-08-07, and yes we are obsessed with it 💖✨🎀🦋

📦 where this page comes from