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,44 +16,41 @@ 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 arguments. For example:
-STDIN redirection has precedence, then piped input, then a filename as an argument, and finally text strings as an arguments.
+
-
+    echo piped | $0 arguments.txt < stdin_redirection.txt
-  EXAMPLE:
+
-  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:
-
+  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.
-* 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.
+EOF
---------------------------------------------------------------------------
+    return
-
+  fi
-HERE
+
-exit
+  if [ -t 0 ]; then
-}
+    echo Running interactively, checking for arguments... >&2
-
+    if [ "$*" ]; then
-sprunge() {
+      echo Arguments present... >&2
-	if [ -t 0 ]; then
+      if [ -f "$*" ]; then
-	  echo Running interactively, checking for arguments... >&2
+        echo Uploading the contents of "$*"... >&2
-	  if [ "$*" ]; then
+        cat "$*"
-		echo Arguments present... >&2
+      else
-		if [ -f "$*" ]; then
+        echo Uploading the text: \""$*"\"... >&2
-		  echo Uploading the contents of "$*"... >&2
+        echo "$*"
-		  cat "$*"
+      fi | curl -F 'sprunge=<-' http://sprunge.us
-		else
+    else
-		  echo Uploading the text: \""$*"\"... >&2
+      echo No arguments found, printing USAGE and exiting. >&2
-		  echo "$*"
+      sprunge --help
-		fi | curl -F 'sprunge=<-' http://sprunge.us
+      return 1
-	  else
+    fi
-		echo No arguments found, printing USAGE and exiting. >&2
+  else
-		usage
+    echo Using input from a pipe or STDIN redirection... >&2
-	  fi
+    curl -F 'sprunge=<-' http://sprunge.us
-	else
+  fi
-	  echo Using input from a pipe or STDIN redirection... >&2
-	  curl -F 'sprunge=<-' http://sprunge.us
-	fi
 }