caligari 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7d28cdbceef43dd381e3754c8edf16801550b4c8
+  data.tar.gz: 1345087a5222d642cdade41b78c21be222891030
+SHA512:
+  metadata.gz: d3f798fd7ead95117d0f6f1dfd5cbf9aec789bfa6c7ba83aaefffd912884f8550902dba6371815bfc0fa5f299ca1c584ce948ed3417f92cbfacdfba5fe0f17e2
+  data.tar.gz: 8afe108d18661153e28598f96edd97dcc478b6c5fceff2eacf4a28ccc9541a3cac92a851b7557759e291b3cb3c751d3c9d586fbcdde86c76aeddcaff8a6537c9

data/.gitignore

@@ -0,0 +1,8 @@
+.yardoc/
+doc/
+Gemfile.lock
+pkg/
+
+man/**/*.html
+man/**/*.css
+man/**/*.?

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2016 Robin Owen
+
+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.

data/README.md

@@ -0,0 +1,99 @@
+# Caligari
+_"...I must become Caligari!"_
+
+## Description
+`caligari` installs configuration files by symbolically linking all of the
+files from the given paths directly to the current user's home directory with
+the same relative file structure, creating any requisite directories as-needed.
+
+## Usage
+`caligari` allows you to exclude files matching a given `fnmatch` pattern with
+the **--exclude/-x** flag. For example, the following may be used to exclude
+all backup files and `vim` swap files:
+
+```sh
+caligari --exclude '**/*~' '**/*.swp'
+```
+
+By default, `caligari` will simply skip over any files which already exist in
+the current user's home directory; however, you can force `caligari` to
+overwrite existing files with the **--force/-f** flag:
+
+```sh
+caligari --force
+```
+
+`caligari` is normally silent except for warnings and errors; if you want more
+explicit output about the operations `caligari` performs, simply use the
+**--verbose/-V** flag. This flag will report all of the file system operations
+`caligari` performs, each with an appropriate label:
+
+  * **ln** for created symbolic links
+  * **path** for created directory paths
+  * **rm** for unlinked files
+  * **err** for any errors encountered
+
+`caligari` reports operations in this way so that they may be filtered in
+whichever way the user desires. For example, you could print a list of the
+files removed by a forceful `caligari` run like so:
+
+```sh
+caligari --force --verbose | awk '/^rm:/ { print $2 }'
+```
+
+You may also simulate the actions `caligari` would normally take upon the file
+system by passing the **--simulate/-s** flag. This implies the **--verbose**
+flag, allowing you to inspect which actions `caligari` would take if run:
+
+```
+$ caligari --simulate --force
+rm:   /home/user/do-not-remove
+ln:   /home/user/do-not-remove
+```
+
+## Configuration
+`caligari` may be configured by editing the system-wide configuration file
+(defined by default as */etc/xdg/caligari.yml*) or the per-user configuration
+file (defined by default as *~/.config/caligari.yml*). These configuration
+files are simple YAML files which define the default exclusion patterns used
+by `caligari`.
+
+Example *~/.config/caligari.yml* to automatically exclude the *.git* directory
+and all *README.md* files:
+
+```yaml
+---
+:exclude:
+- "**/.git"
+- "**/README.md"
+```
+
+## Installation
+```sh
+gem install caligari
+```
+
+## Development
+Just clone the [git repository][repo] and run `bundle install` to install the
+development and runtime dependencies:
+
+```sh
+git clone https://github.com/vthrenody/caligari.git
+cd caligari
+bundle install
+```
+
+You can run Caligari locally for development purposes by running it directly
+from the repository like so:
+
+```sh
+bin/caligari
+```
+
+To install a local copy of Caligari, simply run `rake install`.
+
+## License
+Caligari is made available under the terms of the MIT Expat license. See the
+included LICENSE file for more information.
+
+[repo]: https://www.github.com/vthrenody/caligari

data/Rakefile

@@ -0,0 +1,13 @@
+require 'bundler/gem_tasks'
+require 'md2man/rakefile'
+require 'yard'
+
+YARD::Rake::YardocTask.new do |yard|
+  yard.options = [
+    '--title', 'Caligari Documentation',
+    '--readme', 'README.md',
+    '--files', 'LICENSE',
+    '--markup', 'markdown',
+    '--private',
+  ]
+end

