Merge b3c431ed7a into 773370bacd

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,36 +47,51 @@ source_composure ()
         example $ ls
         example $ draft list
         example $ list
-      local name=$1
+        group composure
-      eval 'function ' $name ' { ' $(fc -ln -1) '; }'
+
+        local func=$1
+        eval 'function ' $func ' { ' $(fc -ln -1) '; }'
+        local file=$(mktemp /tmp/draft.XXXX)
+        declare -f $func > $file
+        transcribe $func $file draft
+        rm $file 2>/dev/null
     }
 
-    write ()
+    glossary ()
     {
-      about prints function declaration to stdout
+        about displays help summary for all functions, or summary for a group of functions
-      param name of function or functions, separated by spaces
+        param 1: optional, group name
-      example $ write myfunction
+        example $ glossary
-      example $ write func1 func2 func3 > ~/funcs.sh
+        example $ glossary misc
-      local func
+        group composure
-      for func in $*
+
-      do
+        local targetgroup=${1:-}
-          # trim trailing semicolons generated by declare -f
+
-          declare -f $func | sed  "s/^\(.*\);$/\1/"
+        for func in $(compgen -A function); do
-          echo
+            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
     }
 
-    revise ()
+    letterpress ()
     {
-        about loads function into editor for revision
+        local metadata=$1 leftcol=${2:- } rightcol
-        param name of function or functions, separated by spaces
+
-        example $ revise myfunction
+        if [ -z "$metadata" ]; then
-        example $ revise func1 func2 func3
+            return
-        local temp=$(mktemp /tmp/revise.XXXX)
+        fi
-        write $* > $temp
+
-        $EDITOR $temp
+        OLD=$IFS; IFS=$'\n'
-        eval "$(cat $temp)"
+        for rightcol in $metadata; do
-        rm $temp
+            printf "%-20s%s\n" $leftcol $rightcol
+        done
+        IFS=$OLD
     }
 
     metafor ()
@@ -75,74 +99,96 @@ 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
-        write $func | sed -n "s/^ *$keyword \([^([].*\)$/\1/p"
+        declare -f $func | sed -n "s/;$//;s/^ *$keyword \([^([].*\)*$/\1/p"
+    }
+
+    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)
+
+        # populate tempfile...
+        if [ -f ~/.composure/$func.sh ]; then
+            # ...with contents of latest git revision...
+            cat ~/.composure/$func.sh >> $temp
+        else
+            # ...or from ENV if not previously versioned
+            declare -f $func >> $temp
+        fi
+        $EDITOR $temp
+        source $temp
+
+        transcribe $func $temp revise
+        rm $temp
     }
 
     reference ()
     {
-        about displays help summary for all functions, or help for specific function
+        about displays apidoc help for a specific function
-        param 1: optional, function name
+        param 1: function name
-        example $ reference
+        example $ reference revise
-        example $ reference metafor
+        group composure
 
-        printline ()
-        {
-            local metadata=$1 lhs=${2:- }
-
-            if [[ -z "$metadata" ]]
-            then
-                return
-            fi
-
-            OLD=$IFS; IFS=$'\n'
-            local line
-            for line in $metadata
-            do
-                printf "%-20s%s\n" $lhs $line
-            done
-            IFS=$OLD
-        }
-
-        help ()
-        {
         local func=$1
 
         local about="$(metafor $func about)"
-            printline "$about" $func
+        letterpress "$about" $func
 
         local params="$(metafor $func param)"
-            if [[ -n "$params" ]]
+        if [ -n "$params" ]; then
-            then
             echo "parameters:"
-                printline "$params"
+            letterpress "$params"
         fi
 
         local examples="$(metafor $func example)"
-            if [[ -n "$examples" ]]
+        if [ -n "$examples" ]; then
-            then
             echo "examples:"
-                printline "$examples"
+            letterpress "$examples"
         fi
-
-            unset printline
     }
 
-        if [[ -n "$1" ]]
+    transcribe ()
-        then
+    {
-            help $1
+        about store function in ~/.composure git repository
-        else
+        param 1: function name
-            for func in $(compgen -A function); do
+        param 2: file containing function
-                local about="$(metafor $func about)"
+        param 3: operation label
-                printline "$about" $func
+        example $ transcribe myfunc /tmp/myfunc.sh 'scooby-doo version'
-            done
+        example stores your function changes with:
-        fi
+        example master 7a7e524 scooby-doo version myfunc
+        group composure
 
-        unset help printline
+        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 ()
 {
@@ -150,8 +196,7 @@ install_composure ()
 
     # find our absolute PATH
     SOURCE="${BASH_SOURCE[0]}"
-    while [ -h "$SOURCE" ]
+    while [ -h "$SOURCE" ]; do
-    do
         SOURCE="$(readlink "$SOURCE")"
     done
     DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )"
@@ -159,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)
+    if [ -f ~/.vimrc ] && ! $(<~/.vimrc done_previously); then
-    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
@@ -172,17 +216,30 @@ install_composure ()
     [ -f ~/.bashrc ] && $(<~/.bashrc done_previously) && done=1
     ! (($done)) && [ -f ~/.bash_profile ] && $(<~/.bash_profile done_previously) && done=1
 
-    if ! (($done))
+    if ! (($done)); then
-    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
+            (
+                echo 'creating git repository for your functions...'
+                mkdir ~/.composure
+                cd ~/.composure
+                git init
+                echo "composure stores your function definitions here" > README.txt
+                git add README.txt
+                git commit -m 'initial commit'
+            )
+        fi
+    fi
+
     echo 'composure installed.'
 }
 
-if [[ "$BASH_SOURCE" == "$0" ]]
+if [ "$BASH_SOURCE" == "$0" ]; then
-then
   install_composure
 else
   source_composure