vimcolorscheme 0.1

data/Gemfile.lock

@@ -0,0 +1,28 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    coderay (1.0.6)
+    diff-lcs (1.1.3)
+    method_source (0.7.1)
+    pry (0.9.9.4)
+      coderay (~> 1.0.5)
+      method_source (~> 0.7.1)
+      slop (>= 2.4.4, < 3)
+    rake (0.9.2.2)
+    rspec (2.9.0)
+      rspec-core (~> 2.9.0)
+      rspec-expectations (~> 2.9.0)
+      rspec-mocks (~> 2.9.0)
+    rspec-core (2.9.0)
+    rspec-expectations (2.9.1)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.9.0)
+    slop (2.4.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  pry
+  rake
+  rspec

data/README.md

@@ -0,0 +1,293 @@
+This is a Ruby DSL for creating Vim color schemes. I personally found color
+schemes difficult to get working in both terminal and graphical interfaces, this
+DSL tries to remedy that by, for example, automatically filling in the value of
+guibg by looking at ctermbg.
+
+[![Build Status](https://secure.travis-ci.org/samwho/vimcolorscheme.png?branch=master)](http://travis-ci.org/samwho/vimcolorscheme)
+
+# Installation
+
+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".

data/examples/simple_theme.rb

@@ -0,0 +1,20 @@
+# 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'
+
+VimColorScheme.new :simple_theme, :dark do
+  highlight :Normal do
+    ctermfg 231
+    ctermbg :none
+  end
+
+  comment "Highlighting for a constant in Ruby."
+  highlight :rubyConstant do
+    guifg '#ff0000'
+    gui   :bold
+  end
+end.save_to_vim!

data/examples/vimscheme1.rb

@@ -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!

data/lib/vimcolorscheme.rb

@@ -0,0 +1,13 @@
+libdir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
+
+module VimColorScheme
+  ROOTDIR = File.expand_path(File.dirname(__FILE__) + '/..')
+end
+
+require 'vimcolorscheme/hex2term'
+require 'vimcolorscheme/highlight_node'
+require 'vimcolorscheme/comment_node'
+require 'vimcolorscheme/raw_node'
+require 'vimcolorscheme/document'
+require 'vimcolorscheme/base'

data/lib/vimcolorscheme/base.rb

@@ -0,0 +1,11 @@
+module VimColorScheme
+  module Base
+    def new name, lightordark, &block
+      @document = VimColorScheme::Document.new(name, lightordark)
+      @document.instance_eval(&block)
+      @document
+    end
+  end
+
+  extend Base
+end

data/lib/vimcolorscheme/comment_node.rb

@@ -0,0 +1,15 @@
+module VimColorScheme
+  class CommentNode
+    # Initializes the comment node with a comment string.
+    def initialize comment
+      @comment = comment
+    end
+
+    # Renders the comment node by splitting the string at newlines and then
+    # appending the " comment character at the start of each line and joining
+    # the result with newlines.
+    def to_s
+      @comment.split(/\n/).map { |str| str = '" ' + str }.join("\n") + "\n"
+    end
+  end
+end

data/lib/vimcolorscheme/document.rb

@@ -0,0 +1,149 @@
+module VimColorScheme
+  class Document
+    # Creates a new color scheme document. The user will never call this method
+    # themselves but an object of this class is what they will be working with
+    # through the DSL.
+    #
+    # This constructor takes the name of the color scheme, whether it is light
+    # or dark and an optional option hash as arguments.
+    def initialize name, lightordark, options = {}
+      @name        = name
+      @lightordark = lightordark
+      @options     = options
+      @nodes       = []
+    end
+
+    # Creates a highlight node in the document. You need to give this method
+    # call a name and a clock. Here's a usage example:
+    #
+    #   highlight :Normal do
+    #     cterm :bold, :underline
+    #   end
+    def highlight name, &block
+      @nodes << HighlightNode.new(name)
+      @nodes.last.instance_eval(&block)
+    end
+
+    # Creates a comment node in the document. It takes a single argument, which
+    # is the string that will be in the comment. You don't need to include the "
+    # comment character in the string, that will be done for you when the vim
+    # color scheme document is created.
+    #
+    # Example:
+    #
+    #   comment "This is a comment!"
+    #
+    # Alternately, you can create a comment by returning a string from a block:
+    #
+    #   comment do
+    #     "This is a comment!"
+    #   end
+    #
+    # Both examples above yield the same result.
+    def comment string = nil
+      if block_given?
+        @nodes << CommentNode.new(yield)
+      else
+        @nodes << CommentNode.new(string)
+      end
+    end
+
+    # Creates a raw node in the current document. Raw nodes are inteded for
+    # users that want to insert code into their vim color scheme that we don't
+    # currently have a native implementation for.
+    #
+    # Example:
+    #
+    #   raw "let g:my_var = 'variable!'"
+    #
+    # You can also give raw a block that returns a string:
+    #
+    #   raw do
+    #     "let g:my_var = 'variable!'"
+    #   end
+    #
+    # The two examples above are functionally the same. The strings that are
+    # passed to raw will be printed as-is into the vim color scheme file.
+    def raw string = nil
+      if block_given?
+        @nodes << RawNode.new(yield)
+      else
+        @nodes << RawNode.new(string)
+      end
+    end
+
+    # Saves this color scheme to a file. If the file exists, the user will be
+    # prompted as to whether or not they want to overwrite the file.
+    def save path
+      if File.exists?(path)
+        puts "#{path} already exists! Overwrite? y/n"
+        answer = gets
+        unless answer == 'n' or answer == 'N'
+          File.open(path, 'w') do |file|
+            file.write(to_s)
+          end
+        end
+      end
+    end
+
+    # Does exactly the same as the save method excpet it doesn't prompt the user
+    # if the file exists, it just goes ahead and overwrites it.
+    def save! path
+      File.open(path, 'w') do |file|
+        file.write(to_s)
+      end
+    end
+
+    # This method will save the color scheme into the user's ~/.vim/colors
+    # directory. If the scheme already exists, the user will be prompted asking
+    # if they want to overwrite it.
+    def save_to_vim
+      save(File.expand_path("~/.vim/colors/#{@name.to_s}.vim"))
+    end
+
+    # This method does exactly the same as the save_to_vim method but it will
+    # not ask if you want to overwrite a file if it exists already, it will just
+    # overwrite it.
+    def save_to_vim!
+      save!(File.expand_path("~/.vim/colors/#{@name.to_s}.vim"))
+    end
+
+    # This method converts the object into a valid vim color scheme document. It
+    # is what is used to create the color schemes at the end of the DSL block.
+    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
+        result += "set background=light\n\n"
+      end
+
+      result += "highlight clear\n\n"
+      result += "if exists('syntax_on')\n"
+      result += "  syntax reset\n"
+      result += "endif\n\n"
+      result += "let g:colors_name = '#{@name.to_s}'\n\n"
+
+      @nodes.each do |node|
+        result += node.to_s
+      end
+
+      return result
+    end
+  end
+end