data/bin/caligari

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+
+require 'trollop'
+
+if $0.start_with?('/')
+  require 'caligari'
+else
+  warn 'warn: running local caligari'
+  require_relative '../lib/caligari'
+end
+
+def die(message)
+  $stderr.puts "err:  #{message}"
+  exit 1
+end
+
+options = Trollop.options do
+  version Caligari::COPYRIGHT
+  banner <<-EOS
+#{Caligari::COPYRIGHT}
+
+caligari is a simple configuration file installer. By default, this utility
+will generate symbolic links in the current user's home directory for all of
+the files present in the target path(s).
+
+Usage:
+        caligari [OPTION]... [PATH]...
+
+Options:
+EOS
+    
+  opt :exclude,  'Exclude the given files or directories', short: 'x',
+    type: :strings
+  opt :force,    'Force installation over existing files'
+  opt :simulate, 'Simulate installation (implies --verbose)'
+  opt :traverse, 'Traverse into the given paths while processing'
+  opt :verbose,  'Print verbose installation information', short: 'V'
+end
+
+# Make sure we have at least an empty array for exclusions.
+options[:exclude] ||= []
+
+# Make sure `ARGV` is populated with the current working directory if not
+# otherwise specified. Note that we use "." here instead of, for example,
+# `Dir.pwd` -- Caligari does not like absolute paths.
+ARGV.push('.') if ARGV.empty?
+
+begin
+  Caligari::Application.new(*ARGV, options).run
+rescue Psych::SyntaxError => ex
+  die("configuration is malformed:\n\t#{ex.message}")
+rescue Exception => ex
+  die(ex.message)
+end

data/caligari.gemspec

@@ -0,0 +1,31 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'caligari/version'
+
+Gem::Specification.new do |gem|
+  gem.name     = 'caligari'
+  gem.version  = Caligari::VERSION
+  gem.authors  = ['Robin Owen']
+  gem.email    = ['vthrenody@gmail.com']
+  gem.homepage = 'https://github.com/vthrenody/caligari'
+  gem.platform = Gem::Platform::RUBY
+  gem.license  = 'MIT'
+  
+  gem.summary     = 'Caligari symbolically links configuration files.'
+  gem.description = %{
+    Caligari is designed to allow the quick and easy installation of
+    configuration files by symbolically linking files from external sources
+    directly to the user's home directory.
+  }.gsub!(/\s+/, " ").strip
+  
+  %w(bundler md2man rake yard).each do |dep|
+    gem.add_development_dependency(dep)
+  end
+  gem.add_dependency('trollop')
+  
+  gem.files        = `git ls-files -z`.split("\x0")
+  gem.files       += Dir['man/man?/*.?'] # Explicitly add generated man page.
+  gem.executables  = 'caligari'
+  gem.require_path = 'lib'
+end

data/lib/caligari.rb

@@ -0,0 +1,9 @@
+require_relative 'caligari/application'
+require_relative 'caligari/xdg'
+require_relative 'caligari/version'
+
+# Caligari is designed to allow the quick and easy installation of
+# configuration files by symbolically linking files from external sources
+# directly to the user's home directory.
+module Caligari
+end

data/lib/caligari/application.rb

