Refactor command execution and help

- Copy and improve help text, and convert it to AsciiDoc files
- Evaluate commands dynamically

docs/cli/cd.adoc

@@ -0,0 +1,10 @@
+Change directory to root or plugin/theme directory.
+
+== USAGE
+  omf cd                                Change to Oh My Fish root folder
+  omf cd <package name> | <theme name>  Change to plugin or theme directory by name
+
+== EXAMPLES
+  omf cd
+  omf cd brew
+  omf cd l

docs/cli/channel.adoc

@@ -0,0 +1,16 @@
+Get or change the update channel.
+
+== USAGE
+  omf channel         Print the currently selected update channel
+  omf channel <name>  Switch to the given update channel
+
+== DESCRIPTION
+Two channels are available by default: the _stable_ channel provides stable
+updates with the latest tagged version of Oh My Fish, and _dev_ which provides
+the latest changes under development. The update channel currently set
+determines what version *omf update* will upgrade to.
+
+== EXAMPLES
+  omf channel
+  omf channel stable
+  omf channel dev

docs/cli/describe.adoc

@@ -0,0 +1,22 @@
+Show information about a package.
+
+== USAGE
+  omf describe <name>
+
+== DESCRIPTION
+Looks up a package whose name matches <name>.
+
+== EXAMPLES
+Show information about the *brew* package:
+
+  omf describe brew
+
+We get the following output:
+
+  Package: brew
+  Description: Oh My Fish plugin to integrate Homebrew paths into shell.
+  Repository: https://github.com/oh-my-fish/plugin-brew
+  Maintainer:
+
+== ALIASES
+*omf d*

docs/cli/destroy.adoc

@@ -0,0 +1,4 @@
+Uninstall Oh My Fish.
+
+== USAGE
+  omf destroy

docs/cli/doctor.adoc

@@ -0,0 +1,4 @@
+Troubleshoot Oh My Fish.
+
+== USAGE
+  omf doctor

docs/cli/help.adoc

@@ -0,0 +1,15 @@
+Show help text about Oh My Fish.
+
+== USAGE
+  omf help [<command>]
+  omf <command> --help
+
+== DESCRIPTION
+If no arguments are given, the usage guide for the *omf* command will be printed to standard output.
+
+If <command> is specified, the usage guide for <command> will be displayed. If <command> is an alias it will be translated into the corresponding command.
+
+== EXAMPLES
+To display the text you are currently reading, you can run:
+
+  omf help help

docs/cli/install.adoc

@@ -0,0 +1,18 @@
+Install one or more packages.
+
+== USAGE
+  omf install                          Install missing packages from bundle
+  omf install (<name> | <url>)         Install package by name or URL
+
+== DESCRIPTION
+You can install packages directly by URL via omf install URL.
+
+When called without arguments, install missing packages from bundle.
+
+== EXAMPLES
+  omf install
+  omf install brew
+  omf install https://github.com/oh-my-fish/plugin-brew
+
+== ALIASES
+*omf i*, *omf in*, *omf get*

docs/cli/list.adoc

@@ -0,0 +1,16 @@
+List installed packages.
+
+== USAGE
+  omf list [options]
+
+== DESCRIPTION
+
+== OPTIONS
+-p, --plugin::
+  Only list plugins.
+
+-t, --theme::
+  Only list themes.
+
+== ALIASES
+*omf ls*

docs/cli/new.adoc

@@ -0,0 +1,10 @@
+Create a new package from a template.
+
+== USAGE
+  omf new (_pkg_ | _theme_) _<name>_  Create a new package from a template
+
+== OPTIONS
+
+== EXAMPLES
+  omf new pkg mypkg
+  omf new theme mytheme

docs/cli/omf.adoc

