Permalink
Browse files

first shot at self-documenting subcommands

  • Loading branch information...
1 parent 86bb368 commit 62b960dbd7b634f7ff157a260bd98e5c5d88bee0 @qrush qrush committed Sep 27, 2012
Showing with 52 additions and 15 deletions.
  1. +21 −0 README.md
  2. +5 −0 libexec/sub-commands
  3. +26 −15 libexec/sub-help
View
@@ -65,6 +65,27 @@ set -e
echo $_RUSH_ROOT
```
+## Self-documenting
+
+Each subcommand can opt into self-documentation, which allows the subcommand to provide information when `sub` and `sub help [SUBCOMMAND]` is run.
+
+This is all done by adding a few magic comments. Here's an example from `rush who` (also see `sub commands` for another example):
+
+``` bash
+#!/usr/bin/env bash
+# Usage: Usage: `sub who`
+# Summary: Check who's logged in
+# Help: This will print out when you run `sub help who`.
+# You can have multiple lines even!
+
+set -e
+
+who
+```
+
+Now, when you run `sub`, it should show now show up:
+
+
## Autocompletion
Your sub loves autocompletion. It's the mustard, mayo, or whatever topping you'd like that day for your commands. Just like real toppings, you have to opt into them! Sub provides two kinds of autocompletion:
View
@@ -1,4 +1,9 @@
#!/usr/bin/env bash
+# Usage: sub commands
+# Summary: List all sub commands
+# Help: This command is mostly used for autocompletion in various shells, and for `sub help`.
+# Also, this command helps find commands that are named the same as potentially builtin shell commands (which, cd, etc)
+
set -e
# Provide sub completions
View
@@ -1,31 +1,42 @@
#!/usr/bin/env bash
set -e
+print_summaries() {
+ for file in libexec/sub-*; do
+ local summary=$(grep "^# Summary:" $file | cut -d ' ' -f3-)
+ if [ -n "$summary" ]; then
+ local name=$(basename $file | sed 's/sub-//')
+ echo "$name" | awk '{ printf " %-20s ", $1}'
+ echo -n $summary
+ echo
+ fi
+ done
+}
+
+print_help() {
+ local usage=$(grep "^# Usage:" $1 | cut -d ' ' -f2-)
+ local halp="$(awk '/^# Help:/,/^[^#]/' libexec/sub-commands | grep "^#" | sed "s/^# Help: //" | sed "s/# //")"
+
+ if [ -n "$usage" ]; then
+ echo $usage
+ [ -n "$halp" ] && echo && echo "$halp"
+ else
+ echo "Sorry, this command isn't documented yet."
+ fi
+}
+
case "$1" in
"") echo "usage: sub <command> [<args>]
Some useful sub commands are:
- commands List all sub commands
+$(print_summaries)
See 'sub help <command>' for information on a specific command."
;;
-# >>>>> copy from this block to add more help blocks!
-# See https://github.com/sstephenson/rbenv/blob/master/libexec/rbenv-help for more examples.
-commands) echo "usage: sub commands
- sub commands --sh
- sub commands --no-sh
-
-List all sub commands."
-;;
-# >>>>>
*)
command_path="$(command -v "sub-$1" || true)"
if [ -n "$command_path" ]; then
- echo "Sorry, the \`$1' command isn't documented yet."
- echo
- echo "You can view the command's source here:"
- echo "$command_path"
- echo
+ print_help "libexec/sub-$1"
else
echo "sub: no such command \`$1'"
fi

0 comments on commit 62b960d

Please sign in to comment.