Merge remote-tracking branch 'onaforeignshore/code_separation' into s…

…taging_700

Merge of Powerlevel9k#771 into Powerlevel9k#859

CHANGELOG.md

@@ -1,5 +1,51 @@
 ## next
 
+- Moved all environment variables from `POWERLEVEL9K_` to `P9K_`
+- `utilities.zsh`
+  - Added OS detection logic to allow use of `$OS` in segments.
+  - Added OS version detection logic for Linux to allow use of `$OS_ID` in segments.
+  - Added Terminal detection logic to allow use of `$TERMINAL` in segments.
+  - Added function `updateEnvironmentVars()` to automatically change user variables for backward compatibility. NOTE: There may be minor issues with arrays, so this still needs review.
+- `icons.zsh`
+  - Only core icons are registered by default.
+  - Each segment is responsible to register its own icons.
+- Moved all segments to their own files under `segments`.
+  - Segments now use `p9kPrepareSegment()` instead of `$1_prompt_segment()`.
+  - Only segments in use are dynamically loaded (including their icons).
+  - The autoloader checks if a file exists before calling it to catch any errors. For `custom_prompt` segments, it checks if it is a variable/definition before checking for a file.
+  - Custom segment files have to be placed in `segments/custom` directory, and have to follow the naming convention.
+    - Segment file should be named `segment_name.p9k`.
+    - Segment definition should be `prompt_custom_segment_name()`.
+- Moved prompt generators to their own files under `generator`.
+  - `default.p9k` is the default (current) generator.
+  - `zsh-async` has been included but is still experimental. To use, set `POWERLEVEL9K_GENERATOR="zsh-async"` in `powerlevel9k.zsh`.
+- Segments and generators use the `*.p9k` extention to ensure that they don't conflict with similarly names `*.zsh` scripts.
+- Segment updates
+  - `vi_mode.p9k`
+    - Rewrote to support both `default` and `zsh-async` generators.
+    - Added support to change cursor shape.
+    - To enable cursor shape change, set `POWERLEVEL9K_CURSOR_SHAPE=true`. On supported terminals, cursor shape can be `box` [], `hbar` _ or `vbar` |.
+    - Changed `zle reset-prompt` to `zle .reset-prompt`.
+  - `prompt_php_version` - Added support for icon.
+  - `rspec_stats` / `symfony2_test` - Both segments call `test_stats.p9k` (which also initializes the icon).
+  - `prompt_java_version` added and `README.md` updated.
+- `README.md`
+  - Added missing items and links to the index.
+  - Rearranged the content to match the index.
+- API created!
+  - Added `API` folder. This contains all the Markdown documentation generated from the function description comments (using `sh2md`) for all of the `*.p9k` files.
+- Internal changes:
+  - All comments have been updated for uniformity and for API generation.
+  - iTerm integration added.
+  - Added `POWERLEVEL9K_PROMPT_SEGMENTS` to allow testing for segment usage in a single variable.
+  - Replaced `$1_prompt_segment()` with `p9kPrepareSegment()` to enable single call from segments irrespective of generator.
+  - Changed all internal functions to use `camelCase`. Exceptions are listed below:
+    - prompt functions still use `prompt_x()` so that we can differentiate between internal (core) functionality and segments.
+    - `prompt_powerlevel9k_setup()`, `prompt_powerlevel9k_teardown()`, and `p9k_preexec()`.
+  - `default.p9k`
+    - Added support for bold segments (already in `zsh-async`).
+    - Added support for the right segment icons to be shown on the left instead (already in `zsh-async`).
+
 ### New Segment: `laravel_version`
 
 Displays the current laravel version.

api/functions/colors.md

