vim-flavor 0.0.4 → 1.0.0

data/features/install_vim_flavor.md

@@ -0,0 +1,42 @@
+## Required softwares
+
+* [Git](http://git-scm.com/) 1.7.9 or later
+* [Ruby](http://www.ruby-lang.org/) 1.9.2 or later
+  * Recommendation: Use [RVM](http://beginrescueend.com/) or other tools
+    for ease of installation across different envinronments.
+* [Vim](http://www.vim.org/) 7.3 or later
+  * Note that Vim should be compiled as normal, big or huge version
+    to use most of plugins.
+
+
+
+
+## Supported platforms
+
+* Unix-like environments such as Linux, Mac OS X, etc.
+* Though Microsoft Windows is not directly supported,
+  it is possible to manage Vim plugins via Cygwin or other environments.
+
+
+
+
+## Installation steps
+
+    gem install vim-flavor
+
+    cd $YOUR_REPOSITORY_FOR_DOTFILES
+
+    # Add the following line into the first line of your vimrc:
+    #
+    #   runtime flavors/bootstrap.vim
+    vim vimrc
+
+    touch VimFlavor VimFlavor.lock
+
+    git add VimFlavor VimFlavor.lock vimrc
+    git commit -m 'Use vim-flavor to manage my favorite Vim plugins'
+
+
+
+
+<!-- vim: set expandtab shiftwidth=4 softtabstop=4 textwidth=78 : -->

data/features/philosophy.md

@@ -0,0 +1,90 @@
+## Installable plugins
+
+Not all Vim plugins can be installed with vim-flavor.
+vim-flavor can install plugins which meet the following conditions:
+
+* Plugins must have dedicated Git repositories.
+  vim-flavor does not support other version control systems.
+  This is an intentional design.  Because:
+  * [vim-scripts.org](http://vim-scripts.org/) provides
+    [comprehensive Git mirrors](https://github.com/vim-scripts) for
+    [plugins uploaded to www.vim.org](http://www.vim.org/scripts/index.php).
+  * Experimental plugins which are not uploaded to www.vim.org
+    are usually found in [GitHub](https://github.com/).
+* Plugins must follow [the versioning pocilies of
+  RubyGems](http://docs.rubygems.org/read/chapter/7#page26) and have "version"
+  tags in their repositories.  For example, if there is the version 1.2.3 of
+  a plugin, its repository must have the tag `1.2.3`, and the files of the
+  version 1.2.3 can be checked out via the tag `1.2.3`.  In other words,
+  plugins which do not have proper tags are not installable.
+  This is an intentional design.  Because:
+  * It's not possible to determine whether two versions are compatible or not
+    without "version" tags.  Compatibility is a big problem to resolve
+    dependencies of plugins.  For example, if plugin A requires plugin X 1.2.3
+    or later while plugin B requires plugin X 2.0 or later, it's not possible
+    to use A and B at the same time.  Such problems should be detected before
+    installing plugins.
+  * Git mirrors by vim-scripts.org are tagged with version numbers.
+  * Some Git repositories might not have "version" tags.
+    Such plugins are not ready to use for everyone.
+    So that it should not be installable.
+* Plugins must have proper directory structures.
+  For example, directories such as `autoload`, `syntax` etc should exist in
+  the roots of plugins.
+  This is an intentional design.  Because:
+  * Git mirrors by vim-scripts.org have proper directory structures even if
+    the original plugins are uploaded to www.vim.org without proper directory
+    structures.  (A good example is
+    [a.vim](http://www.vim.org/scripts/script.php?script_id=31) and
+    [its mirror](https://github.com/vim-scripts/a.vim).)
+  * Other Git repositories might not have proper directory structures.
+    Such plugins are not ready to use for everyone.
+    So that it should not be installable.
+
+
+
+
+## Why make another management tool?
+
+I know that there are several implementations for the same purpose and many
+users love them, but all of them do not meet my taste.  That's why I wrote
+vim-flavor.  The philosophy on vim-flavor is as follows:
+
+Whole configuration including *versions of plugins* should be under a version
+control system.  All of existing implementations do not manage versions of
+plugins.  This means that *it's not possible to use the same configuration
+across multiple environments* (the only one exception is using
+[pathogen](https://github.com/tpope/vim-pathogen) with Git submodules,
+but you'll find it's painful to manually manage many plugins).
+
+There should be a standard way to describe proper dependencies of plugins to
+install dependencies without explicit declarations.  Most of existing
+implementations do not resolve dependencies automatically (the only one
+exception is
+[vim-addon-manager](https://github.com/MarcWeber/vim-addon-manager), but it
+doesn't take care about required versions).  The configuration file formats of
+vim-flavor are also used to describe dependencies of plugins with required
+versions.  This means that vim-flavor installs plugins and their dependencies
+automatically (unfortunately this feature is not implemented yet, but it'll be
+available soon).
+
+Any software should have enough and reproducible test cases.
+But existing implementations such as
+[vundle](https://github.com/gmarik/vundle) and
+[neobundle](https://github.com/Shougo/neobundle.vim) are not developed so.
+It's horrible for me.
+
+Installation steps should be small, be reproducible, and not affect existing
+environment as less as possible.  Most of existing implementations require to
+manually tweak `~/.vim` etc.  It's painful to set up such stuffs manually
+because a vimfiles path is varied on each platform.
+
+Finally, a tool and files deployed by the tool should be uninstalled easily.
+[Vimana](https://github.com/c9s/Vimana) does not meet this because it directly
+puts files into `~/.vim/colors` etc and it doesn't provide `uninstall`
+command.
+
+
+
+
+<!-- vim: set expandtab shiftwidth=4 softtabstop=4 textwidth=78 : -->

data/features/resolve_dependencies.feature

@@ -0,0 +1,16 @@
+Feature: Resolve dependencies of Vim plugins
+  In order to hide details of dependencies,
+  as a lazy Vim user,
+  I want to resolve and install dependencies of Vim plugins automatically.
+
+  # TODO
+  Scenario: Resolve 2-level dependencies
+
+  # TODO
+  Scenario: Resolve 3-level dependencies
+
+  # TODO
+  Scenario: Resolve dependencies of a plugin required by two or more plugins
+
+  # TODO
+  Scenario: Resolve dependencies of a plugin required by plugins and user

data/features/step_definitions/bootstrap_script_steps.rb

@@ -0,0 +1,7 @@
+Then /^I get a bootstrap script in '(.+)'$/ do |virtual_path|
+  File.should exist(
+    expand(virtual_path).
+    to_flavors_path.
+    to_bootstrap_path
+  )
+end

data/features/step_definitions/cli_steps.rb

@@ -0,0 +1,34 @@
+When /^I run `vim-flavor(.*)`(?: again)?(?:,? (but))?$/ do |args, mode|
+  begin
+    original_home = ENV['HOME']
+    ENV['HOME'] = expand('$home')
+    Dir.chdir(expand('$tmp')) do
+      original_stdout = $stdout
+      begin
+        $stdout = @output = StringIO.new()
+        Vim::Flavor::CLI.start(args.strip().split(/\s+/).map {|a| expand(a)})
+      rescue RuntimeError => e
+        @last_error = e
+      ensure
+        $stdout = original_stdout
+      end
+      if mode == 'but'
+        raise RuntimeError, 'Command succeeded unexpectedly' if not @last_error
+      else
+        raise @last_error if @last_error
+      end
+    end
+  ensure
+    ENV['HOME'] = original_home
+  end
+end
+
+Then /^it fails with messages like$/ do |pattern|
+  @last_error.should_not be_nil
+  @last_error.message.should match Regexp.new(pattern.strip().gsub(/\s+/, '\s+'))
+end
+
+Then 'it outputs progress like' do |text|
+  # For some reason, Cucumber drops the last newline from every docstring...
+  @output.string.should include expand(text + "\n")
+end

data/features/step_definitions/directory_steps.rb

@@ -0,0 +1,23 @@
+require 'tmpdir'
+
+Given /^a temporary directory called '(.+)'$/ do |name|
+  path = Dir.mktmpdir
+  at_exit do
+    delete_path path
+  end
+  variable_table[name] = path
+end
+
+Given /^a home directory called '(.+)' in '(.+)'$/ do |name, virtual_path|
+  actual_path = expand(virtual_path)
+  Dir.mkdir actual_path, 0700
+  variable_table[name] = actual_path
+end
+
+Given /^I don't have a directory called '(.+)'$/ do |virtual_path|
+  Dir.should_not exist(expand(virtual_path))
+end
+
+Given /^I delete '(.+)'$/ do |virtual_path|
+  delete_path expand(virtual_path)
+end

data/features/step_definitions/flavor_steps.rb

@@ -0,0 +1,37 @@
+Given /^a repository '(.+)' with versions '(.+)'$/ do |basename, versions|
+  repository_path = make_repo_path(basename)
+  doc_name = basename.split('/').last.sub(/^vim-/, '')
+  variable_table["#{basename}_uri"] = make_repo_uri(basename)
+  system <<-"END"
+    {
+      mkdir -p '#{repository_path}' &&
+      cd '#{repository_path}' &&
+      git init &&
+      mkdir doc &&
+      for v in #{versions}
+      do
+        echo "*#{doc_name}* $v" >'doc/#{doc_name}.txt'
+        git add doc
+        git commit -m "Version $v"
+        git tag -m "Version $v" "$v"
+      done
+    } >/dev/null
+  END
+end
+
+Given /^I disable network to the original repository of '(.+)'$/ do |basename|
+  delete_path make_repo_path(basename)
+end
+
+Then /^I get flavor '(.+)' with '(.+)' in '(.+)'$/ do |v_repo_name, version, virtual_path|
+  flavor_path = make_flavor_path(expand(virtual_path), expand(v_repo_name))
+  basename = expand(v_repo_name).split('/').last.sub(/^vim-/, '')
+  File.open("#{flavor_path}/doc/#{basename}.txt", 'r').read().should ==
+    "*#{basename}* #{version}\n"
+  File.should exist("#{flavor_path}/doc/tags")
+end
+
+Then /^I don't have flavor '(.+)' in '(.+)'$/ do |v_repo_name, virtual_path|
+  flavor_path = make_flavor_path(expand(virtual_path), expand(v_repo_name))
+  Dir.should_not exist(flavor_path)
+end

data/features/step_definitions/flavorfile_steps.rb

@@ -0,0 +1,12 @@
+Given 'flavorfile' do |content|
+  create_file expand('$tmp').to_flavorfile_path, expand(content)
+end
+
+When 'I edit flavorfile as' do |content|
+  steps %Q{
+    Given flavorfile
+    """
+    #{content}
+    """
+  }
+end

data/features/step_definitions/lockfile_steps.rb

@@ -0,0 +1,13 @@
+Given 'lockfile' do |content|
+  create_file expand('$tmp').to_lockfile_path, expand(content)
+end
+
+Given /^I delete lockfile$/ do
+  delete_path expand('$tmp').to_lockfile_path
+end
+
+Then 'I get lockfile' do |content|
+  # For some reason, Cucumber drops the last newline from every docstring...
+  File.open(expand('$tmp').to_lockfile_path, 'r').read().should ==
+    (content == '' ? '' : expand(content) + "\n")
+end

data/features/support/env.rb

@@ -0,0 +1,49 @@
+require 'fileutils'
+require 'vim-flavor'
+
+class FakeUserEnvironment
+  def initialize()
+    env = self
+    Vim::Flavor::Flavor.instance_eval do
+      @github_repo_uri = lambda {|user, repo|
+        "file://#{env.expand('$tmp')}/repos/#{user}/#{repo}"
+      }
+    end
+  end
+
+  def create_file path, content
+    File.open(path, 'w') do |f|
+      f.write(content)
+    end
+  end
+
+  def delete_path path
+    FileUtils.remove_entry_secure(path)
+  end
+
+  def expand(virtual_path)
+    virtual_path.gsub(/\$([a-z_]+)/) {
+      variable_table[$1]
+    }
+  end
+
+  def make_flavor_path(vimfiles_path, repo_name)
+    "#{vimfiles_path.to_flavors_path}/#{repo_name.zap}"
+  end
+
+  def make_repo_path(basename)
+    "#{expand("$tmp")}/repos/#{basename}"
+  end
+
+  def make_repo_uri(basename)
+    "file://#{make_repo_path(basename)}"
+  end
+
+  def variable_table
+    @variable_table ||= Hash.new
+  end
+end
+
+World do
+  FakeUserEnvironment.new
+end

data/features/typical_usage/README.md

@@ -0,0 +1,63 @@
+## Abstract
+
+As a skilled Vim user, it is an exciting time to start using a new plugin,
+but installation is not so, because there are several steps to do like the
+following:
+
+1. Get a package of the plugin.
+2. Copy source tree in the package into `~/.vim` etc.
+3. Generate the help tags file for the plugin.
+
+It is also exciting to upgrade favorite Vim plugins to the latest version,
+but I don't want to repeat the steps for each plugin.  It's boring.
+
+Some plugins depend on other plugins, so that I have to install also
+dependencies, but it is easy to forget about dependencies.
+It's sad to see error messages like "E117: Unknown function: foo#bar".
+
+It would be better to automate these routine works with a declarative way,
+and `vim-flavor` does it.
+
+
+
+
+## Typical workflow
+
+    cd $YOUR_REPOSITORY_FOR_DOTFILES
+
+    # Add, delete or change declarations which versions of Vim plugins to use.
+    vim VimFlavor
+
+    # Install Vim plugins according to VimFlavor.
+    vim-flavor install
+
+    # Record changes to the declarations and locked status.
+    git add VimFlavor VimFlavor.lock
+    git commit -m '...'
+
+
+
+
+## Flavorfile (`VimFlavor`)
+
+`vim-flavor` reads a file `VimFlavor` in the current working directory.
+The file is called a flavorfile.  A flavorfile contains zero or more
+declarations about Vim plugins and which versions of Vim plugins to use.
+
+See also [Flavorfile details](../flavorfile).
+
+
+
+
+## Lockfile (`VimFlavor.lock`)
+
+`vim-flavor` creates a file `VimFlavor.lock` in the current working directory.
+The file is called a lockfile.  A lockfile contains details about installed
+Vim plugins to use the same configuration on every machine.
+
+You don't have to care about the content of a lockfile.
+
+
+
+
+<!-- vim: set expandtab shiftwidth=4 softtabstop=4 textwidth=78 : -->

data/features/typical_usage/deploy_to_arbitrary_place.feature

@@ -0,0 +1,24 @@
+@typical_usage
+Feature: Deploy Vim plugins to a non-standard directory
+  In order to provide flexibility,
+  as a lazy Vim user,
+  I want to deploy Vim plugins to arbitrary place.
+
+  Background:
+    Given a temporary directory called 'tmp'
+    And a home directory called 'home' in '$tmp/home'
+    And a repository 'foo' with versions '1.0.0 1.0.1 1.0.2'
+
+  Scenario: Install to specified vimfiles path which does not exist
+    Given flavorfile
+      """ruby
+      flavor '$foo_uri'
+      """
+    And I don't have a directory called '$tmp/my-vimfiles'
+    When I run `vim-flavor install --vimfiles-path=$tmp/my-vimfiles`
+    Then I get lockfile
+      """
+      $foo_uri (1.0.2)
+      """
+    And I get a bootstrap script in '$tmp/my-vimfiles'
+    And I get flavor '$foo_uri' with '1.0.2' in '$tmp/my-vimfiles'

data/features/typical_usage/install_vim_plugins.feature

@@ -0,0 +1,26 @@
+@typical_usage
+Feature: Install Vim plugins
+  In order to automate boring steps,
+  as a lazy Vim user,
+  I want to use a declarative way to start using new Vim plugins.
+
+  Background:
+    Given a temporary directory called 'tmp'
+    And a home directory called 'home' in '$tmp/home'
+    And a repository 'foo' with versions '1.0.0 1.0.1 1.0.2'
+
+  Scenario: Install from scratch
+    Given flavorfile
+      """ruby
+      """
+    When I edit flavorfile as
+      """ruby
+      flavor '$foo_uri'
+      """
+    And I run `vim-flavor install`
+    Then I get lockfile
+      """
+      $foo_uri (1.0.2)
+      """
+    And I get a bootstrap script in '$home/.vim'
+    And I get flavor '$foo_uri' with '1.0.2' in '$home/.vim'