spigot

What is it?

The tool merely interprets the (unlimited number of) controls specified on the command line as it goes through the file. The controls turn the "tap" on and off.

You could think of "spigot" as a simple version of expect and cat and head, all rolled into one.

License:

Documentation?

% spigot -h

The controls are:

-show <num>		Show <num> lines (or 'all')
-skip <num>		Skip <num> lines
-off <regex>		Turn off display when <regex> is seen
-on <regex>		Turn on display when <regex> is seen
-ON		Just turn on unconditionally (similar to '-on .')
-OFF		Just turn off unconditionally
-do "<cmd>"		Execute a command
-echo "<string>"		Print a line

Examples:

% spigot somefile

It's just a very silly way to do a 'cat'

-show and -skip allow us to process the file by numbers of lines. So we can show just the first 15 lines of a file (similar to 'head') with:

% spigot somefile -show 15

In this case, spigot set our initial state was 'off' because we started with a -show. If you wanted to, you could be redundant with:

% spigot somefile -OFF -show 15

Once the first 15 lines are shown, spigot is smart enough to realize that it can stop reading the file because nothing else is going to be printed.

spigot is smart enough to figure out the start state. It's generally on, except for the controls that presume that it starts as off, specifically '-show' and '-on'

We can also skip lines. To only show the third and fourth lines of a file:

% spigot somefile -skip 2 -show 2 -OFF

We needed to remember to turn off the 'tap' after the last -show, because there's nothing turning it off here. -skip and -show don't actually change the permanent state of the 'tap,' they just change it temporarily.

We can also turn the "tap" on and off based on file contents. If we want to show everything in a file except for the footer, and we know the footer has started when we see a line that starts with "Copyright" then we can:

% spigot file -off '^Copyright'

If we want to do the same, but we still want to see the copyright line, then just add in a control to show that line:

% spigot file -off '^Copyright' -show 1

The "tap" will turn off when it sees '^Copyright' - but then temporarily turn back on for one line (the Copyright line) and then go back off again.

We can do the reverse, and skip a header of a file, for example, only showing everything including and after we see a line with 'START'

% spigot file -on START

And again, if we don't want to see the 'START' line we can add in a skip:

% spigot file -on START -skip 1

As a more complicated example, lets show the first four lines of a file, then everything from when we find 'ERROR MSG' until the first blank line is found:

% spigot log -show 4 -on "ERROR MSG" -off '^$'

Finally, we have the ability to insert text into the file using -echo and -do. Here we simply echo borders around a specific line we're looking for:

% spigot log -off WARNING -echo ======== -show 1 -echo ======== -ON

Note that we are only using -off to find the line, because we are using -show 1 and -ON we actually don't ever turn off the spigot.

We can also run a command. As a simple example, replace the line "DATE" with the actual date:

% spigot log -off DATE -skip 1 -do "date" -ON

Or replace "INCLUDE-HERE" with contents of file "include.txt"

% spigot log -off INCLUDE-HERE -skip 1 -do "cat include.txt" -ON

One thing to note is that "-ON" will turn on the spigot and continue to process, so something like this won't work:

% spigot file -ON -echo "END OF FILE"

What you really want is:

% spigot file -ON -show all -echo "END OF FILE"

Future Plans: