gosh -- the gopher shell

I wrote this program on 2025-06-16 and 2025-06-17 in an attempt to write
a minimal gopher browser.

When you run the browser, you will see a > prompt. Enter the domain of a
gopherhole you want to visit. The browser will send the empty selector
(= "list all you have") to the server on port 70. (There is no way to
enter other selectors or ports manually, but this would be an easy
extension.) When the browser has received the gophermap, it will page it
to you and number the selectors. Once you reach the bottom of the
gophermap, you will see the > prompt again.

You can now enter the empty string (just hit return) to view the
gophermap again. Or you can enter one of the numbers to follow that
selector. Or you can enter the domain of a new gopherhole you want to
visit.

When you follow a selector that is marked as a text item (item type 0),
the browser will page it to you unaltered. When you follow a selector
that is marked as a gophermap (item type 1), the browser will page it to
you just like it did with your first gophermap, with numbered links. For
all other item types, you will see a ? prompt. In that case, enter a
line of shell script (which can be simply the name of a viewing
program); the browser will pipe the item into that shell script. (If you
enter the empty string, nothing will happen and you will be brought
right back to the > prompt.) Once you see the > prompt, you can enter
the empty string to view the item again (with a new ? prompt if it is
neither a text item nor a gophermap), just like with your first
gophermap.

To go back in your browsing history, enter the letter b when you see the
> prompt. You can flip through your entire browsing history this way, no
matter how long it is, as soon as you have fetched at least two items.
(Once you reach the first item you have ever fetched, the order becomes
weird because the browser shoves back all newer items behind it when you
go back. But this is only an aesthetic matter and harmless.)

What happens under the hood is that the browser stores its state in the
~/.gosh directory, in three files: a data file, a history file, and a
type file. Whenever you fetch an item, the browser stores it in the data
file (overwriting the previous contents) and writes the item type to the
type file. It also appends the item type, the selector, host, and port,
as well as a current timestamp to the history file. (The history file is
in the format of a regular gophermap. The timestamp is only included for
manual inspection; the mechanism to go back in the browsing history
works independently of it.)

This means that the browser stores its entire state on the disk, and not
in memory. Whenever you see the > prompt, it is as if you had just shut
down and started the browser again. So when you shut down the browser
after a browsing session, boot up your machine the next day, start up
the browser again, and then enter the empty string at the > prompt, you
will view the most recently fetched item again, as if you had fetched it
just a second ago. You can also go back in your browsing history beyond
the most recent session.

This also means that whenever you view a fetched item again and again
and again, there will be no network requests, but going back in your
browsing history will make new network requests (because there is no
caching beyond the single data file).

There is no mechanism in the browser to save items you like. Instead,
you can go to the ~/.gosh directory and just copy the data file to
whatever place you like. You can also inspect the file in case of
encoding issues or the like. (Allowing more than the builtin pager for
text items and gophermaps would be an easy extension.)

The history file is reordered whenever you go back in your browsing
history, but you run sort -k1.2 on it see it in chronological order
(because of the included timestamps).

You can quit the browser by entering the letter q when you see the >
prompt, or by hitting ^D there. ^C gives you a fresh > prompt instead of
shutting down the browser. (In this regard, the browser is similar to a
shell.) (When you see the ? prompt, hitting ^C at any time, or ^D when
you have not entered anything yet, will stop the viewing routine and go
back to the > prompt, as if you had entered an empty shell line.)

Keep in mind that after viewing a non-text item (with the ? prompt), you
have to go back in your browsing history to see the gophermap that
brought you to that item. The browser does not do this automatically.
This is so that you can view the item again if you like, or copy the
data file before it is overwritten with the gophermap.

                                                            Daniel Kalak
                                                              2025-06-17