README.md

   1
   2 # Pinnacle<a name="pinnacle-pinnacle" href="#user-content-pinnacle-pinnacle"></a>
   3
   4
   5 ## Intro<a name="pinnacle-intro" href="#user-content-pinnacle-intro"></a>
   6
   7 Pinnacle provides functions for manipulating <strong>`:highlight`</strong> groups.
   8
   9
  10 ## Installation<a name="pinnacle-installation" href="#user-content-pinnacle-installation"></a>
  11
  12 To install Pinnacle, use your plug-in management system of choice.
  13
  14 If you don't have a &quot;plug-in management system of choice&quot;, I recommend Pathogen (https://github.com/tpope/vim-pathogen) due to its simplicity and robustness. Assuming that you have Pathogen installed and configured, and that you want to install Pinnacle into `~/.vim/bundle`, you can do so with:
  15
  16 ```
  17 git clone https://github.com/wincent/pinnacle.git ~/.vim/bundle/pinnacle
  18 ```
  19
  20 Alternatively, if you use a Git submodule for each Vim plug-in, you could do the following after `cd`-ing into the top-level of your Git superproject:
  21
  22 ```
  23 git submodule add https://github.com/wincent/pinnacle.git ~/vim/bundle/pinnacle
  24 git submodule init
  25 ```
  26
  27 To generate help tags under Pathogen, you can do so from inside Vim with:
  28
  29 ```
  30 :call pathogen#helptags()
  31 ```
  32
  33
  34 ## Functions<a name="pinnacle-functions" href="#user-content-pinnacle-functions"></a>
  35
  36 <p align="right"><a name="pinnaclesubnewlines" href="#user-content-pinnaclesubnewlines"><code>pinnacle#sub_newlines()</code></a></p>
  37
  38 ### `pinnacle#sub_newlines()`<a name="pinnacle-pinnaclesubnewlines" href="#user-content-pinnacle-pinnaclesubnewlines"></a>
  39
  40 Replaces newlines with spaces.
  41
  42 <p align="right"><a name="pinnaclecapturelline" href="#user-content-pinnaclecapturelline"><code>pinnacle#capturel_line()</code></a></p>
  43
  44 ### `pinnacle#capturel_line()`<a name="pinnacle-pinnaclecapturelline" href="#user-content-pinnacle-pinnaclecapturelline"></a>
  45
  46 Runs a command and returns the captured output as a single line.
  47
  48 Useful when we don't want to let long lines on narrow windows produce unwanted embedded newlines.
  49
  50 <p align="right"><a name="pinnaclecapturehighlight" href="#user-content-pinnaclecapturehighlight"><code>pinnacle#capture_highlight()</code></a></p>
  51
  52 ### `pinnacle#capture_highlight()`<a name="pinnacle-pinnaclecapturehighlight" href="#user-content-pinnacle-pinnaclecapturehighlight"></a>
  53
  54 Gets the current value of a highlight group.
  55
  56 <p align="right"><a name="pinnacleextracthighlight" href="#user-content-pinnacleextracthighlight"><code>pinnacle#extract_highlight()</code></a></p>
  57
  58 ### `pinnacle#extract_highlight()`<a name="pinnacle-pinnacleextracthighlight" href="#user-content-pinnacle-pinnacleextracthighlight"></a>
  59
  60 Extracts a highlight string from a group, recursively traversing linked groups, and returns a string suitable for passing to `:highlight`.
  61
  62 <p align="right"><a name="pinnacleextractbg" href="#user-content-pinnacleextractbg"><code>pinnacle#extract_bg()</code></a></p>
  63
  64 ### `pinnacle#extract_bg()`<a name="pinnacle-pinnacleextractbg" href="#user-content-pinnacle-pinnacleextractbg"></a>
  65
  66 Extracts just the bg portion of the specified highlight group.
  67
  68 <p align="right"><a name="pinnacleextractfg" href="#user-content-pinnacleextractfg"><code>pinnacle#extract_fg()</code></a></p>
  69
  70 ### `pinnacle#extract_fg()`<a name="pinnacle-pinnacleextractfg" href="#user-content-pinnacle-pinnacleextractfg"></a>
  71
  72 Extracts just the bg portion of the specified highlight group.
  73
  74 <p align="right"><a name="pinnacleextractcomponent" href="#user-content-pinnacleextractcomponent"><code>pinnacle#extract_component()</code></a></p>
  75
  76 ### `pinnacle#extract_component()`<a name="pinnacle-pinnacleextractcomponent" href="#user-content-pinnacle-pinnacleextractcomponent"></a>
  77
  78 Extracts a single component (eg. &quot;bg&quot;, &quot;fg&quot;, &quot;italic&quot; etc) from the specified highlight group.
  79
  80 <p align="right"><a name="pinnacledump" href="#user-content-pinnacledump"><code>pinnacle#dump()</code></a></p>
  81
  82 ### `pinnacle#dump()`<a name="pinnacle-pinnacledump" href="#user-content-pinnacle-pinnacledump"></a>
  83
  84 Returns a dictionary representation of the specified highlight group.
  85
  86 <p align="right"><a name="pinnaclehighlight" href="#user-content-pinnaclehighlight"><code>pinnacle#highlight()</code></a></p>
  87
  88 ### `pinnacle#highlight()`<a name="pinnacle-pinnaclehighlight" href="#user-content-pinnacle-pinnaclehighlight"></a>
  89
  90 Returns a string representation of a dictionary containing bg, fg, term, cterm and guiterm entries.
  91
  92 <p align="right"><a name="pinnacleitalicize" href="#user-content-pinnacleitalicize"><code>pinnacle#italicize()</code></a></p>
  93
  94 ### `pinnacle#italicize()`<a name="pinnacle-pinnacleitalicize" href="#user-content-pinnacle-pinnacleitalicize"></a>
  95
  96 Returns an italicized copy of `group` suitable for passing to `:highlight`.
  97
  98 <p align="right"><a name="pinnacleembolden" href="#user-content-pinnacleembolden"><code>pinnacle#embolden()</code></a></p>
  99
 100 ### `pinnacle#embolden()`<a name="pinnacle-pinnacleembolden" href="#user-content-pinnacle-pinnacleembolden"></a>
 101
 102 Returns a bold copy of `group` suitable for passing to `:highlight`.
 103
 104 <p align="right"><a name="pinnacleunderline" href="#user-content-pinnacleunderline"><code>pinnacle#underline()</code></a></p>
 105
 106 ### `pinnacle#underline()`<a name="pinnacle-pinnacleunderline" href="#user-content-pinnacle-pinnacleunderline"></a>
 107
 108 Returns an underlined copy of `group` suitable for passing to `:highlight`.
 109
 110 <p align="right"><a name="pinnacledecorate" href="#user-content-pinnacledecorate"><code>pinnacle#decorate()</code></a></p>
 111
 112 ### `pinnacle#decorate()`<a name="pinnacle-pinnacledecorate" href="#user-content-pinnacle-pinnacledecorate"></a>
 113
 114 Returns a copy of `group` decorated with `style` (eg. &quot;bold&quot;, &quot;italic&quot; etc) suitable for passing to `:highlight`.
 115
 116 To decorate with multiple styles, `style` should be a comma-separated list.
 117
 118
 119 ## Website<a name="pinnacle-website" href="#user-content-pinnacle-website"></a>
 120
 121 The official Pinnacle source code repo is at:
 122
 123 http://git.wincent.com/pinnacle.git
 124
 125 Mirrors exist at:
 126
 127 - https://github.com/wincent/pinnacle
 128 - https://gitlab.com/wincent/pinnacle
 129 - https://bitbucket.org/ghurrell/pinnacle
 130
 131 Official releases are listed at:
 132
 133 http://www.vim.org/scripts/script.php?script_id=5360
 134
 135
 136 ## License<a name="pinnacle-license" href="#user-content-pinnacle-license"></a>
 137
 138 Copyright (c) 2016-present Greg Hurrell
 139
 140 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the &quot;Software&quot;), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 141
 142 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 143
 144 THE SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 145
 146
 147 ## Development<a name="pinnacle-development" href="#user-content-pinnacle-development"></a>
 148
 149
 150 ### Contributing patches<a name="pinnacle-contributing-patches" href="#user-content-pinnacle-contributing-patches"></a>
 151
 152 Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests at: https://github.com/wincent/pinnacle/pulls
 153
 154
 155 ### Cutting a new release<a name="pinnacle-cutting-a-new-release" href="#user-content-pinnacle-cutting-a-new-release"></a>
 156
 157 At the moment the release process is manual:
 158
 159 - Perform final sanity checks and manual testing
 160 - Update the <strong>[`pinnacle-history`](#user-content-pinnacle-history)</strong> section of the documentation
 161 - Verify clean work tree:
 162
 163 ```
 164 git status
 165 ```
 166
 167 - Tag the release:
 168
 169 ```
 170 git tag -s -m "$VERSION release" $VERSION
 171 ```
 172
 173 - Publish the code:
 174
 175 ```
 176 git push origin master --follow-tags
 177 git push github master --follow-tags
 178 ```
 179
 180 - Produce the release archive:
 181
 182 ```
 183 git archive -o pinnacle-$VERSION.zip HEAD -- .
 184 ```
 185
 186 - Upload to http://www.vim.org/scripts/script.php?script_id=5360
 187
 188
 189 ## Authors<a name="pinnacle-authors" href="#user-content-pinnacle-authors"></a>
 190
 191 Pinnacle is written and maintained by Greg Hurrell &lt;greg@hurrell.net&gt;.
 192
 193 Other contributors that have submitted patches include (in alphabetical order):
 194
 195 - Cody Buell
 196 - Kyle Poole
 197
 198
 199 ## History<a name="pinnacle-history" href="#user-content-pinnacle-history"></a>
 200
 201
 202 ### master (not yet released)<a name="pinnacle-master-not-yet-released" href="#user-content-pinnacle-master-not-yet-released"></a>
 203
 204 - Teach `pinnacle#decorate()` to accept a comma-separated list of styles.
 205
 206
 207 ### 1.0 (6 March 2019)<a name="pinnacle-10-6-march-2019" href="#user-content-pinnacle-10-6-march-2019"></a>
 208
 209 - Added `pinnacle#dump()`.
 210
 211
 212 ### 0.3.1 (7 June 2017)<a name="pinnacle-031-7-june-2017" href="#user-content-pinnacle-031-7-june-2017"></a>
 213
 214 - Fix another bug with augmentation of existing highlights.
 215
 216
 217 ### 0.3 (6 June 2017)<a name="pinnacle-03-6-june-2017" href="#user-content-pinnacle-03-6-june-2017"></a>
 218
 219 - Added `pinnacle#extract_bg` and `pinnacle#extract_fg`.
 220 - Fixed bug that could cause existing highlights to be incorrectly augmented.
 221
 222
 223 ### 0.2 (9 January 2017)<a name="pinnacle-02-9-january-2017" href="#user-content-pinnacle-02-9-january-2017"></a>
 224
 225 - Added `pinnacle#underline`.
 226
 227
 228 ### 0.1 (30 March 2016)<a name="pinnacle-01-30-march-2016" href="#user-content-pinnacle-01-30-march-2016"></a>
 229
 230 - Initial release.