Working on getting READMEs up to snuff

Author: fileformat

bin/build.sh

@@ -19,17 +19,28 @@ if [ ! -d "${DIST_DIR}" ]; then
 	mkdir "${REPO_DIR}/dist"
 fi
 
-FILES=$(ls "${REPO_DIR}/cmd")
+CLEAN=1
+FILES=("$@")
+if [ ${#FILES[@]} -eq 0 ]; then
+	echo "INFO: no files specified, building all files in ${REPO_DIR}/cmd"
+	CLEAN=0
+	FILES=($(ls "${REPO_DIR}/cmd"))
+fi
 LASTMOD=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 COMMIT=$(git rev-parse --short HEAD)
 if [[ $(git diff --stat) != '' ]]; then
 	COMMIT="${COMMIT}-dirty"
 fi
 
-for f in $FILES; do
+for f in "${FILES[@]}"; do
 	if [ -f "${DIST_DIR}/${f}" ]; then
-		echo "WARNING: file ${DIST_DIR}/${f} already exists"
-		continue
+		if [ ${CLEAN} -eq 1 ]; then
+			echo "INFO: removing existing file ${DIST_DIR}/${f}"
+			rm "${DIST_DIR}/${f}"
+		else
+			echo "WARNING: file ${DIST_DIR}/${f} already exists"
+			continue
+		fi
 	fi
 	echo "INFO: compiling ${f} to dist directory"
 	go build \

cmd/hosty/hosty.go

@@ -0,0 +1,4 @@
+package hosty
+
+func main() {
+}

cmd/urly/README.md

@@ -0,0 +1,45 @@
+# urly
+
+Get a URL into the specific form required by a program without regular expressions or custom parsers.
+
+## Usage
+
+The URL can be passed on the command line or in an environment value specified with `--url-env`.
+
+The component (see table) can be set with the corresponding flag, or deleted with `-no-XXX` flag.
+
+```
+┌─────────┬───┬──────────┬──────────┬─┬────────────────┬─┬──────┬──────────┬─┬──────────────┬─┬──────────┐
+│ scheme  │   │ username │ password │ │   hostname     │ │ port │  path    │ │    query     │ │ fragment │
+│  https   ://    user   :   pass    @  sub.example.com :  8080   /p/a/t/h  ?  query=string  #  hash     │
+└────────────────────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+Password input is different: for security reasons, it should not be passed on the command line.  You can pass
+it in via stdin with `--password-stdin` or set it via the environment with `--password-env`.  Username can also
+be passed via the environment with `--username-env`.
+
+Query string parameters are a little different: they can be set with `--setparam` or added with `--addparam` or
+deleted with `--delparam`.
+
+The output can be the complete URL or a specific component with the `--output` flag.  You can also output the
+complete parsed URL as formatted JSON with `--output=json` or a single line JSON with `--output=jsonl`.
+
+## Exit Status
+
+The program will exit with an errorlevel if it cannot parse the URL.
+
+## Examples
+
+Combine username and password from the environment to make a complete URL:
+```
+urly --username-env=DB_USER --password-env DB_PSWD "postgres://pgdbhost.example.com/db?sslMode=required"
+```
+
+## Standards
+
+[RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986): Uniform Resource Identifier (URI): Generic Syntax
+
+## Security Considerations
+
+While urly does not accept passwords on the command line, it will output URLs with a password if specified.  Be careful with this output!

cmd/urly/urly.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	_ "embed"
 	"encoding/json"
 	"fmt"
 	"net/url"
@@ -17,6 +18,9 @@ var (
 	VERSION = "internal"
 )
 
+//go:embed README.md
+var helpText string
+
 func setUserName(userInfo *url.Userinfo, username string) *url.Userinfo {
 	if userInfo != nil {
 		password, hasPassword := userInfo.Password()
@@ -101,9 +105,6 @@ func aliasFunc(f *pflag.FlagSet, name string) pflag.NormalizedName {
 	return pflag.NormalizedName(name)
 }
 
-// Detailed help text
-var helpText = `urly: A URL parsing and processing tool.`
-
 func main() {
 
 	var scheme = pflag.String("scheme", "", "Set the URL scheme")
@@ -151,8 +152,7 @@ func main() {
 	if *help {
 		fmt.Println("urly - manipulate URLs")
 		pflag.PrintDefaults()
-		fmt.Println()
-		fmt.Println("Use `man urly` for detailed help.")
+		fmt.Printf("%s\n", helpText)
 		return
 	}
 

cmd/wombat/README.md

@@ -0,0 +1,3 @@
+# wombat
+
+Test your terminal endpoints with a quick ASCII animation

cmd/wombat/wombat.go

@@ -2,9 +2,11 @@ package main
 
 import (
 	"fmt"
+	"os"
 	"time"
 
 	. "github.com/FileFormatInfo/fftools/internal"
+	"github.com/spf13/pflag"
 )
 
 var (
@@ -16,6 +18,15 @@ var (
 
 func main() {
 
+	var version = pflag.Bool("version", false, "Version info")
+
+	pflag.Parse()
+
+	if *version {
+		fmt.Fprintf(os.Stdout, "wombat version %s (built by %s on %s, commit %s)\n", VERSION, BUILDER, LASTMOD, COMMIT)
+		return
+	}
+
 	oldState := Init()
 	defer Deinit(oldState)