@@ -0,0 +1,34 @@
+Oh My Fish! - the fish shell framework
+
+== USAGE
+  omf [options] [<command>] [arguments]
+
+== DESCRIPTION
+Provides options to list, download and remove packages, update the framework, create a new package, etc.
+
+== COMMANDS
+<<cd.adoc#,**cd**>>::            Change directory to plugin/theme directory.
+<<channel.adoc#,**channel**>>::       Get or change the update channel.
+<<describe.adoc#,**d**escribe>>::      Show information about a package.
+<<destroy.adoc#,**destroy**>>::       Uninstall Oh My Fish.
+<<doctor.adoc#,**doctor**>>::        Troubleshoot Oh My Fish.
+<<help.adoc#,**help**>>::          Shows help about a specific action.
+<<install.adoc#,**i**nstall>>::       Install one or more packages.
+<<list.adoc#,**l**ist>>::          List installed packages.
+<<new.adoc#,**n**ew>>::           Create a new package from a template.
+<<reload.adoc#,**reload**>>::        Reload the current shell.
+<<remove.adoc#,**r**emove>>::        Remove a theme or package.
+<<repositories.adoc#,**repo**sitories>>::  Manage package repositories.
+<<search.adoc#,**s**earch>>::        Search for a package or theme.
+<<theme.adoc#,**t**heme>>::         List / Use themes.
+<<update.adoc#,**u**pdate>>::        Update Oh My Fish.
+<<version.adoc#,**version**>>::       Display version and exit.
+
+== OPTIONS
+-h, --help::
+  Display this help.
+
+-v, --version::
+  Display version and exit.
+
+For more information visit → https://git.io/oh-my-fish

docs/cli/reload.adoc

@@ -0,0 +1,7 @@
+Reload the current shell.
+
+== USAGE
+  omf reload
+
+== DESCRIPTION
+Reload Oh My Fish and all plugins by using exec to replace current shell process with a brand new process. This command tries to be as safe as possible, mitigating side-effects caused by exec and preventing the reload in case of background processes.

docs/cli/remove.adoc

@@ -0,0 +1,11 @@
+Remove a theme or package.
+
+== USAGE
+  omf remove _<package name>_ | _<theme name>_  Removes a theme or package by name
+
+== EXAMPLES
+  omf remove brew
+  omf remove l
+
+== ALIASES
+*omf rm*, *omf uninstall*

docs/cli/repositories.adoc

@@ -0,0 +1,27 @@
+Manage user-installed package repositories.
+
+== USAGE
+  omf repositories [list | ls]
+  omf repositories add <url> [<branch>]
+  omf repositories (rm | remove) <url> [<branch>]
+
+== DESCRIPTION
+Package repositories are where packages come from used by commands like omf install. By default the official repository is always installed and available.
+
+== SUBCOMMANDS
+list, ls::
+  List installed repositories.
+
+add::
+  Add a package repository.
+
+remove, rm::
+  Remove a package repository.
+
+== EXAMPLES
+  omf repositories
+  omf repositories add https://github.com/vendor/fish-packages
+  omf repositories rm https://github.com/vendor/fish-packages master
+
+== ALIASES
+*omf repo*

docs/cli/search.adoc

@@ -0,0 +1,16 @@
+Search for a plugin or theme.
+
+== USAGE
+  omf search [options] <name>
+
+== OPTIONS
+-p, --plugin::
+  Limit results to plugins.
+
+-t, --theme::
+  Limit results to themes.
+
+== EXAMPLES
+  omf search -p nvm
+  omf search -t bobthefish
+  omf search vi

docs/cli/theme.adoc

@@ -0,0 +1,9 @@
+Install and list themes.
+
+== USAGE
+  omf theme         List available themes to install
+  omf theme <name>  Install theme by name
+
+== EXAMPLES
+  omf theme
+  omf theme l

docs/cli/update.adoc

@@ -0,0 +1,15 @@
+Update Oh My Fish.
+
+== USAGE
+  omf update [<package1> [<package2> [...]]]
+
+== DESCRIPTION
+Update Oh My Fish, all package repositories, and all installed packages.
+
+* When called without arguments, update core and all installed packages.
+* You can choose to update only the core, by running omf update omf.
+* For selective package update, list only the names of packages you wish to
+  update. You may still include "omf" in the list to update the core as well.
+
+== ALIASES
+*omf u*, *omf up*

docs/cli/version.adoc

@@ -0,0 +1,5 @@
+Display version and exit.
+
+== USAGE
+  omf version
+  omf --version

pkg/omf/functions/cli/omf.cli.help.fish

