Permalink
Browse files

Added a gemspec and a license. Expanded the README. Fixed a really gn…

…arly bug: ruby 1.8.7 responds to hash collisions differently to ruby 1.9.3 when calling Hash.invert. Had to make sure my test cases didn't test on anything that had a hash collision. It gives correct answers, it's just messy to test against. Easier to pick values that only appear once in the lookup table.
  • Loading branch information...
1 parent 2b5ca6e commit 2d90d5ff621e04d061f9b1e4c1fd20a827c019f7 @samwho committed May 1, 2012
Showing with 369 additions and 11 deletions.
  1. +18 −0 LICENSE
  2. +279 −0 README.md
  3. +27 −0 examples/vimscheme1.rb
  4. +1 −1 lib/vimcolorscheme.rb
  5. +14 −0 lib/vimcolorscheme/document.rb
  6. +4 −0 spec/base_spec.rb
  7. +2 −2 spec/hex2term_spec.rb
  8. +8 −8 spec/highlight_node_spec.rb
  9. +16 −0 vimcolorscheme.gemspec
View
@@ -0,0 +1,18 @@
+Copyright (C) 2012 Sam Rose
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), 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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", 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.
View
@@ -9,4 +9,283 @@ Installation is standard for a Ruby gem:
gem install vimcolorscheme
+# Usage
+Let's start by showing you a really small example:
+
+``` ruby
+ require 'vimcolorscheme'
+
+ scheme = VimColorScheme.new :scheme_name, :dark do
+
+ end
+
+ scheme.save_to_vim!
+```
+
+Here we're starting a new vim color scheme with the name of `:scheme_name`
+(which will be converted into a string later) and it's going to be a dark theme.
+
+At the end of this script we save the color scheme to our vim directory with the
+`save_to_vim!` method on the scheme object. This will write our color scheme to
+the file `~/.vim/colors/scheme_name.vim`. The exclamation mark means it will
+overwrite if a file with that name exists. You can omit the exclamation mark if
+you would rather be prompted.
+
+## Adding highlights
+
+Let's expand this example to actually do something useful: highlight!
+
+``` ruby
+ require 'vimcolorscheme'
+
+ scheme = VimColorScheme.new :scheme_name, :dark do
+ highlight :Normal do
+ guifg '#ffffff'
+ guibg '#000000'
+ end
+ end
+
+ scheme.save_to_vim!
+```
+
+The `highlight` method takes a name argument, which can be anything with a
+`to_s` method and a block, which gives us access to some really cool methods.
+
+There are methods for all of the following attributes: `gui`, `guifg`, `guibg`,
+`cterm`, `ctermfg`, and `ctermbg`. Calling them with no arguments will return
+their value, which is nil by default, and calling them with arguments will set
+their value.
+
+Let's have a look at what that outputs when we save the file as `vimscheme1.rb`
+and run it with:
+
+ ruby vimscheme1.rb
+
+And the output is:
+
+``` vim
+ set background=dark
+
+ highlight clear
+
+ if exists('syntax_on')
+ syntax reset
+ endif
+
+ let g:colors_name = 'scheme_name'
+
+ highlight Normal gui=NONE guifg=#ffffff guibg=#000000 cterm=NONE ctermfg=231
+ ctermbg=16
+```
+
+The top part of the file is some obligatory boilerplate stuff such as setting
+the background to light or dark, clearing the current highlighting and syntax
+and setting the color scheme name inside of vim itself.
+
+The last line is what we're interested in. The highlight line. Notice how it
+has values for both the guifg _and_ ctermfg? Internally it works out what the
+closest match is for the color and sets it for you.
+
+You don't need to accept this automatic color defaulting if you don't want. To
+stop it happening, just explicitly set what you want the ctermfg attribute to
+be:
+
+``` ruby
+ require 'vimcolorscheme'
+
+ scheme = VimColorScheme.new :scheme_name, :dark do
+ highlight :Normal do
+ guifg '#ffffff'
+ guibg '#000000'
+
+ ctermfg :none
+ ctermbg :none
+ end
+ end
+
+ scheme.save_to_vim!
+```
+
+### What about bold and underline and stuff?
+
+Setting the gui and cterm elements works slightly differently. These methods
+take as many arguments you give them. Let's see an example:
+
+``` ruby
+ require 'vimcolorscheme'
+
+ scheme = VimColorScheme.new :scheme_name, :dark do
+ highlight :Normal do
+ guifg '#ffffff'
+ guibg '#000000'
+
+ ctermfg :none
+ ctermbg :none
+
+ gui :bold, :italic
+ end
+ end
+
+ scheme.save_to_vim!
+```
+
+And the corresponding output:
+
+``` vim
+ set background=dark
+
+ highlight clear
+
+ if exists('syntax_on')
+ syntax reset
+ endif
+
+ let g:colors_name = 'scheme_name'
+
+ highlight Normal gui=bold,italic guifg=#ffffff guibg=#000000 cterm=bold,italic
+ ctermfg=NONE ctermbg=NONE
+```
+
+Notice how both `gui` _and_ `cterm` have been given bold and italic properties?
+This should hopefully make color scheme development simpler and more
+expressive by harnessing the power of Ruby.
+
+## Comments
+
+If you want to add comments into your resulting color scheme file that's
+possible too! Check this out:
+
+``` ruby
+ require 'vimcolorscheme'
+
+ scheme = VimColorScheme.new :scheme_name, :dark do
+ comment "author: Sam Rose <samwho@lbak.co.uk>"
+
+ highlight :Normal do
+ guifg '#ffffff'
+ guibg '#000000'
+
+ ctermfg :none
+ ctermbg :none
+
+ gui :bold, :italic
+ end
+ end
+
+ scheme.save_to_vim!
+```
+
+See that `comment` line near the top? That tells people that I authored this
+theme. Let's see what it looks like in the vim file:
+
+``` vim
+ " author: Sam Rose <samwho@lbak.co.uk>
+
+ set background=dark
+
+ highlight clear
+
+ if exists('syntax_on')
+ syntax reset
+ endif
+
+ let g:colors_name = 'scheme_name'
+
+ highlight Normal gui=bold,italic guifg=#ffffff guibg=#000000 cterm=bold,italic
+ ctermfg=NONE ctermbg=NONE
+```
+
+We now have a comment at the top! Sweet. The astute among you may be curious
+about the placement of the boilerplate code. Why isn't it above the comment?
+Comments at the start of a document are treated specially. Before the document
+is created, vimcolorscheme looks through what we've done and all comments that
+happen before anything else are placed at the very top of the file. In short,
+all comments that you create before you create anything else will end up at the
+very top of the file.
+
+### Block comments
+
+You can also insert comments using blocks. This following snippet of code is
+exactly the same as the last one:
+
+``` ruby
+ require 'vimcolorscheme'
+
+ scheme = VimColorScheme.new :scheme_name, :dark do
+ comment do
+ "author: Sam Rose <samwho@lbak.co.uk>"
+ end
+
+ highlight :Normal do
+ guifg '#ffffff'
+ guibg '#000000'
+
+ ctermfg :none
+ ctermbg :none
+
+ gui :bold, :italic
+ end
+ end
+
+ scheme.save_to_vim!
+```
+
+## Raw input
+
+This DSL isn't perfect. There are things you can't do. Because of this, the
+ability to implement raw strings into the document is present. With this we can
+do things such as define vim variable or insert if statements into our color
+scheme file. Example:
+
+``` ruby
+ require 'vimcolorscheme'
+
+ scheme = VimColorScheme.new :scheme_name, :dark do
+ comment do
+ "author: Sam Rose <samwho@lbak.co.uk>"
+ end
+
+ raw "if version < 700"
+ raw " finish"
+ raw "endif\n"
+
+ highlight :Normal do
+ guifg '#ffffff'
+ guibg '#000000'
+
+ ctermfg :none
+ ctermbg :none
+
+ gui :bold, :italic
+ end
+ end
+
+ scheme.save_to_vim!
+```
+
+Let's see what that gives us:
+
+``` vim
+ " author: Sam Rose <samwho@lbak.co.uk>
+
+ set background=dark
+
+ highlight clear
+
+ if exists('syntax_on')
+ syntax reset
+ endif
+
+ let g:colors_name = 'scheme_name'
+
+ if version < 700
+ finish
+ endif
+
+ highlight Normal gui=bold,italic guifg=#ffffff guibg=#000000
+ cterm=bold,italic ctermfg=NONE ctermbg=NONE
+```
+
+As expected, the if statement is just pasted in verbatim. It's not pretty, but
+it lets us do things the DSL wouldn't let us do "natively".
@@ -0,0 +1,27 @@
+# In your code, this LOAD_PATH malarky won't be necessary because the gem will
+# already be on your load path. This is just here for my own testing purposes so
+# that I can test the examples against the latest code base.
+libdir = File.absolute_path(File.dirname(__FILE__)) + '/../lib'
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
+
+require 'vimcolorscheme'
+
+scheme = VimColorScheme.new :scheme_name, :dark do
+ comment "author: Sam Rose <samwho@lbak.co.uk>"
+
+ raw "if version < 700"
+ raw " finish"
+ raw "endif\n"
+
+ highlight :Normal do
+ guifg '#ffffff'
+ guibg '#000000'
+
+ ctermfg :none
+ ctermbg :none
+
+ gui :bold, :italic
+ end
+end
+
+scheme.save_to_vim!
@@ -1,4 +1,4 @@
-libdir = File.absolute_path(File.dirname(__FILE__))
+libdir = File.dirname(__FILE__)
$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
module VimColorScheme
@@ -113,6 +113,20 @@ def save_to_vim!
def to_s
result = ''
+ # If the document starts with comments, we want to print those at the top.
+ top_comments = @nodes.take_while { |node| node.is_a? CommentNode }
+ top_comments.each do |comment|
+ result += comment.to_s
+ end
+
+ # Vanity new lines ftw.
+ result += "\n"
+
+ # Pop the top comments off the node list.
+ top_comments.length.times do
+ @nodes.shift
+ end
+
if @lightordark == :dark
result += "set background=dark\n\n"
else
View
@@ -78,6 +78,10 @@
test_scheme.should include('" This is a block comment!' + "\n")
end
+ it 'should render comments at the top... at the top' do
+ test_scheme.start_with?('" This is a comment!' + "\n").should be_true
+ end
+
it 'should render raw' do
test_scheme.should include("Some raw input.\n")
end
@@ -9,7 +9,7 @@ def convert value
it "correctly convert hex colors to term colors" do
convert('123456').should == '23'
- convert('ffffff').should == '231'
+ convert('00af00').should == '34'
convert('odadd6').should == '38'
convert('231').should == '#ffffff'
@@ -19,7 +19,7 @@ def convert value
it "correctly handle hex number with leading hashes" do
convert('#123456').should == '23'
- convert('#ffffff').should == '231'
+ convert('#00af00').should == '34'
convert('#odadd6').should == '38'
end
end
Oops, something went wrong.

0 comments on commit 2d90d5f

Please sign in to comment.