@@ -0,0 +1,127 @@
+require 'pathname'
+require 'yaml/store'
+
+require_relative 'xdg'
+
+module Caligari
+  # This class is instantiated and used to run a single invocation of the
+  # `caligari` application.
+  class Application
+    # The flags to be passed to `Pathname#fnmatch?` to filter exclusions.
+    FLAGS = File::FNM_DOTMATCH | File::FNM_PATHNAME
+
+    # The `Pathname` representation of the current user's home directory.
+    HOME = Pathname.new(Dir.home)
+
+    # Instantiates a new {Application} instance.
+    #
+    # @param paths [Array<String>]
+    #   the paths for this {Application} to {#run} on
+    # @param options [Hash]
+    #   the hash of options to apply to this {Application}
+    # @return [self]
+    #   the initialized {Application} instance
+    def initialize(*paths, **options)
+      @paths = paths.map { |path| Pathname.new(path) }
+      options.each do |key, value|
+        instance_variable_set(:"@#{key}", value)
+      end
+      collect_exclusions
+    end
+
+    # Runs Caligari.
+    #
+    # @return [self]
+    def run
+      @paths.each do |path|
+        fail "#{path} is not a valid path" unless path.directory?
+        if @traverse
+          Dir.chdir(path) do
+            each_file(Pathname.new('.')) { |file| link(file) }
+          end
+        else
+          each_file(path) { |file| link(file) }
+        end
+      end
+      self
+    end
+
+    # Collects the list of exclusion patterns for Caligari from a combination
+    # of XDG configuration directories and the given CLI exclusions.
+    #
+    # @note Exclusion patterns are used to filter the files to act upon via the
+    #   `Pathname#fnmatch?` instance method. The actual filtering, however,
+    #   takes place within {#each_file}.
+    #
+    # @return [Array<String>]
+    #   the array of patterns to exclude
+    #
+    # @see #each_file
+    private def collect_exclusions
+      XDG::CONFIG_FILES.each do |file|
+        config = YAML::Store.new(file)
+        @exclude |= config.transaction { config.fetch(:exclude, []) }
+      end
+      @exclude
+    end
+
+    # Recursively iterates over each file in the given `path`, excluding those
+    # which match any of the exclusion patterns collected via the
+    # {#collect_exclusions} private instance method. The given `block` is
+    # executed for each file.
+    # 
+    # @param path [Pathname]
+    #   the base directory to iterate over
+    # @yieldparam entry [Pathname]
+    #   the representation of a file
+    # @return [Array<Pathname>]
+    # 
+    # @see #collect_exclusions
+    private def each_file(path, &block)
+      path.each_child do |entry|
+        next if @exclude.any? { |pattern| entry.fnmatch?(pattern, FLAGS) }
+        entry.directory? ? each_file(entry, &block) : yield(entry)
+      end
+    end
+
+    # Symbolically links the given `file` to the current user's home directory.
+    # 
+    # @param file [Pathname]
+    #   the `Pathname` representation of a file to link
+    # @return [Boolean]
+    #   `true` if the given `file` was symbolically linked, `false` otherwise
+    private def link(file)
+      return false unless file.exist?
+      dest = HOME + file.dirname
+      unless dest.exist?
+        report "path: #{dest}"
+        dest.mkpath unless @simulate
+      end
+      dest += file.basename
+      if @force && dest.file?
+        report "rm:   #{dest}"
+        dest.delete unless @simulate
+      end
+      report "ln:   #{dest}" if @simulate || !dest.file?
+      if @simulate || dest.file?
+        false
+      else
+        dest.make_symlink(file.expand_path)
+        true
+      end
+    end
+
+    # Reports the given `message` on the given `stream` if Caligari has been
+    # configured to run in verbose or simulation mode.
+    #
+    # @param message [#to_s]
+    #   the message to report
+    # @param stream [#puts]
+    #   the stream to write a message to
+    # @return [nil]
+    private def report(message, stream = $stdout)
+      return unless @verbose || @simulate
+      stream.puts message.to_s
+    end
+  end
+end

data/lib/caligari/version.rb

@@ -0,0 +1,7 @@
+module Caligari
+  # Semantic version of Caligari.
+  VERSION = '0.1.0'.freeze
+
+  # Copyright notice for Caligari.
+  COPYRIGHT = "caligari #{VERSION} (c) 2016 Robin Owen".freeze
+end

data/lib/caligari/xdg.rb

@@ -0,0 +1,41 @@
+require 'pathname'
+
+module Caligari
+  # This module contains constants representing XDG configuration directories
+  # and files for Caligari as specified by the XDG Base Directory
+  # Specification.
+  #
+  # @see http://polr.me/zjp XDG Base Directory Specification
+  module XDG
+    # Collects configuration directories as defined by the XDG Base Directory
+    # Specification as `Pathname` instances.
+    #
+    # @api private
+    # @return [Array<Pathname>] the collected XDG configuration directories
+    def self.collect_xdg_config_dirs
+      dirs = ENV['XDG_CONFIG_DIRS']
+      if dirs
+        dirs.split(':').map! do |dir|
+          Pathname.new(dir).expand_path.freeze
+        end.freeze
+      else
+        [Pathname.new('/etc/xdg').freeze].freeze
+      end
+    end
+    private_class_method :collect_xdg_config_dirs
+
+    # The global XDG configuration directories as an array of `Pathname`
+    # instances.
+    CONFIG_DIRS = collect_xdg_config_dirs
+
+    # The user XDG configuration directory as a `Pathname` instance.
+    CONFIG_HOME =
+      Pathname.new(ENV['XDG_CONFIG_HOME'] || '~/.config').expand_path.freeze
+
+    # The existent XDG configuration files for Caligari as a `Pathname`
+    # instance.
+    CONFIG_FILES = (CONFIG_DIRS + [CONFIG_HOME]).map! do |dir|
+      (dir + 'caligari.yml').freeze
+    end.select! { |file| file.exist? }.freeze
+  end
+end