@@ -1,193 +1,56 @@
-function omf.cli.help -a command
-  switch "$command"
-    case "c" "cd"
-      echo "\
-Change directory to root or plugin/theme directory.
+function omf.cli.help
+  set -l IFS ''
+  set -l doc_root $OMF_PATH/docs/cli
+  set -l doc $doc_root/omf.adoc
 
-"(omf::dim)"Usage:"(omf::off)"
-  omf cd                                Change to Oh My Fish root folder
-  omf cd "(omf::em)"<package name>"(omf::off)" | "(omf::em)"<theme name>"(omf::off)"  Change to plugin or theme directory by name
-
-"(omf::dim)"Examples:"(omf::off)"
-  omf cd
-  omf cd brew
-  omf cd l
-"
-
-    case "channel"
-      echo \n"\
-Gets or changes the update channel.
-
-Two channels are available by default: the "(omf::em)"stable"(omf::off)" channel provides stable
-updates with the latest tagged version of Oh My Fish, and "(omf::em)"dev"(omf::off)" which provides
-the latest changes under development. The update channel currently set
-determines what version "(omf::em)"omf update"(omf::off)" will upgrade to.
-
-"(omf::dim)"Usage:"(omf::off)"
-  omf channel         Print the currently selected update channel
-  omf channel "(omf::em)"<name>"(omf::off)"  Switch to the given update channel
-
-"(omf::dim)"Examples:"(omf::off)"
-  omf channel
-  omf channel stable
-  omf channel dev
-"
-
-    case "d" "describe"
-      echo "\
-Get information about what packages do.
-
-"(omf::dim)"Usage:"(omf::off)"
-  omf describe "(omf::em)"<name>"(omf::off)"  Show information about a package
-
-"(omf::dim)"Examples:"(omf::off)"
-  omf describe brew
-"
-
-    case "destroy"
-      echo "\
-Uninstall Oh My Fish.
-
-"(omf::dim)"Usage:"(omf::off)"
-  omf destroy
-"
-
-    case "doctor"
-      echo "\
-Troubleshoot Oh My Fish.
-
-"(omf::dim)"Usage:"(omf::off)"
-  omf doctor
-"
-
-    case "i" "install" "get"
-      echo "\
-Install packages.
-
-"(omf::dim)"Usage:"(omf::off)"
-  omf install                 Install missing packages from bundle
-  omf install "(omf::em)"<name>"(omf::off)" | "(omf::em)"<url>"(omf::off)"  Install package by name or URL
-
-"(omf::dim)"Examples:"(omf::off)"
-  omf install
-  omf install brew
-  omf install https://github.com/oh-my-fish/plugin-brew
-"
-
-    case "l" "ls" "list"
-      echo "\
-List local packages.
-
-"(omf::dim)"Usage:"(omf::off)"
-  omf list [ --available | -a ]
-  omf list [ --installed | -i ]
-  omf list [ --database  | -d ]
-"
-
-    case "n" "new"
-      echo "\
-Create a new package from a template.
-
-"(omf::dim)"Usage:"(omf::off)"
-  omf new ("(omf::dim)"pkg"(omf::off)" | "(omf::dim)"theme"(omf::off)") "(omf::em)"<name>"(omf::off)"  Create a new package from a template
-
-"(omf::dim)"Examples:"(omf::off)"
-  omf new pkg mypkg
-  omf new theme mytheme
-"
-
-    case "repo" "repositories"
-      echo "\
-Manage package repositories.
-
-"(omf::dim)"Usage:"(omf::off)"
-  omf repositories [list|ls]                   List installed repositories
-  omf repositories add "(omf::em)"<url>"(omf::off)" ["(omf::em)"<branch>"(omf::off)"]        Add a package repository
-  omf repositories rm|remove "(omf::em)"<url>"(omf::off)" ["(omf::em)"<branch>"(omf::off)"]  Remove a package repository
-
-"(omf::dim)"Examples:"(omf::off)"
-  omf repositories
-  omf repositories add https://github.com/vendor/fish-packages
-  omf repositories rm https://github.com/vendor/fish-packages master
-"
-
-    case "r" "rm" "remove" "uninstall"
-      echo "\
-Remove a theme or package.
-
-"(omf::dim)"Usage:"(omf::off)"
-  omf remove "(omf::em)"<package name>"(omf::off)" | "(omf::em)"<theme name>"(omf::off)"  Removes a theme or package by name
-
-"(omf::dim)"Examples:"(omf::off)"
-  omf remove brew
-  omf remove l
-"
-
-    case "search"
-      echo "\
-Search for a plugin or theme.
-
-"(omf::dim)"Usage:"(omf::off)"
-  omf search ("(omf::dim)"-p/--plugin"(omf::off)" | "(omf::dim)"-t/--theme"(omf::off)") "(omf::em)"<name>"(omf::off)"  Search for a plugin or theme
-
-"(omf::dim)"Examples:"(omf::off)"
-  omf search -p nvm
-  omf search -t bobthefish
-  omf search vi
-"
-
-    case "t" "theme"
-      echo "\
-Install and list themes.
-
-"(omf::dim)"Usage:"(omf::off)"
-  omf theme         List available themes to install
-  omf theme "(omf::em)"<name>"(omf::off)"  Install theme by name
-
-"(omf::dim)"Examples:"(omf::off)"
-  omf theme
-  omf theme l
-"
-
-    case "u" "update"
-      echo "\
-Update Oh My Fish.
-
-"(omf::dim)"Usage:"(omf::off)"
-  omf update
-"
-
-    case "*"
-      echo "\
-\$ omf [command] [arguments]
-
-"(omf::dim)"Usage:"(omf::off)"
-  omf "(omf::em)"install"(omf::off)" [<name>|<url>]
-  omf "(omf::em)"theme"(omf::off)" [<name>]
-  omf "(omf::em)"remove"(omf::off)" [<name>]
-  omf "(omf::em)"search"(omf::off)" [<name>]
-  omf "(omf::em)"update"(omf::off)"
-  omf "(omf::em)"help"(omf::off)" [<command>]
-
-"(omf::dim)"Commands:"(omf::off)"
-  "(omf::em)"c"(omf::off)"d            Change directory to plugin/theme directory.
-  "(omf::em)"d"(omf::off)"escribe      Get information about what packages do.
-  "(omf::em)"destroy"(omf::off)"       Uninstall Oh My Fish.
-  "(omf::em)"doctor"(omf::off)"        Troubleshoot Oh My Fish.
-  "(omf::em)"help"(omf::off)"          Shows help about a specific action.
-  "(omf::em)"i"(omf::off)"nstall       Install one or more packages.
-  "(omf::em)"l"(omf::off)"ist          List local packages.
-  "(omf::em)"n"(omf::off)"ew           Create a new package from a template.
-  "(omf::em)"r"(omf::off)"emove        Remove a theme or package.
-  "(omf::em)"repo"(omf::off)"sitories  Manage package repositories.
-  "(omf::em)"s"(omf::off)"earch        Search for a package or theme.
-  "(omf::em)"t"(omf::off)"heme         List / Use themes.
-  "(omf::em)"u"(omf::off)"pdate        Update Oh My Fish.
-
-"(omf::dim)"Options:"(omf::off)"
-  "(omf::em)"--h"(omf::off)"elp        Display this help.
-  "(omf::em)"--v"(omf::off)"ersion     Display version.
-
-For more information visit → "(omf::em)"git.io/oh-my-fish"(omf::off)\n
+  # If a command was given, find a help document for it.
+  if set -q argv[1]
+    if not set command (omf.command $argv[1])
+      echo (omf::err)"Unknown command: $argv[1]"(omf::off) >&2
+      return $OMF_UNKNOWN_OPT
     end
