Updated documentation for agnoster theme

themes/agnoster.zsh-theme

@@ -1,22 +1,51 @@
+# vim:ft=zsh ts=2 sw=2 sts=2
+#
+# agnoster's Theme
+# A Powerline-inspired theme for ZSH
+#
+# # README
+#
+# In order for this theme to render correctly, you will need a
+# [Powerline-patched font](https://gist.github.com/1595572).
+#
+# In addition, I recommend the
+# [Solarized theme](https://github.com/altercation/solarized/) and, if you're
+# using it on Mac OS X, [iTerm 2](http://www.iterm2.com/) over Terminal.app -
+# it has significantly better color fidelity.
+#
+# # Goals
+#
+# The aim of this theme is to only show you *relevant* information. Like most
+# prompts, it will only show git information when in a git working directory.
+# However, it goes a step further: everything from the current user and
+# hostname to whether the last call exited with an error to whether background
+# jobs are running in this shell will all be displayed automatically when
+# appropriate.
+
 ### Segment drawing
 # A few utility functions to make it easy and re-usable to draw segmented prompts
 
-CURRENT_BG=''
+CURRENT_BG='NONE'
 SEGMENT_SEPARATOR='⮀'
-function segment_start() {
-  local bg=$1
-  local fg=$2
-  if [[ -n $CURRENT_BG && $bg != $CURRENT_BG ]]; then
-    echo -n " %{%K{$bg}%F{$CURRENT_BG}%}$SEGMENT_SEPARATOR"
+
+# Begin a segment
+# Takes two arguments, background and foreground. Both can be omitted,
+# rendering default background/foreground.
+prompt_segment() {
+  local bg fg
+  [[ -n $1 ]] && bg="%K{$1}" || bg="%k"
+  [[ -n $2 ]] && fg="%F{$2}" || fg="%f"
+  if [[ $CURRENT_BG != 'NONE' && $1 != $CURRENT_BG ]]; then
+    echo -n " %{$bg%F{$CURRENT_BG}%}$SEGMENT_SEPARATOR%{$fg%} "
   else
-    echo -n "%{%K{$bg}%}"
+    echo -n "%{$bg%}%{$fg%} "
   fi
-  [[ -n $fg ]] && fg="%F{$fg}" || fg="%f"
-  echo -n "%{$fg%} "
-  CURRENT_BG=$bg
+  CURRENT_BG=$1
+  [[ -n $3 ]] && echo -n $3
 }
 
-function segment_stop() {
+# End the prompt, closing any open segments
+prompt_end() {
   if [[ -n $CURRENT_BG ]]; then
     echo -n " %{%k%F{$CURRENT_BG}%}$SEGMENT_SEPARATOR"
   else
@@ -29,58 +58,58 @@ function segment_stop() {
 ### Prompt components
 # Each component will draw itself, and hide itself if no information needs to be shown
 
-function prompt_context() {
+# Context: user@hostname (who am I and where am I)
+prompt_context() {
   local user=`whoami`
 
-  if [[ ("$user" != "$DEFAULT_USER") || (-n "$SSH_CLIENT") ]]; then
-    segment_start black
-    #echo -n "%{%F{yellow}%}$user%{%F{gray}%}@%{%F{green}%}%m%{%f%}"
-    echo -n "%(!.%{%F{yellow}%}.)$user@%m"
+  if [[ "$user" != "$DEFAULT_USER" || -n "$SSH_CLIENT" ]]; then
+    prompt_segment black default "%(!.%{%F{yellow}%}.)$user@%m"
   fi
 }
 
-function prompt_git() {
+# Git: branch/detached head, dirty status
+prompt_git() {
+  local ref dirty
   if $(git rev-parse --is-inside-work-tree >/dev/null 2>&1); then
     ZSH_THEME_GIT_PROMPT_DIRTY='±'
-    local dirty=$(parse_git_dirty)
-    local ref
+    dirty=$(parse_git_dirty)
     ref=$(git symbolic-ref HEAD 2> /dev/null) || ref="➦ $(git show-ref --head -s --abbrev |head -n1 2> /dev/null)"
     if [[ -n $dirty ]]; then
-      segment_start yellow black
+      prompt_segment yellow black
     else
-      segment_start green black
+      prompt_segment green black
     fi
     echo -n "${ref/refs\/heads\//⭠ }$dirty"
   fi
 }
 
-function prompt_dir() {
-  segment_start blue white
-  echo -n '%~'
+# Dir: current working directory
+prompt_dir() {
+  prompt_segment blue black '%~'
 }
 
-function prompt_status() {
+# Status:
+# - was there an error
+# - am I root
+# - are there background jobs?
+prompt_status() {
   local symbols
   symbols=()
   [[ $RETVAL -ne 0 ]] && symbols+="%{%F{red}%}✘"
   [[ $UID -eq 0 ]] && symbols+="%{%F{yellow}%}⚡"
-  jobs=$(jobs -l | wc -l)
-  [[ $jobs -gt 0 ]] && symbols+="%{%F{cyan}%}⚙"
-  if [[ -n "$symbols" ]]; then
-    segment_start black white
-    echo -n "${symbols}"
-  fi
+  [[ $(jobs -l | wc -l) -gt 0 ]] && symbols+="%{%F{cyan}%}⚙"
+
+  [[ -n "$symbols" ]] && prompt_segment black default "$symbols"
 }
 
 ## Main prompt
-function build_prompt() {
+build_prompt() {
   RETVAL=$?
   prompt_status
   prompt_context
   prompt_dir
   prompt_git
-  segment_stop
+  prompt_end
 }
 
-PROMPT='%{%f%b%k%}
-$(build_prompt) '
+PROMPT='%{%f%b%k%}$(build_prompt) '