data/man/man1/caligari.1.md

@@ -0,0 +1,105 @@
+CALIGARI 1
+===============================================================================
+
+NAME
+-------------------------------------------------------------------------------
+
+caligari - symbolically link external configuration files
+
+SYNOPSIS
+-------------------------------------------------------------------------------
+
+`caligari` [*OPTION*]... [*PATH*]...
+
+DESCRIPTION
+-------------------------------------------------------------------------------
+
+`caligari` installs configuration files by symbolically linking all of the
+files from the given paths directly to the current user's home directory with
+the same relative file structure, creating any requisite directories as-needed.
+
+
+OPTIONS
+-------------------------------------------------------------------------------
+
+`-x`, `--exclude` *pattern* ...
+  Exclude the files and directories matching the given patterns. Patterns may
+  be supplied as *fnmatch* patterns. Note that exclusions are automatically
+  given the **FNM_DOTMATCH** and **FNM_PATHNAME** flags.
+
+`-f`, `--force`
+  Force installation over existing files.
+
+`-s`, `--simulate`
+  Simulate installation (implies `--verbose`). Any action which would normally
+  affect the file system is simply reported rather than acted upon.
+
+`-t`, `--traverse`
+  Traverse into the given directories while processing. This ensures that each
+  path given acts as its own relative "root" path during processing -- the
+  files in each path will be linked directly to the user's home directory
+  rather than being treated as children of the current working directory.
+
+`-V`, `--verbose`
+  Print verbose installation information while processing. Each item printed
+  by this flag is announced with an appropriate label for the action being
+  taken (or simulated): `ln:` for created symbolic links, `path:` for created
+  directory paths, `rm:` for unlinked files, and `err:` for any errors
+  encountered.
+
+CONFIGURATION
+-------------------------------------------------------------------------------
+
+`caligari` may be configured by editing the system-wide configuration file
+(defined by default as */etc/xdg/caligari.yml*) or the per-user configuration
+file (defined by default as *~/.config/caligari.yml*). These configuration
+files are simple YAML files which define the default exclusion patterns used
+by `caligari`.
+
+EXAMPLES
+-------------------------------------------------------------------------------
+
+Create symbolic links for all of the files in the current directory excluding
+the *.git* directory and all *README.md* files:
+
+```sh
+caligari -x '**/.git' '**/README.md'
+```
+
+Forcefully create symbolic links for all of the files in the directories
+*dotfiles* and *more-dotfiles*, traversing to each so the files are linked
+directly to the home directory:
+
+```sh
+caligari -tf dotfiles more-dotfiles
+```
+
+Print each file which was forcefully removed:
+
+```sh
+caligari -Vf | awk '/^rm:/ { print $2 }'
+```
+
+Example *~/.config/caligari.yml* to automatically exclude the *.git* directory
+and all *README.md* files:
+
+```yaml
+---
+:exclude:
+- "**/.git"
+- "**/README.md"
+```
+
+FILES
+-------------------------------------------------------------------------------
+
+*/etc/xdg/caligari.yml*
+  The system-wide configuration file.
+
+*~/.config/caligari.yml*
+  Per-user configuration file.
+
+AUTHOR
+-------------------------------------------------------------------------------
+
+Robin Owen <vthrenody@gmail.com>

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: caligari
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Robin Owen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-08-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: md2man
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: trollop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Caligari is designed to allow the quick and easy installation of configuration
+  files by symbolically linking files from external sources directly to the user's
+  home directory.
+email:
+- vthrenody@gmail.com
+executables:
+- caligari
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/caligari
+- caligari.gemspec
+- lib/caligari.rb
+- lib/caligari/application.rb
+- lib/caligari/version.rb
+- lib/caligari/xdg.rb
+- man/man1/caligari.1
+- man/man1/caligari.1.md
+homepage: https://github.com/vthrenody/caligari
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.6
+signing_key: 
+specification_version: 4
+summary: Caligari symbolically links configuration files.
+test_files: []