+
+    set doc $doc_root/$command.adoc
+  end
+
+  set -l r (set_color normal ^ /dev/null)
+  set -l c (set_color cyan ^ /dev/null)
+  set -l b (set_color --bold ^ /dev/null)
+  set -l u (set_color --underline ^ /dev/null)
+
+  # Format the help document for the terminal.
+  fold -s $doc | sed -e "
+    # Strip cross references.
+    s/<<[^,]*,\([^>]*\)>>/\1/g
+
+    # Definition lists.
+    s/^\(\S.*\)::\(..*\)/\1\2/g
+    s/^\(\S.*\)::/$b\1$r/g
+
+    # Nice bullets for unordered lists.
+    s/^[*-] /· /g
+
+    # Indent everything left except for headers and the first line.
+    2,\$ s/^[^=]/  &/
+
+    # Headers.
+    s/^==* \(.*\)/$b\1$r/
+
+    # Bold.
+    s/\*\*\([^\*]*\)\*\*/$c\1$r/g
+    s/\*\([^\*]*\)\*/$c\1$r/g
+
+    # Style italics as underline.
+    s/__\([^_]*\)__/$u\1$r/g
+    s/_\([^_]*\)_/$u\1$r/g
+
+    # Underline links.
+    s/\w\w*:\S\S*/$u&$r/g
+
+    # Since we're in the terminal anyway, just strip monospace backticks.
+    s/`\([^`]*\)`/\1/g
+
+    # Underline variable names in angle brackets.
+    s/<[^>]*>/$u&$r/g
+  "
 end

pkg/omf/functions/cli/omf.cli.new.fish

@@ -1,7 +1,6 @@
 function omf.cli.new
   if test (count $argv) -ne 2
     echo (omf::err)"Package type or name missing"(omf::off) >&2
-    echo "Usage: omf new "(omf::em)"(pkg | theme)"(omf::off)" <name>" >&2
     return $OMF_MISSING_ARG
   end
   omf.packages.new $argv

pkg/omf/functions/cli/omf.cli.remove.fish

@@ -9,7 +9,7 @@ function omf.cli.remove -a name
       echo (omf::em)"$name successfully removed."(omf::off)
       # Opt-in flag for testing
       set -q OMF_AUTO_RELOAD
-        and omf.cli.reload
+        and omf.reload
     case 1
       echo (omf::err)"$name could not be removed."(omf::off) >&2
     case 2

pkg/omf/functions/cli/omf.cli.repositories.fish

@@ -0,0 +1,3 @@
+function omf.cli.repositories
+  omf.index.repositories $argv
+end

pkg/omf/functions/cli/omf.cli.theme.fish

@@ -1,7 +1,18 @@
 function omf.cli.theme -a name
   switch (count $argv)
   case 0
-    omf.cli.themes.list
+    test -f $OMF_CONFIG/theme
+      and read -l theme < $OMF_CONFIG/theme
+      or set -l theme default
+
+    set -l regex_current "(^|[[:space:]])($theme)([[:space:]]|\$)"
+    set -l highlight_current s/"$regex_current"/"\1"(omf::em)"\2"(omf::off)"\3"/g
+
+    echo (omf::under)"Installed:"(omf::off)
+    omf.packages.list --theme | column | sed -E "$highlight_current"
+    echo
+    echo (omf::under)"Available:"(omf::off)
+    omf.index.query --type=theme | column
   case 1
     omf.theme.set $name
   case '*'

pkg/omf/functions/cli/omf.cli.update.fish

@@ -36,6 +36,6 @@ function omf.cli.update
 
   # Opt-in flag for testing
   if set -q OMF_AUTO_RELOAD
-    omf.cli.reload
+    omf.reload
   end
 end

pkg/omf/functions/compat/refresh.fish

@@ -9,10 +9,10 @@ function refresh -d "(deprecated) Refresh fish session by replacing current proc
   set -q CI
     and return 0
 
-  type -q omf.core.reload
-    and omf.core.reload
+  type -q omf.reload
+    and omf.reload
 
-  # If omf.core.reload exist, current fish will be replaced via exec, so
+  # If omf.reload exist, current fish will be replaced via exec, so
   # the code below will never be reached. When it doesn't exist, the code
   # below, the deprecated method, will be used as fallback.
 

pkg/omf/functions/core/omf.command.fish

@@ -0,0 +1,38 @@
+function omf.command -d 'Lookup OMF command by name or alias' -a name
+  switch "$name"
+    case 'cd'
+      echo cd
+    case 'channel'
+      echo channel
+    case 'd' 'describe'
+      echo describe
+    case 'destroy'
+      echo destroy
+    case 'doctor'
+      echo doctor
+    case 'help'
+      echo help
+    case 'i' 'in' 'install' 'get'
+      echo install
+    case 'l' 'ls' 'list'
+      echo list
+    case 'n' 'new'
+      echo new
+    case 'reload'
+      echo reload
+    case 'r' 'rm' 'remove' 'uninstall'
+      echo remove
+    case 'repo' 'repositories'
+      echo repositories
+    case 't' 'theme'
+      echo theme
+    case 'u' 'update'
+      echo update
+    case 's' 'search'
+      echo search
+    case 'version'
+      echo version
+    case '*'
+      return $OMF_UNKNOWN_OPT
+  end
+end

pkg/omf/functions/omf.fish

@@ -1,80 +1,51 @@
-# SYNOPSIS
-#   Oh My Fish! CLI
-#
-# OVERVIEW
-#   Provides options to list, download and remove packages, update
-#   the framework, create / submit a new package, etc.
-
 function omf -d "Oh My Fish"
-
-  if test "x$argv[-1]" = "x--help" -a (count $argv) = 2
+  # Parse any options before the command name.
+  while set -q argv[1]
+    switch $argv[1]
+      case '-h' '--help' '-\?' '/\?'
         set command help
-    set arguments $argv[1]
-  else if test (count $argv) -ge 2
+
+      case '-v' '--version'
+        set command version
+
+      case '-?*'
+        echo (omf::err)"Unknown option: $argv[1]"(omf::off) >&2
+        return $OMF_UNKNOWN_OPT
+
+      case '*'
+        break
+    end
+
+    set -e argv[1]
+  end
+
+  # Also extract a help flag from the last argument.
+  switch "$argv[-1]"
+    case '-h' '--help' '-\?' '/\?'
+      set command help
+      set -e argv[-1]
+  end
+
+  # Extract the command name from the remaining arguments.
+  if not set -q command
+    if set -q argv[1]
       set command $argv[1]
-    set arguments $argv[2..-1]
-  else if test (count $argv) = 1
-    set command $argv[1]
-    set arguments
+      set -e argv[1]
     else
       set command help
-    set arguments
+    end
   end
 
-  switch "$command"
-    case "-v*" "--v*"
-      omf.cli.version
-
-    case "-h*" "--h*" "help"
-      omf.cli.help $arguments
-
-    case "c" "cd"
-      omf.cli.cd $arguments
-
-    case "d" "describe"
-      omf.cli.describe $arguments
-
-    case "destroy"
-      omf.cli.destroy
-
-    case "doctor"
-      omf.cli.doctor
-
-    case "reload"
-      omf.cli.reload $arguments
-
-    case "i" "install" "get"
-      omf.cli.install $arguments
-
-    case "l" "ls" "list"
-      omf.cli.list $arguments
-
-    case "n" "new"
-      omf.cli.new $arguments
-
-    case "r" "rm" "remove" "uninstall"
-      omf.cli.remove $arguments
-
-    case "t" "theme"
-      omf.cli.theme $arguments
-
-    case "u" "update"
-      omf.cli.update $arguments
-
-    case "repo" "repositories"
-      omf.index.repositories $arguments
-
-    case "channel"
-      omf.cli.channel $arguments
-
-    case "s" "search"
-      omf.cli.search $arguments
-
-    case "version"
-      omf.cli.version $arguments
-
-    case "*"
-      echo (omf::err)"$argv[1] option not recognized"(omf::off) >&2
+  # Lookup the function for the requested command.
+  if not set command_name (omf.command $command)
+    echo (omf::err)"Unknown command: $command"(omf::off) >&2
     return $OMF_UNKNOWN_OPT
   end
+
+  # Execute the command.
+  echo "function __omf_last_command --no-scope-shadowing
+    omf.cli.$command_name \$argv
+  end" | source
+
+  __omf_last_command $argv
 end

pkg/omf/functions/packages/omf.packages.new.fish

@@ -40,7 +40,7 @@ end
 
 function omf.packages.new -a option name
   switch $option
-    case "p" "pkg" "pack" "packg" "package"
+    case "p" "plugin"
       set option "pkg"
     case "t" "th" "the" "thm" "theme" "themes"
       set option "themes"