From 3dc5084e40b2e10272d072c7d6f05b642016e326 Mon Sep 17 00:00:00 2001 From: Dominik Ritter Date: Thu, 4 Jun 2015 03:58:27 +0200 Subject: [PATCH 1/2] Added a little "Developers Guide" --- README.md | 52 ++++++++++++++++++++++++++++++++++++++++++ powerlevel9k.zsh-theme | 19 +++++++++++---- 2 files changed, 66 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index dc8798fe..76b98ea7 100644 --- a/README.md +++ b/README.md @@ -256,3 +256,55 @@ Please submit your contribution as a Github pull-request. If you would like to contact me directly, you can find my e-mail address on my [Github profile page](https://github.com/bhilburn). +#### Developers Guide + +The theme has grown a lot lately, so I think a little explanation would be +helpful. + +##### Basic Knowledge + +Our main entry point are the `PROMPT` and `RPROMPT` variables, which are +interpreted by zsh itself. All that this (and any other) theme does is +filling these two variables with control instructions (like defining +colors, etc.) and ready-to-use data. So within this theme we collect a +whole bunch of information to put in that variables. You can find +`PROMPT` and `RPROMPT` at the very end of the `powerlevel9k.zsh-theme`. + +This simple diagram may explain the invoking order better: + +``` ++-----+ +---------+ +| Zsh |--->| $PROMPT | ++-----+ +---------+ + | + V + +---------------------+ +------------+ +---------------------+ + | build_left_prompt() |--->| prompt_*() |->| $1_prompt_segment() | + +---------------------+ +------------+ +---------------------+ +``` + +##### Adding Segments + +Feel free to add your own segments. Every segment gets called with an +orientation as first parameter (`left` or `right`), so we can figure +out on which side we should draw the segment. This information is +used at the time we call the actual segment-drawing function: +`$1_prompt_segment`. To make the magic color-overwrite mechanism to +work, we have to pass our function name as first argument. Usually +this is just `$0`. Second parameter is a default background color, +third the default foreground color. And finally we pass our content +to the function. So our function could look somewhat like this: + +```zsh + prompt_echo() { + local content='Hello World!' + $1_prompt_segment $0 blue red $content + } +``` + +At this point we can overwrite our blue-on-red segment by putting + + POWERLEVEL9K_ECHO_FOREGROUND="200" + POWERLEVEL9K_ECHO_BACKGROUND="040" + +in our `~/.zshrc`. We now have a pink-on-green segment. Yay! diff --git a/powerlevel9k.zsh-theme b/powerlevel9k.zsh-theme index f65143a1..726ccbb9 100644 --- a/powerlevel9k.zsh-theme +++ b/powerlevel9k.zsh-theme @@ -135,8 +135,13 @@ fi ################################################################ # Begin a left prompt segment -# Takes two arguments, background and foreground. Both can be omitted, -# rendering default background/foreground. +# Takes four arguments: +# * $1: Name of the function that was orginally invoked (mandatory). +# Necessary, to make the dynamic color-overwrite mechanism work. +# * $2: Background color +# * $3: Foreground color +# * $4: The segment content +# The latter three can be omitted, left_prompt_segment() { # Overwrite given background-color by user defined variable for this segment. # We get as first Parameter the function name, which called this function. @@ -177,9 +182,13 @@ left_prompt_end() { } # Begin a right prompt segment -# Takes two arguments, background and foreground. Both can be omitted, -# rendering default background/foreground. No ending for the right prompt -# segment is needed (unlike the left prompt, above). +# Takes four arguments: +# * $1: Name of the function that was orginally invoked (mandatory). +# Necessary, to make the dynamic color-overwrite mechanism work. +# * $2: Background color +# * $3: Foreground color +# * $4: The segment content +# No ending for the right prompt segment is needed (unlike the left prompt, above). right_prompt_segment() { # Overwrite given background-color by user defined variable for this segment. local BACKGROUND_USER_VARIABLE=POWERLEVEL9K_${(U)1#prompt_}_BACKGROUND From 3a857c276d28503d293634b0a1d1ce1eb3b15ff0 Mon Sep 17 00:00:00 2001 From: Ben Hilburn Date: Fri, 10 Jul 2015 20:39:27 -0700 Subject: [PATCH 2/2] README: Moving Dev Guide to Github wiki --- README.md | 59 ++++++------------------------------------------------- 1 file changed, 6 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index ff124b2e..0f3867b2 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,7 @@ like with a normal installation and default settings: - [Gaps Between Segments](#gaps-between-segments) - [Meta](#meta) - [Kudos](#kudos) + - [Developing](#developing) - [Contributions / Bugs / Contact](#contributions--bugs--contact) @@ -414,6 +415,11 @@ This theme wouldn't have happened without inspiration from the original [agnoste Before creating this theme, I also tried [jeremyFreeAgent's theme](https://github.com/jeremyFreeAgent/oh-my-zsh-powerline-theme) and [maverick2000's theme, ZSH2000](https://github.com/maverick2000/zsh2000). +#### Developing + +Documentation for developers is kept on the [Powerlevel9k Github +wiki](https://github.com/bhilburn/powerlevel9k/wiki/Developers'-Guide). + #### Contributions / Bugs / Contact If you have any requests or bug reports, please use the tracker in this Github @@ -423,56 +429,3 @@ I'm happy to accept code contributions from anyone who has a bug fix, new featur If you would like to contact me directly, you can find my e-mail address on my [Github profile page](https://github.com/bhilburn). - -#### Developers Guide - -The theme has grown a lot lately, so I think a little explanation would be -helpful. - -##### Basic Knowledge - -Our main entry point are the `PROMPT` and `RPROMPT` variables, which are -interpreted by zsh itself. All that this (and any other) theme does is -filling these two variables with control instructions (like defining -colors, etc.) and ready-to-use data. So within this theme we collect a -whole bunch of information to put in that variables. You can find -`PROMPT` and `RPROMPT` at the very end of the `powerlevel9k.zsh-theme`. - -This simple diagram may explain the invoking order better: - -``` -+-----+ +---------+ -| Zsh |--->| $PROMPT | -+-----+ +---------+ - | - V - +---------------------+ +------------+ +---------------------+ - | build_left_prompt() |--->| prompt_*() |->| $1_prompt_segment() | - +---------------------+ +------------+ +---------------------+ -``` - -##### Adding Segments - -Feel free to add your own segments. Every segment gets called with an -orientation as first parameter (`left` or `right`), so we can figure -out on which side we should draw the segment. This information is -used at the time we call the actual segment-drawing function: -`$1_prompt_segment`. To make the magic color-overwrite mechanism to -work, we have to pass our function name as first argument. Usually -this is just `$0`. Second parameter is a default background color, -third the default foreground color. And finally we pass our content -to the function. So our function could look somewhat like this: - -```zsh - prompt_echo() { - local content='Hello World!' - $1_prompt_segment $0 blue red $content - } -``` - -At this point we can overwrite our blue-on-red segment by putting - - POWERLEVEL9K_ECHO_FOREGROUND="200" - POWERLEVEL9K_ECHO_BACKGROUND="040" - -in our `~/.zshrc`. We now have a pink-on-green segment. Yay!