Add Alternate VCS theme

This theme adds a "status" section to the VCS details display, showing
staged, modified, and untracked file counts, as well as all of the other
parts that the default theme shows. Each section has a config option.
Also adds an option to always display a matching VCS tag, even if a
branch is matching. This is a feature request from #567.

This is somewhat a refactor of #525. I decided to refactor because I
needed a good example theme for changing only one part of the default
theme. Changing the VCS display seemed to be decently often requested,
and I had a pretty good implementation in @MunifTanjim s pull request
(thanks!).

What I didn't expect was to like it so much. I'm running this theme as
my default for right now.

What I do not want to do yet is merge this as part of mainline
Liquidprompt; I would rather keep this as an included theme. Even though
each part is configurable, these config options would only be applicable
to the default theme. And these kind of modifications really should be
done in a theme, which is exactly what this is.

What could be added yet is "new", "deleted", and "changed" distinctions.
This would need new data sources though, as right now the VCS interface
added in v2.0 only has uncommitted files/lines, unstaged files/lines,
and untracked files.

Co-authored-by: MunifTanjim <MunifTanjim@users.noreply.github.com>

docs/theme/included.rst

@@ -7,5 +7,6 @@ them as they are added to Liquidprompt.
 .. toctree::
    :maxdepth: 2
 
+   included/alternate_vcs
    included/powerline
 

docs/theme/included/alternate_vcs.rst

@@ -0,0 +1,105 @@
+***************************
+Alternate VCS Details Theme
+***************************
+
+The included ``themes/powerline/alternate_vcs.theme`` file includes a theme
+extending the default theme but replacing the VCS details display.
+
+.. contents::
+   :local:
+
+Alternate VCS
+*************
+
+The ``alternate_vcs`` theme is an extension of the default theme.
+
+This prompt is a fully usable theme, designed to be more flexible than the
+default theme in terms of what VCS information is shown in the prompt.
+
+It is also an example of how to build a theme extending the default theme while
+replacing one of the template sections.
+
+.. versionadded:: 2.0
+
+Preview
+=======
+
+If there is nothing special about the current context, the appearance of
+Alternate VCS might be as simple as this:
+
+.. image:: alternate_vcs-short.png
+   :alt: [user:~] $
+
+If you are running a background command and are also in the "main" branch of a
+Git repository on a server:
+
+.. image:: alternate_vcs-med.png
+   :alt: 1& [user@server:~/liquidprompt] main ±
+
+When Liquidprompt is displaying nearly everything, it may look like this:
+
+.. image:: alternate_vcs-long.png
+   :alt: 🕤 ⌁24% ⌂42% θ90° 3d/2&/1z [user@server:~ … /code/liquidprompt] [pyenv] main(?1 +10/-5,+3/-1)+ 20s 125 ±
+
+A demo of what disabling the configuration options might look like:
+
+.. image:: alternate_vcs-demo.png
+   :alt: [user@server:~/liquidprompt] main(U1 ?1 +8/-1,+1/-3)+ ±
+
+Configuration
+=============
+
+Liquidprompt Configuration
+--------------------------
+All Liquidprompt config options are respected, **except for**:
+
+* :attr:`LP_MARK_UNTRACKED` when :attr:`LP_ENABLE_ALT_VCS_STATUS` is enabled.
+
+Theme Configuration
+-------------------
+
+Alternate VCS adds these config options:
+
+Features
+________
+
+.. attribute:: LP_ALWAYS_ALT_VCS_TAG
+   :type: bool
+   :value: 0
+
+   Determine when a matching VCS tag should be displayed:
+
+   * ``0`` - Only when there is no current branch or bookmark
+   * ``1`` - Always
+
+.. attribute:: LP_ENABLE_ALT_VCS_COMMITS
+   :type: bool
+   :value: 1
+
+   Display commits ahead or behind the remote tracking branch.
+
+.. attribute:: LP_ENABLE_ALT_VCS_DIFF
+   :type: bool
+   :value: 1
+
+   Display the number of changed lines.
+
+.. attribute:: LP_ENABLE_ALT_VCS_STATUS
+   :type: bool
+   :value: 1
+
+   Display the number(s) of changed files, of type staged (if VCS supports
+   staging), non-staged (or non-committed if no staging), and untracked.
+
+   If disabled, a marker will be added to the end of the display to show if
+   there are untracked files (the behavior of the default theme).
+
+Markers
+_______
+
+.. attribute:: LP_MARK_ALT_VCS_TAG
+   :type: string
+   :value: "🔖"
+
+   The marker string used to indicate the following string is a VCS tag.
+

