$ cats nobody@supertxt.net:options-arguments-tables.s.txt

# Options, Arguments, ... and Tables!

Writing tables in plain text is hard. It's hard because there are tradeoffs between ease of composition and reading. Some formats amount to writing the table using a kind of ASCII art, which almost looks like typeset table, but if you need to insert something in the middle it can be time consuming to re-align everything. One of the easiest tables to compose is using CSV (Comma-Separated Values), but it can become really dense, making reading more difficult with any variability to the width. For small tables this can be an acceptable compromise, especially if the columns have no semantic meaning.

this starts,to go,off the rails

Browsers can take any of these formats and render a grid with perfect alignment. Here we are concerned with cases where you don't have a browser, such as when you're looking at the source, or composing it. HTML oddly composes tables as trees with a hierarchy.


There are other popular table formats out there too, such as TSV (Tabbed-Separated Values), and its new variant LTSV (Labeled Tabbed-Separated Values), making use of tabs as the column delimiter, the latter making labels a feature of each cell, while repetitive, helps to identify the column more easily in the middle of a large file (e.g. log files). A potential tradeoff is that tabs aren't always easy to type in certain environments.

this	is	a	TSV
id:1	country:DE	comment:This is a labeled TSV

All of these tabular formats have tradeoffs, which can be well suited for specific situations. Here we will introduce a new format that can be useful in other situations, Shell Word Values (SWV). The separator is one or more whitespaces, except for the newline. The values are the "words," which includes any sequence of non-whitespace characters, including numbers. Each word is a positional argument that relates values in the same position between rows.

one two three
four five 6

So, what happens if the word has a space in it? The argument value can be grouped together using double-quotes, like this:

"Jane Doe" "1145 Nowhere Lane"
"Paul May" "82 Somewhere Street"

Escaping the double-quote character inside a word is done with a "\" character. Otherwise, everything between the two double-quotes is the argument value. As with the TSV format it can become difficult in large files with variable width values to remember what that data represents. Is it the name, or the address? Option values provide a label with each value to help with the clarity.

--name="Jane Doe" --address="1145 Nowhere Lane"
--address="82 Somewhere Street" --name="Paul May"

Option values can provide some flexibility in the order within the row, as compared with argument values. They begin with one, or two dashes "-", along with the name of the option. The equal sign is the separator for the value of the option.

note: Since option values are named and position independent there can be multiple value for the same option within a row.

It's technically possible to have option names that have whitespace in them, or capitalization. Use of single words, or snake case is encouraged. If it's not possible then options can be encapsulated within double-quotes.

"--Full Name=Jane Doe" --Address="1145 Nowhere Lane"
--full_name="Paul May" --address="82 Somewhere Street"

Options that represent simple boolean (true/false) values can be recorded as flag values. Their presence on a particular row indicates yes/true/1, and their absence indicates the opposite no/false/0/null.

--task="Mow Lawn" -done
--task="Cook Meal"

With flag and option values that start with the dash, how do you represent a positional argument that happens to being with that character due to a bit of bad luck? In that case you can insert a special double-dash that disables option and flag parsing for the remainder of the row.

-- -10+50

If this format seems familiar, it is a subset of the Unix shell command-line format. Here it is being applied to each row of a tabular format, with a familiar set of tradeoffs. In particular, shell words are designed to be both fairly easy to type and to read in a row, at the cost of visual alignment between rows.

One last thing about the semantics of the SWV. It's often the case that tables reserve the final column for a short description of the row. In the case where a row has only a single positional argument at the end, it is considered to be an option value called "description." This is usually the concern of a tool that understands semantics, such as a browser that might render the table in a grid with column headings, or a query engine.

--lat=82 --lon=28 "Buried Treasure"
--lat=46 --lon=55 "Home Sweet Home"

This new format for tables felt like a good fit within the SuperTXT ecosystem since it aligns with a foundational OS concept of the shell. Learning how to make tables like this also helps one to compose commands at the shell level, which in turn helps to understand how to use commands to browse the internet, and how hyperlinks work. The network effects can be really effective, but we still encourage everyone to use the right tools for the job. This format has its tradeoffs and hopefully it will be useful in certain cases. The best part is that you can start today with a single .swv file and your favorite text editor. With some interest the tools will come.

ssh nobody@supertxt.net ccmnt options-arguments-tables.s.txt <<EOF
suggestion: Here's my actionable suggestion.