From b3c431ed7a74f8dbe34ec5719d49027c5e5cfa01 Mon Sep 17 00:00:00 2001
From: Erich Smith <heartquest@gmail.com>
Date: Wed, 2 May 2012 16:50:02 -0400
Subject: [PATCH] improved help system refactored and renamed help functions:

glossary now shows all functions with 'about' metadata, like:

$ glossary

or, only functions by group, with:

$ glossary composure

reference () now shows apidoc help for specific functions, e.g.:

$ reference down4me
---
 lib/composure.sh | 222 ++++++++++++++++++++++++-----------------------
 1 file changed, 115 insertions(+), 107 deletions(-)

diff --git a/lib/composure.sh b/lib/composure.sh
index 359ab2cf..bf8465e0 100755
--- a/lib/composure.sh
+++ b/lib/composure.sh
@@ -1,10 +1,9 @@
 #!/bin/bash
 # Composure - don't fear the UNIX chainsaw...
+#             these light-hearted shell functions make programming the shell
+#             easier and more intuitive
 # by erichs, 2012
 
-# these are a set of light-hearted shell functions that aim to make
-# programming the shell easier and more intuitive
-
 # latest source available at http://git.io/composure
 
 source_composure ()
@@ -19,17 +18,27 @@ source_composure ()
       bind '"\C-j": edit-and-execute-command'
     fi
 
+    # define default metadata keywords:
+    about ()   { :; }
+    group ()   { :; }
+    param ()   { :; }
+    author ()  { :; }
+    example () { :; }
+
     cite ()
     {
-        about () { :; }
         about creates a new meta keyword for use in your functions
+        param 1: keyword
+        example $ cite url
+        example $ url http://somewhere.com
+        group composure
+
         local keyword=$1
         for keyword in $*; do
             eval "function $keyword { :; }"
         done
     }
 
-    cite about param example
 
     draft ()
     {
@@ -38,6 +47,8 @@ source_composure ()
         example $ ls
         example $ draft list
         example $ list
+        group composure
+
         local func=$1
         eval 'function ' $func ' { ' $(fc -ln -1) '; }'
         local file=$(mktemp /tmp/draft.XXXX)
@@ -46,39 +57,41 @@ source_composure ()
         rm $file 2>/dev/null
     }
 
-    transcribe ()
+    glossary ()
     {
-        about store function in ~/.composure git repository
-        param 1: function name
-        param 2: file containing function
-        param 3: operation label
-        example $ transcribe myfunc /tmp/myfunc.sh 'scooby-doo version'
-        example stores your function changes with:
-        example master 7a7e524 scooby-doo version myfunc
-        local func=$1
-        local file=$2
-        local operation="$3"
+        about displays help summary for all functions, or summary for a group of functions
+        param 1: optional, group name
+        example $ glossary
+        example $ glossary misc
+        group composure
 
-        if git --version >/dev/null 2>&1
-        then
-            if [ -d ~/.composure ]
-            then
-                (
-                    cd ~/.composure
-                    if git rev-parse 2>/dev/null
-                    then
-                        if [ ! -f $file ]
-                        then
-                            echo "Oops! Couldn't find $file to version it for you..."
-                            return
-                        fi
-                        cp $file ~/.composure/$func.sh
-                        git add --all .
-                        git commit -m "$operation $func"
-                    fi
-                )
+        local targetgroup=${1:-}
+
+        for func in $(compgen -A function); do
+            local about="$(metafor $func about)"
+            if [ -n "$targetgroup" ]; then
+                local group="$(metafor $func group)"
+                if [ "$group" != "$targetgroup" ]; then
+                    continue  # skip non-matching groups, if specified
+                fi
             fi
+            letterpress "$about" $func
+        done
+    }
+
+    letterpress ()
+    {
+        local metadata=$1 leftcol=${2:- } rightcol
+
+        if [ -z "$metadata" ]; then
+            return
         fi
+
+        OLD=$IFS; IFS=$'\n'
+        for rightcol in $metadata; do
+            printf "%-20s%s\n" $leftcol $rightcol
+        done
+        IFS=$OLD
     }
 
     metafor ()
@@ -86,75 +99,18 @@ source_composure ()
         about prints function metadata associated with keyword
         param 1: function name
         param 2: meta keyword
-        example $ metafor reference example
+        example $ metafor glossary example
+        group composure
         local func=$1 keyword=$2
         declare -f $func | sed -n "s/;$//;s/^ *$keyword \([^([].*\)*$/\1/p"
     }
 
