phd/README.md at 99178d51d9f63beaa7a33a80d40208a252659cb4

mirror of https://github.com/xvxx/phd synced 2024-11-04 18:00:22 +00:00

dvkt 99178d51d9 indent

2020-01-06 11:37:07 -08:00

4.8 KiB

Raw Blame History

phd is an esoteric gopher server for small gopherholes.

point it at a directory and it'll serve up all its text files, sub-directories, and binary files over gopher. any .gph files will be served up as gopermaps and executable .gph files will be run as a script with their output served to the client, like cgi!

special files:

header.gph: if it exists in a directory, its content will be shown above the directory's content. put ascii art in it.
footer.gph: same, but will be shown below a directory's content.
index.gph: completely replaces a directory's content with what's in this file.
??.gph: visiting gopher://yoursite/1/dog/ will try to render dog.gph from disk.
.reverse: if this exists, the directory contents will be listed in reverse alphanumeric order. useful for phloggin'.

any line in a .gph file that doesn't contain tabs (\t) and doesn't start with an i will get an i automatically prefixed, turning it into a gopher information item.

dynamic content:

any .gph file that is marked executable with be run as if it were a shell script and its output will be sent to the client. it will be passed three arguments: the query string (if any, the host, and the port. do with them what you will.

for example:

$ cat echo.gph
#!/bin/sh
echo "Hi, world! You said:" $1
echo "1Visit Gopherpedia	/	gopherpedia.com	70"

then:

$ gopher-client gopher://localhost/1/echo?something
[INFO] Hi, world! You said: something
[LINK] Visit Gopherpedia

or more seriously:

$ cat figlet.gph
#!/bin/sh
figlet $1

then:

$ gopher-client gopher://localhost/1/figlet?hi gopher
[INFO]  _     _                     _
[INFO] | |__ (_)   __ _  ___  _ __ | |__   ___ _ __
[INFO] | '_ \| |  / _` |/ _ \| '_ \| '_ \ / _ \ '__|
[INFO] | | | | | | (_| | (_) | |_) | | | |  __/ |
[INFO] |_| |_|_|  \__, |\___/| .__/|_| |_|\___|_|
[INFO]             |___/      |_|

ruby on rails:

sh is fun, but for serious work you need a serious scripting language like Ruby or PHP or Node.JS:

$ cat sizes.gph
#!/usr/bin/env ruby

def filesize(file)
    (size=File.size file) > (k=1024) ? "#{size/k}K" : "#{size}B"
end

puts "~ file sizes ~"
spaces = 20
Dir[__dir__ + "/*"].each do |entry|
    name = File.basename entry
    puts "#{name}#{' ' * (spaces - name.length)}#{filesize entry}"
end

now you can finally share the file sizes of a directory with the world of Gopher!

$ phetch -r 0.0.0.0:7070/1/sizes
i~ file sizes ~	(null)	127.0.0.1	7070
iCargo.toml          731B	(null)	127.0.0.1	7070
iLICENSE             1K	(null)	127.0.0.1	7070
iMakefile            724B	(null)	127.0.0.1	7070
itarget              288B	(null)	127.0.0.1	7070
iphd                 248K	(null)	127.0.0.1	7070
iCargo.lock          2K	(null)	127.0.0.1	7070
iREADME.md           4K	(null)	127.0.0.1	7070
img                 96B	(null)	127.0.0.1	7070
isizes.gph           276B	(null)	127.0.0.1	7070
isrc                 224B	(null)	127.0.0.1	7070

usage

Usage:

    phd [options] <root directory>

Options:

    -p, --port      Port to bind to.
    -h, --host      Hostname to use when generating links.

Other flags:

    -h, --help      Print this screen.
    -v, --version   Print phd version.

Examples:

    phd ./path/to/site  # Serve directory over port 7070.
    phd -p 70 docs      # Serve 'docs' directory on port 70
    phd -h gopher.com   # Serve current directory over port 7070
                        # using hostname "gopher.com"

installation

binaries for linux, mac, and raspberry pi are available at https://github.com/dvkt/phd/releases:

just unzip/untar the phd program into your $PATH and get going!

development

cargo run -- ./path/to/gopher/site

resources

todo

script/serverless mode
systemd config, or something
TLS support
man page
ipv6

4.8 KiB Raw Blame History