@@ -0,0 +1,98 @@
+# powerlevel9k Color Functions
+
+
+### Source(s)
+
+[https://github.com/bhilburn/powerlevel9k](#https://github.com/bhilburn/powerlevel9k)
+
+
+### Author(s)
+
+- Ben Hilburn (bhilburn)
+- Dominik Ritter (dritter)
+
+
+### File Description
+
+*This file contains some color-functions for powerlevel9k. *
+
+## Table of Contents
+
+- [termColors](#termColors)
+- [getColor](#getColor)
+- [backgroundColor](#backgroundColor)
+- [foregroundColor](#foregroundColor)
+- [getColorCode](#getColorCode)
+- [isSameColor](#isSameColor)
+
+## termColors
+*This function checks if the terminal supports 256 colors. If it doesn't, an error message is displayed. *
+
+#### Arguments
+
+- *Function has no arguments.*
+
+
+#### Notes
+
+*You can bypass this check by setting `P9K_IGNORE_TERM_COLORS=true`. *
+
+## getColor
+*This function gets the proper color code if it does not exist as a name. *
+
+#### Arguments
+
+- **$1** (misc) Color to check (as a number or string)
+
+
+## backgroundColor
+*Function to set the background color. *
+
+#### Arguments
+
+- **$1** (misc) The background color.
+
+
+#### Returns
+
+- An escape code string for (re)setting the background color.
+
+
+#### Notes
+
+*An empty paramenter resets (stops) background color. *
+
+## foregroundColor
+*Function to set the foreground color. *
+
+#### Arguments
+
+- **$1** (misc) The foreground color.
+
+
+#### Returns
+
+- An escape code string for (re)setting the foreground color.
+
+
+#### Notes
+
+*An empty paramenter resets (stops) foreground color. *
+
+## getColorCode
+*Function to get numerical color codes. That way we translate ANSI codes into ZSH-Style color codes. *
+
+#### Arguments
+
+- **$1** (misc) Number or string of color.
+
+
+## isSameColor
+*Check if two colors are equal, even if one is specified as ANSI code. *
+
+#### Arguments
+
+- **$1** (misc) First color (number or string)
+- **$2** (misc) Second color (number or string)
+
+

api/functions/icons.md

@@ -0,0 +1,64 @@
+# powerlevel9k Icon Functions
+
+
+### Source(s)
+
+[https://github.com/bhilburn/powerlevel9k](#https://github.com/bhilburn/powerlevel9k)
+
+
+### Author(s)
+
+- Ben Hilburn (bhilburn)
+- Dominik Ritter (dritter)
+
+
+### File Description
+
+*This file contains some the core icon definitions and icon-functions. *
+
+*These characters require the Powerline fonts to work properly. If you see boxes or bizarre characters below, your fonts are not correctly installed. If you do not want to install a special font, you can set `P9K_MODE` to `compatible`. This shows all icons in regular symbols. *
+
+## Table of Contents
+
+- [registerIcon](#registerIcon)
+- [printIcon](#printIcon)
+
+## registerIcon
+*This function allows a segment to register the icons that it requires. These icons may be overriden by the user later. Arguments may be a direct call or an array. *
+
+#### Arguments
+
+- **$1** (string) Name of icon
+- **$2** (string) Generic icon
+- **$3** (string) Flat / Awesome Patched icon
+- **$4** (string) Awesome FontConfig icon
+- **$5** (string) Awesome Mapped FontConfig icon
+- **$6** (string) NerdFont Complete / FontConfig icon
+
+
+#### Notes
+
+*You can specify a string, unicode string or codepoint string (for Mapped fonts only). *
+
+#### Usage
+
+```sh
+registerIcon "name_of_icon" 'Gen' $'\uXXX' $'\uXXX' '\u'$CODEPOINT_OF_AWESOME_xxx '\uXXX'
+
+```
+
+#### Example
+
+```sh
+registerIcon "LOCK_ICON"  $'\UE0A2'  $'\UE138'  $'\UF023'  '\u'$CODEPOINT_OF_AWESOME_LOCK  $'\UF023'
+
+```
+
+## printIcon
+*Safety function for printing icons. Prints the named icon, or if that icon is undefined, the string name. *
+
+#### Arguments
+
+- **$1** (string) Name of icon
+
+

api/functions/utilities.md

@@ -0,0 +1,138 @@
+# powerlevel9k Utility Functions
+
+
+### Source(s)
+
+[https://github.com/bhilburn/powerlevel9k](#https://github.com/bhilburn/powerlevel9k)
+
+
+### Author(s)
+
+- Ben Hilburn (bhilburn)
+- Dominik Ritter (dritter)
+
+
+### File Description
+
+*This file contains some utility-functions for the powerlevel9k ZSH theme. *
+
+## Table of Contents
+
+- [defined](#defined)
+- [setDefault](#setDefault)
+- [printSizeHumanReadable](#printSizeHumanReadable)
+- [getRelevantItem](#getRelevantItem)
+- [segmentInUse](#segmentInUse)
+- [printDeprecationWarning](#printDeprecationWarning)
+- [segmentShouldBeJoined](#segmentShouldBeJoined)
+- [truncatePath](#truncatePath)
+- [truncatePathFromRight](#truncatePathFromRight)
+- [upsearch](#upsearch)
+
+## defined
+*This function determine if a variable has been previously defined, even if empty. *
+
+#### Arguments
+
+- **$1** (string) The name of the variable that should be checked.
+
+
+#### Returns
+
+- 0 if the variable has been defined.
+
+
+## setDefault
+*This function determine if a variable has been previously defined, and only sets the value to the specified default if it hasn't. *
+
+#### Arguments
+
+- **$1** (string) The name of the variable that should be checked.
+- **$2** (string) The default value
+
+
+#### Returns
+
+- Nothing.
+
+
+#### Notes
+
+*Typeset cannot set the value for an array, so this will only work for scalar values. *
+
+## printSizeHumanReadable
+*Converts large memory values into a human-readable unit (e.g., bytes --> GB) *
+
+#### Arguments
+
+- **$1** (integer) Size - The number which should be prettified.
+- **$2** (string) Base - The base of the number (default Bytes).
+
+
+#### Notes
+
+*The base can be any of the following: B, K, M, G, T, P, E, Z, Y. *
+
+## getRelevantItem
+*Gets the first value out of a list of items that is not empty. The items are examined by a callback-function. *
+
+#### Arguments
+
+- **$1** (array) A list of items.
+- **$2** (string) A callback function to examine if the item is worthy.
+
+
+#### Notes
+
+*The callback function has access to the inner variable $item. *
+
+## segmentInUse
+*Determine if the passed segment is used in either the LEFT or RIGHT prompt arrays. *
+
+#### Arguments
+
+- **$1** (string) The segment to be tested.
+
+
+## printDeprecationWarning
+*Print a deprecation warning if an old segment is in use. *
+
+#### Arguments
+
+- **$1** (associative-array) An associative array that contains the
+- deprecated segments as keys, and the new segment names as values.
+
+
+## segmentShouldBeJoined
+*A helper function to determine if a segment should be joined or promoted to a full one. *
+
+## truncatePath
+*Given a directory path, truncate it according to the settings. *
+
+#### Arguments
+
+- **$1** (string) The directory path to be truncated.
+- **$2** (integer) Length to truncate to.
+- **$3** (string) Delimiter to use.
+- **$4** (string) Where to truncate from - "right" | "middle". If omited, assumes right.
+
+
+## truncatePathFromRight
+*Given a directory path, truncate it according to the settings for `truncate_from_right`. *
+
+#### Arguments
+
+- **$1** (string) Directory path.
+
+
+#### Notes
+
+*Deprecated. Use `truncatePath` instead. *
+
+## upsearch
+*Search recursively in parent folders for given file. *
+
+#### Arguments
+
+- **$1** (string) Filename to search for.
+