-    reference ()
-    {
-        about displays help summary for all functions, or help for specific function
-        param 1: optional, function name
-        example $ reference
-        example $ reference metafor
-
-        printline ()
-        {
-            local metadata=$1 leftcol=${2:- } rightcol
-
-            if [[ -z "$metadata" ]]
-            then
-                return
-            fi
-
-            OLD=$IFS; IFS=$'\n'
-            for rightcol in $metadata
-            do
-                printf "%-20s%s\n" $leftcol $rightcol
-            done
-            IFS=$OLD
-        }
-
-        help ()
-        {
-            local func=$1
-
-            local about="$(metafor $func about)"
-            printline "$about" $func
-
-            local params="$(metafor $func param)"
-            if [[ -n "$params" ]]
-            then
-                echo "parameters:"
-                printline "$params"
-            fi
-
-            local examples="$(metafor $func example)"
-            if [[ -n "$examples" ]]
-            then
-                echo "examples:"
-                printline "$examples"
-            fi
-        }
-
-        if [[ -n "$1" ]]
-        then
-            help $1
-        else
-            for func in $(compgen -A function); do
-                local about="$(metafor $func about)"
-                printline "$about" $func
-            done
-        fi
-
-        unset help printline
-    }
-
     revise ()
     {
         about loads function into editor for revision
         param 1: name of function
         example $ revise myfunction
+        group composure
 
         local func=$1
         local temp=$(mktemp /tmp/revise.XXXX)
@@ -174,7 +130,65 @@ source_composure ()
         rm $temp
     }
 
-}
+    reference ()
+    {
+        about displays apidoc help for a specific function
+        param 1: function name
+        example $ reference revise
+        group composure
+
+        local func=$1
+
+        local about="$(metafor $func about)"
+        letterpress "$about" $func
+
+        local params="$(metafor $func param)"
+        if [ -n "$params" ]; then
+            echo "parameters:"
+            letterpress "$params"
+        fi
+
+        local examples="$(metafor $func example)"
+        if [ -n "$examples" ]; then
+            echo "examples:"
+            letterpress "$examples"
+        fi
+    }
+
+    transcribe ()
+    {
+        about store function in ~/.composure git repository
+        param 1: function name
+        param 2: file containing function
+        param 3: operation label
+        example $ transcribe myfunc /tmp/myfunc.sh 'scooby-doo version'
+        example stores your function changes with:
+        example master 7a7e524 scooby-doo version myfunc
+        group composure
+
+        local func=$1
+        local file=$2
+        local operation="$3"
+
+        if git --version >/dev/null 2>&1; then
+            if [ -d ~/.composure ]; then
+                (
+                    cd ~/.composure
+                    if git rev-parse 2>/dev/null; then
+                        if [ ! -f $file ]; then
+                            echo "Oops! Couldn't find $file to version it for you..."
+                            return
+                        fi
+                        cp $file ~/.composure/$func.sh
+                        git add --all .
+                        git commit -m "$operation $func"
+                    fi
+                )
+            fi
+        fi
+    }
+
+ }
 
 install_composure ()
 {
@@ -182,8 +196,7 @@ install_composure ()
 
     # find our absolute PATH
     SOURCE="${BASH_SOURCE[0]}"
-    while [ -h "$SOURCE" ]
-    do
+    while [ -h "$SOURCE" ]; do
         SOURCE="$(readlink "$SOURCE")"
     done
     DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )"
@@ -191,8 +204,7 @@ install_composure ()
     # vim: automatically chmod +x scripts with #! lines
     done_previously () { [ ! -z "$(grep BufWritePost | grep bin | grep chmod)" ]; }
 
-    if [ -f ~/.vimrc ] && ! $(<~/.vimrc done_previously)
-    then
+    if [ -f ~/.vimrc ] && ! $(<~/.vimrc done_previously); then
       echo 'vimrc: adding automatic chmod+x for files with shebang (#!) lines...'
       echo 'au BufWritePost * if getline(1) =~ "^#!" | if getline(1) =~ "/bin/" | silent execute "!chmod a+x <afile>" | endif | endif' >> ~/.vimrc
     fi
@@ -204,17 +216,14 @@ install_composure ()
     [ -f ~/.bashrc ] && $(<~/.bashrc done_previously) && done=1
     ! (($done)) && [ -f ~/.bash_profile ] && $(<~/.bash_profile done_previously) && done=1
 
-    if ! (($done))
-    then
+    if ! (($done)); then
       echo 'sourcing composure from .bashrc...'
       echo "source $DIR/$(basename $0)" >> ~/.bashrc
     fi
 
     # prepare git repo
-    if git --version >/dev/null 2>&1
-    then
-        if [ ! -d ~/.composure ]
-        then
+    if git --version >/dev/null 2>&1; then
+        if [ ! -d ~/.composure ]; then
             (
                 echo 'creating git repository for your functions...'
                 mkdir ~/.composure
@@ -230,8 +239,7 @@ install_composure ()
     echo 'composure installed.'
 }
 
-if [[ "$BASH_SOURCE" == "$0" ]]
-then
+if [ "$BASH_SOURCE" == "$0" ]; then
   install_composure
 else
   source_composure