sprunge: add README and refactor (#8239)

Co-authored-by: Marc Cornellà <marc.cornella@live.com>

plugins/sprunge/README.md

@@ -0,0 +1,31 @@
+# Sprunge plugin
+
+This plugin uploads data and fetch URL from the pastebin http://sprunge.us
+
+To enable it, add 'sprunge' to your plugins:
+```
+plugins=(... sprunge)
+```
+
+## Usage
+
+| Command                      | Description                               |
+|------------------------------|-------------------------------------------|
+| `sprunge filename.txt`       | Uploads filename.txt                      |
+| `sprunge "this is a string"` | Uploads plain text                        |
+| `sprunge < filename.txt`     | Redirects filename.txt content to sprunge |
+| `echo data \| sprunge`       | Any piped data will be uploaded           |
+
+Once sprunge has processed the input it will give you a unique HTTP address:
+```
+$ sprunge "hello"
+http://sprunge.us/XxjnKz
+```
+
+## Notes
+
+- Sprunge accepts piped data, stdin redirection, text strings as input or filenames.
+  Only one of these can be used at a time.
+- Argument precedence goes as follows: stdin > piped input > text strings.
+- If a filename is mispelled or doesn't have the necessary path description, it will NOT
+  generate an error, but instead treat it as a text string.

plugins/sprunge/sprunge.plugin.zsh

@@ -2,12 +2,9 @@
 # Created by the blogger at the URL below...I don't know where to find his/her name
 # Original found at https://www.shellperson.net/sprunge-pastebin-script/
 
-usage() {
+sprunge() {
-description | fmt -s >&2
+  if [[ "$1" = --help ]]; then
-}
+    fmt -s >&2 << EOF
-
-description() {
-cat << HERE
 
 DESCRIPTION
   Upload data and fetch URL from the pastebin http://sprunge.us
@@ -19,27 +16,23 @@ USAGE
   piped_data | $0
 
 NOTES
---------------------------------------------------------------------------
+  Input Methods:
-* INPUT METHODS *
+  $0 can accept piped data, STDIN redirection [< filename.txt], text strings following the command as arguments, or filenames as arguments. Only one of these methods can be used at a time, so please see the note on precedence. Also, note that using a pipe or STDIN redirection will treat tabs as spaces, or disregard them entirely (if they appear at the beginning of a line). So I suggest using a filename as an argument if tabs are important either to the function or readability of the code.
-$0 can accept piped data, STDIN redirection [<filename.txt], text strings following the command as arguments, or filenames as arguments.  Only one of these methods can be used at a time, so please see the note on precedence.  Also, note that using a pipe or STDIN redirection will treat tabs as spaces, or disregard them entirely (if they appear at the beginning of a line).  So I suggest using a filename as an argument if tabs are important either to the function or readability of the code.
 
-* PRECEDENCE *
+  Precedence:
-STDIN redirection has precedence, then piped input, then a filename as an argument, and finally text strings as an arguments.
+  STDIN redirection has precedence, then piped input, then a filename as an argument, and finally text strings as arguments. For example:
 
-  EXAMPLE:
+    echo piped | $0 arguments.txt < stdin_redirection.txt
-  echo piped | "$0" arguments.txt < stdin_redirection.txt
 
-In this example, the contents of file_as_stdin_redirection.txt would be uploaded. Both the piped_text and the file_as_argument.txt are ignored. If there is piped input and arguments, the arguments will be ignored, and the piped input uploaded.
+  In this example, the contents of file_as_stdin_redirection.txt would be uploaded. Both the piped_text and the file_as_argument.txt are ignored. If there is piped input and arguments, the arguments will be ignored, and the piped input uploaded.
 
-* FILENAMES *
+  Filenames:
-If a filename is misspelled or doesn't have the necessary path description, it will NOT generate an error, but will instead treat it as a text string and upload it.
+  If a filename is misspelled or doesn't have the necessary path description, it will NOT generate an error, but will instead treat it as a text string and upload it.
---------------------------------------------------------------------------
 
-HERE
+EOF
-exit
+    return
-}
+  fi
 
-sprunge() {
   if [ -t 0 ]; then
     echo Running interactively, checking for arguments... >&2
     if [ "$*" ]; then
@@ -53,7 +46,8 @@ sprunge() {
       fi | curl -F 'sprunge=<-' http://sprunge.us
     else
       echo No arguments found, printing USAGE and exiting. >&2
-		usage
+      sprunge --help
+      return 1
     fi
   else
     echo Using input from a pipe or STDIN redirection... >&2