While the bc command is extremely well known, there's little awareness of its competitor Spigot. Nevertheless, all it takes is a quick read of the manual and a few sample sums to start using this simple tool. The program borrows its name from the eponymous algorithm for calculating mathematical constants. However, there are other programs with the same name, which can be rather confusing. The software was developed by Simon Tatham [1].

The source for Spigot is available from [2], but you are better off simply installing it with your trusty apt software manager:

sudo apt install spigot

To test the installation, enter spigot 1 + 2 in the terminal. If you see the correct answer, the installation has worked. There's an online manual for Spigot [3] that contains further information on getting started.

General Information

One of Spigot's specialities is that it can display a virtually infinite number of decimal places. Try entering spigot pi in the terminal, and you'll see that the number of digits will scroll past indefinitely until you press Ctrl+C.

To distinguish negative input values from options and commands, place your calculations inside quotation marks and brackets (Figure 1). You can do away with these for positive numbers. At the very least, however, you should always place tasks inside commas in order to avoid confusing the shell. When using variables, you need to remove brackets because of the shell.

Figure 1: The way you input positive and negative numbers is slightly different.

For day-to-day use, you'll need to limit the number of decimal places and round values off. You can set the degree of accuracy with -d<digits> . This truncates numbers, but does not round them up or down. The rounding is determined by another set of parameters. Table 1 summarizes the main Spigot options. See Figure 2 for examples.

Figure 2: Rounding off numbers is one of Spigot's standard operations.

To display the output in a specific format, put the appropriate printf statement at the end of an input. You can find out more about the various operators with man printf . Spigot's mathematical functions, such as square root (sqrt ), are the same as those used by common programming languages. Spigot follows the order of operations in which multiplications and divisions are executed first, then additions and subtractions, and so on.

Just like bc , spigot cannot read directly from a pipe. Instead, you tell the program which input channel to read a value and the base that the number will be in. Put statements together as follows:

spigot base<base>fd:<file descriptor>

For example, the command

echo 11 | spigot base7fd:0

will spit out 8 , because fd:0 is standard input (i.e., in this case, a pipe), and 11 in base 7 is 8 in decimal.

To read the value from a file instead, use the following statement:

spigot base<base>file:<filenameI>

For example, the instruction

spigot base2file:number.txt

will read the number contained in the file number.txt and assume it is in base 2. It will spit out the number converted to decimal.

When used in a script, enclose variables in double quotes whenever they appear in a statement.

Working with Variables

Listing 1 shows how to include variables in a Spigot statement. Negative numbers are used here. The individual options include round (- rn ), cap at 50 decimal places (-d50 ), and an example of formatted output (-printf for 8 non-decimal digits and 2 decimal digits for a floating point number are also in Listing 1).

#!/bin/bash
echo "Calculating with Spigot and Variables"
read -p "First number: " a
read -p "Second number: " b
echo "Results without formatting"
echo "----------------------------"
spigot --rn -d50 \("$a"*"$b"\)
spigot --rn -d50 \("$a"/"$b"\)
echo "Results with formatting"
echo "----------------------------"
spigot --rn -d50 \("$a"*"$b"\) --printf %8.2f
spigot --rn -d50 \("$a"/"$b"\) --printf %8.2f

Figure 3 lists the commands in a script. You must either call it in the bash script or assign permissions to make it executable.

Figure 3: A small shell script demonstrates some features of Spigot, including the use of shell variables as part of a statement.

Conversion

Spigot supports conversion between numbering systems using various kinds of syntax. The command shown here will work in every case:

echo <valueI> | spigot -b<output_base> ,base
<input_base>fd:0'

Figure 4 shows common usage examples.

Figure 4: You can convert numbers using Spigot in several different ways.

Calculating Frequency

The example from Listing 2 shows how to deal with variables as exponents. Here you see that the variables are isolated by quotes; the e-12 describes the exponent's remainder. Use the script to calculate the frequency of a resonant circuit using the coil (Inductance , ?H ) and the capacitor (Capacitor , pF ). See Figure 5 for the script's output.

#!/bin/bash
# qrgcalc.sh
echo "Resonant circuit calculation, result in MHz"
read -p "Inductance in ?H: " L
read -p "Capacitor in pF: " C
echo "Inductance: $L ?H, Capacitor $C pF"
# In the header, correct conversion for ISO units to H and F
echo "------------------------------"
qrg=$(spigot --rn -d50 "$L"e-6*"$C"e-12 | spigot --rn -d50 '(1/(2pi*sqrt(base10fd:0))/1000000)' --printf %10.3f)
echo "Frequency $qrg MHz"

Figure 5: Spigot helps calculate the frequency of a resonant circuit.

Variables within Variables

A very useful feature is including the symbols for operations (+, -, *, /, etc.) within a variable. As you may get negative numbers in random operations, remember to enclose variables inside brackets (Listing 3). Figure 6 shows the output enclosed within commas.

#!/bin/bash
# calculator.sh
read -p "First number: " a
read -p "Operation: " op
read -p "Second number: " b
echo -n "$a $op $b returns"; spigot --rn -d50 \($a$op$b\) --printf %10.2f

Figure 6: You can save operation symbols within a variable.

Plotting Results

You can modify the circuit script to output results and plot a graph. For example, You can measure tuneable resonant circuits (frequency variation using a variable capacitor). In the example in Listing 4, both Pi (pi ) and the square root function (sqrt ) are used too.

#!/bin/bash
# vfo.sh
# Delete any existing results table
rm resultstab.txt
clear
echo "Calculation of tuning range LC oscillating circuit"
echo "------------------------------------------------- "
read -p "                   coil:inductance in ?H: " l
read -p "   Rotary capacitor: highest value in pF: " cmax
read -p "     Rotary capacitor:lowest value in pF: " cmin
# cmin decrease by 1 in a for loop
cmin=$(echo $cmin | spigot 'base10fd:0-1')
for ((c=cmax; c>cmin; c--))
do
  qrg=$(spigot --rn -d50 "$l"e-6*"$c"e-12 | spigot --rn -d50 '(1/(2pi*sqrt(base10fd:0))/1000000)' --printf %10.3f)
  echo "$c $qrg" >> resultstab.txt
done
gnuplot -p -e "plot 'resultstab.txt' using 1:2"

The for loop specifies the maximum value for capacitance (cmax ) of the variable capacitor, which is reduced by one, until the minimum value (Cmin ) is reached. The results (values for capacity and frequency) are placed in a table. Using gnuplot [4], the script then creates a diagram, which is displayed on the screen. You will need to install the gnuplot and plotutils packages for this to work. Figure 7 shows the script's output.

Figure 7: Spigot not only calculates data, but also displays it as a graph if necessary.

Conclusion

Spigot is a powerful calculation tool, although some of the operating concepts initially seem cumbersome. However, once you have familiarized yourself with the features, you can even perform complex calculations in the blink of an eye using automated scripts.