themes/alternate_vcs/alternate_vcs.theme

@@ -0,0 +1,141 @@
+
+_lp_alternate_vcs_theme_activate() {
+    _lp_default_theme_activate
+
+    LP_ALWAYS_ALT_VCS_TAG=${LP_ALWAYS_ALT_VCS_TAG:-0}
+    LP_ENABLE_ALT_VCS_COMMITS=${LP_ENABLE_ALT_VCS_COMMITS:-1}
+    LP_ENABLE_ALT_VCS_DIFF=${LP_ENABLE_ALT_VCS_DIFF:-1}
+    LP_ENABLE_ALT_VCS_STATUS=${LP_ENABLE_ALT_VCS_STATUS:-1}
+    LP_MARK_ALT_VCS_TAG=${LP_MARK_ALT_VCS_TAG:-"🔖"}
+}
+
+_lp_alternate_vcs_theme_directory() {
+    _lp_default_theme_directory
+}
+
+_lp_alternate_vcs_theme_prompt() {
+    _lp_default_theme_prompt_data
+
+    # TODO: This will run both VCS details, which will make this prompt slower
+    if _lp_find_vcs && _lp_alternate_vcs_details; then
+        LP_VCS=" $lp_alternate_vcs_details"
+    else
+        LP_VCS=
+    fi
+
+    _lp_default_theme_prompt_template
+}
+
+_lp_alternate_vcs_details() {
+    local branch
+    if _lp_vcs_branch; then
+        branch="$lp_vcs_branch"
+
+        if _lp_vcs_bookmark; then
+            branch+=": $lp_vcs_bookmark"
+        fi
+        if (( LP_ALWAYS_ALT_VCS_TAG )) && _lp_vcs_tag; then
+            branch+=" ${LP_MARK_ALT_VCS_TAG}${lp_vcs_tag}"
+        fi
+    elif _lp_vcs_bookmark; then
+        branch="$lp_vcs_bookmark"
+    elif _lp_vcs_tag; then
+        branch="${LP_MARK_ALT_VCS_TAG}${lp_vcs_tag}"
+    else
+        _lp_vcs_commit_id
+        branch="${lp_vcs_commit_id:0:7}"
+    fi
+
+    lp_alternate_vcs_details="$LP_COLOR_UP"
+
+    local has_commit=
+    if _lp_vcs_commits_off_remote; then
+        lp_alternate_vcs_details="$LP_COLOR_COMMITS_BEHIND"
+        if [[ "$lp_vcs_commit_ahead" -ne "0" && "$lp_vcs_commit_behind" -ne "0" ]]; then
+            has_commit="${LP_COLOR_COMMITS}+$lp_vcs_commit_ahead${NO_COL}/${LP_COLOR_COMMITS_BEHIND}-$lp_vcs_commit_behind"
+        elif [[ "$lp_vcs_commit_ahead" -ne "0" ]]; then
+            has_commit="${LP_COLOR_COMMITS}$lp_vcs_commit_ahead"
+            lp_alternate_vcs_details="$LP_COLOR_COMMITS"
+        elif [[ "$lp_vcs_commit_behind" -ne "0" ]]; then
+            has_commit="${LP_COLOR_COMMITS_BEHIND}-$lp_vcs_commit_behind"
+        fi
+        (( LP_ENABLE_ALT_VCS_COMMITS )) || has_commit=""
+    fi
+
+    local ret has_files=
+    if _lp_vcs_uncommitted_files; then
+        lp_alternate_vcs_details="$LP_COLOR_CHANGES"
+        if (( LP_ENABLE_ALT_VCS_STATUS )); then
+            _lp_vcs_unstaged_files; ret=$?
+            # Only show unstaged files if the VCS supports staging, otherwise
+            # show only uncommitted files
+            if (( ret == 0 )); then
+                local -i staged_files=$(( lp_vcs_uncommitted_files - lp_vcs_unstaged_files ))
+                if (( staged_files )); then
+                    has_files="${LP_COLOR_COMMITS}S${staged_files} "
+                fi
+                has_files+="${LP_COLOR_CHANGES}U${lp_vcs_unstaged_files}"
+            elif (( ret == 1 )); then
+                has_files="${LP_COLOR_COMMITS}S${lp_vcs_uncommitted_files}"
+            else
+                has_files="${LP_COLOR_CHANGES}U${lp_vcs_uncommitted_files}"
+            fi
+        fi
+    fi
+    if (( LP_ENABLE_ALT_VCS_STATUS )) && _lp_vcs_untracked_files; then
+        [[ -n $has_files ]] && has_files+=" "
+        has_files+="${LP_COLOR_CHANGES}?${lp_vcs_untracked_files}"
+    fi
+
+    local has_lines=
+    if (( LP_ENABLE_ALT_VCS_DIFF )) && _lp_vcs_uncommitted_lines; then
+        _lp_vcs_unstaged_lines; ret=$?
+        # Only show unstaged changes if the VCS supports staging, otherwise
+        # show uncommitted changes.
+        if (( ret == 0 )); then
+            has_lines="+$lp_vcs_unstaged_i_lines/-$lp_vcs_unstaged_d_lines"
+        elif (( ret == 1 )); then
+            # If the status is on, it would be redundant to say there are no unstaged lines.
+            if (( ! LP_ENABLE_ALT_VCS_STATUS )); then
+                has_lines="+0/-0"
+            fi
+        else
+            has_lines="+$lp_vcs_uncommitted_i_lines/-$lp_vcs_uncommitted_d_lines"
+        fi
+    fi
+
+    lp_alternate_vcs_details+="$branch"
+    if [[ -n $has_lines || -n $has_files || -n $has_commit ]]; then
+        lp_alternate_vcs_details+="${NO_COL}("
+        if [[ -n $has_files ]]; then
+            lp_alternate_vcs_details+="$has_files"
+            if [[ -n $has_lines || -n $has_commit ]]; then
+                lp_alternate_vcs_details+="${NO_COL} "
+            fi
+        fi
+        if [[ -n $has_lines ]]; then
+            lp_alternate_vcs_details+="${LP_COLOR_DIFF}${has_lines}"
+            if [[ -n $has_commit ]]; then
+                lp_alternate_vcs_details+="${NO_COL},"
+            fi
+        fi
+        lp_alternate_vcs_details+="${has_commit}${NO_COL})"
+    fi
+
+    if _lp_vcs_stash_count; then
+        lp_alternate_vcs_details+="${LP_COLOR_COMMITS}${LP_MARK_STASH}"
+    fi
+
+    if (( ! LP_ENABLE_ALT_VCS_STATUS )) && _lp_vcs_untracked_files; then
+        lp_alternate_vcs_details+="${LP_COLOR_CHANGES}${LP_MARK_UNTRACKED}"
+    fi
+
+    if _lp_vcs_head_status; then
+        lp_alternate_vcs_details+=" ${LP_COLOR_CHANGES}${lp_vcs_head_status}"
+        if [[ -n "${lp_vcs_head_details-}" ]]; then
+            lp_alternate_vcs_details+="(${lp_vcs_head_details})"
+        fi
+    fi
+
+    lp_alternate_vcs_details+="$NO_COL"
+}