added helptext and some environmentals

1 files changed, 83 insertions, 9 deletions

diff --git a/bin/bin/makepass.zsh b/bin/bin/makepass.zsh
index 182317f..0d56c6a 100755
--- a/bin/bin/makepass.zsh
+++ b/bin/bin/makepass.zsh
@@ -1,5 +1,5 @@
 #!/usr/bin/env zsh
-emulate -L zsh
+emulate zsh
 # Filename:      ~/bin/makepass.zsh
 # Purpose:       Creating random passwords.
 # Authors:       Dennis Eriksen <d@ennis.no>
@@ -9,33 +9,107 @@ emulate -L zsh
 # This file takes randomness from /dev/urandom and turns it into random
 # passwords.
 ################################################################################
+#
+# This script relies on the following external commands, in addition to zsh:
+# `head`, `tail`, and `tr`. All three are used in a way which is defined in
+# POSIX.1-2017. This script should therefore work on *most* systems with zsh.
+#
+# head - https://pubs.opengroup.org/onlinepubs/9699919799/utilities/head.html
+# tail - https://pubs.opengroup.org/onlinepubs/9699919799/utilities/tail.html
+# tr   - https://pubs.opengroup.org/onlinepubs/9699919799/utilities/tr.html
+#
+# Copyright (c) 2018-2022 Dennis Eriksen • d@ennis.no
 
+function _makepass_help() {
+  local string='NAME
+    makepass - create several random passwords
 
-# Copyright (c) 2018-2022 Dennis Eriksen • d@ennis.no
+SYNOPSIS
+    makepass [OPTIONS] [NUM]
+
+    If a NUM is provided, the we will output passwords of that length.
+
+    By default `makepass` will output passwords from the three following classes:
+
+    - Normal passwords - 10 random strings with letters (both lower and upper
+      case), numbers, and dashes and underscores.
+
+    - Passwords with special characters - six random strings from the following
+      range: !#$%&/()=?+-_,.;:<>[]{}|\@*^A-Z-a-z-0-9
+
+    - Passphrases - if we find a dictionary, five series of eight random words
+      from the dictionary, separated by dashes. The number of words can not be
+      changed, but you do not have to use all of them. Use as mane as you want.
+
+DESCRIPTION
+    makepass has the following options:
+
+    -h
+        output this help-text
+
+ENVIRONMENT
+    makepass examines the following environmental variables.
+
+    MAKEPASS_DEFAULT_LENGTH
+        Specifies the default length of passwords. Valid values are "random"
+        (default), or a number. If "random", a random value between 8 and 42
+        will be used for each password. If `makepass` is run with a NUM as an
+        argument, that NUM overrides this variable.
+
+    MAKEPASS_NORMAL
+        Specifies the array of characters from which to generate "normal"
+        passwords. See below for valid values. Defaults to: _A-Z-a-z-0-9
+
+    MAKEPASS_SPECIAL
+        Specifies the array of characters from which to generate passwords with
+        special characters. See below for valid values. Defaults to:
+        !#$%&/()=?+-_,.;:<>[]{}|\@*^A-Z-a-z-0-9
+
+    MAKEPASS_WORDLIST
+        Specifies the dictionary we find words for passphrases in. If this is
+        unset or empty, we try "/usr/share/dict/words". If that file does not
+        exist, no passphrases will be provided.
+
+ABOUT CHARACTER ARRAYS
+    makepass uses `tr` to translate and/or delete characters. Therefore, values
+    that would be valid for `tr` is valid for makepass. This includes
+    character-classes like [:alnum:] and [:print:].
+
+AUTHOR
+    Dennis Eriksen <https://dnns.no>'
+
+  print -- $string
+  return 0
+}
 
 # makepass-function. This is where the magic happens
 function makepass() {
-  setopt local_options
-
+  MAKEPASS_DEFAULT_LENGTH=${MAKEPASS_DEFAULT_LENGTH:-random}
+  MAKEPASS_NORMAL=${MAKEPASS_NORMAL:-'_A-Z-a-z-0-9'}
+  MAKEPASS_SPECIAL=${MAKEPASS_SPECIAL:-'!#$%&/()=?+-_,.;:<>[]{}|\@*^A-Z-a-z-0-9'}
   MAKEPASS_WORDLIST=${MAKEPASS_WORDLIST:-/usr/share/dict/words}
   RANDOM=$(head -n 10 /dev/urandom | tr -cd '[:digit:]' | tail -c 10) # seed RANDOM
 
+  local -i len
+
   # Some error-checking
   # We only take one argument
-  (( ARGC > 1 )) && print "only one argument" && return 1
+  (( ARGC > 1 )) && print -u2 -- "only one argument\nmaybe try running \`makepass -h\` for help" && return 1
+  # if $1 == -h
+  [[ $1 == '-h' ]] && _makepass_help && return 0
   # if $1 is not empty and is not a number
-  [[ ! -z "$1" && ! $1 = <1-> ]] && print "not a number above 0" && return 1
+  [[ ! -z "$1" && ! $1 = <1-> ]] && print -u2 -- "not a number above 0\nmaybe try running \`makepass -h\` for help" && return 1
 
-  local -i len=$1 # is automatically 0 if $1 is unset or not a number
+  [[ $MAKEPASS_DEFAULT_LENGTH == <0-> && -z $1 ]] && len=$MAKEPASS_DEFAULT_LENGTH || len=${1:-0}
 
   # Normal passwords
   print "Normal passwords:"
-  (repeat 10 _random $len '_A-Z-a-z-0-9') | column
+  print -c -- $(repeat 10 _random $len $MAKEPASS_NORMAL)
   print
 
   # Passowrds with special characters
   print "Passwords with special characters:"
-  (repeat 6 _random $len '!#$%&/()=?+-_,.;:<>[]{}|\@*^A-Z-a-z-0-9' true) | column
+  print -c -- $(repeat 6 _random $len $MAKEPASS_SPECIAL true)
 
   # Passphrases - but only if a wordlist is available
   if [[ -r "$MAKEPASS_WORDLIST" ]]; then