cheatr 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in cheatr.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Ernesto Garcia
+
+MIT License
+
+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,173 @@
+# cheatr
+
+Cheatr is a simple command line utility to access cheat sheets from an online
+repository.
+
+Generally speaking, cheatr is a tool that allows to host an online collection
+of cheat sheets, and lets users query and maintain this repository remotely via
+a command line client utility.
+
+### What is a cheat sheet?
+
+In the context of cheatr, a cheat sheet is a small document with quick tips and
+hints on a concrete and specific topic.  Typically it contains notes intended
+to aid one's memory, like listing common and useful shortcuts used on
+a program, quick and easy tips on how to use a library, or the command line
+options of a shell command, for instance.
+
+Cheatr however enforces very little on the contents of the cheat sheets in
+a repository.  The above specification is just a guideline on the intended use
+of this tool, but in practice you can use it to store and maintain any
+collection of text documents in it.
+
+Further down this document you'll find more information about the format of
+[cheat sheet contents](#cheat-sheet-contents).
+
+## Installation
+
+    $ gem install cheatr
+
+## Usage
+
+Cheatr retrieves cheat sheets from a remote server, so we need to tell
+cheatr where to look.
+
+    $ cheatr config server cheatr.gnapse.com
+
+This generates a configuration file in `~/.cheatr/config.yml`.  Now we can
+start querying the remote server for cheat sheets, or start creating new ones.
+
+    $ cheatr show "ruby*"  # Cheat sheets with names starting with 'ruby'
+    ruby.strings
+    ruby.blocks
+    rubygems
+
+    $ cheatr search ruby   # With this command you can ommit the wildcard
+    ruby.strings
+    ruby.blocks
+    rubygems
+
+    $ cheatr all           # Lists all cheat sheets available
+    ack
+    bash
+    cplusplus
+    ...
+    ruby
+    vim
+    zsh
+
+Tell cheatr to show a given cheat sheet.
+
+    $ cheatr show ruby.blocks
+    Ruby blocks are an awesome language feature!
+
+The contents of a cheat sheet are cached once it has been fetched.  You can
+force cheatr to fetch remote contents.
+
+    $ cheatr show ruby.blocks -r
+
+You can edit existing cheat sheets, or create new ones.
+
+    $ cheatr edit ruby.blocks
+
+This will launch you preferred `$EDITOR` with the current contents of the
+specified cheat sheet.  After you save the file and quit the editor, `cheatr`
+will update the cheat sheet contents.
+
+Cheatr commands provide help, so you can discover all its features and
+possibilities. Type `cheatr --help` or `cheatr <command> --help` for details.
+
+## Web server
+
+This gem includes the server side component as well, so anyone can host their
+own cheat sheets service.  This server offers the basic API-like calls to
+query, retrieve and modify cheat sheet contents.  You can start a cheatr
+server with the following command:
+
+    $ cheatr server /path/to/cheatr/repository
+
+The repository path refers to the location where the cheats repository can be
+found.  A cheatr repository is nothing more than a git repository holding the
+cheat sheets as files in it.  If omitted, the current working directory is
+assummed.
+
+A cheatr server is a [sinatra][] app, so it can also be started using [rack][].
+Every cheatr repository, when created, is initialized with a standard
+`config.ru` file.  So while placed in the repository's root folder, the server
+can be started with the following command:
+
+    $ rackup
+
+Also try `rackup --help` for more options.
+
+[sinatra]: http://www.sinatrarb.com
+[rack]: https://github.com/rack/rack
+
+### Web interface
+
+Additionally, cheatr servers can be accessed directly on a browser, where
+content is delivered as traditional hyperlinked web pages instead of mere plain
+text, with the possibility to search for cheat sheets, or [link between
+them](#cheat-sheet-hyperlinks), converting cheatr in a simple but powerful
+cheat sheets wiki.
+
+To try this, type the following command:
+
+    $ cheatr browse ruby.blocks
+
+It will open the contents of the specified cheat sheet in your preferred
+browser.  Or you can always type the URLs in your browser yourself, provided
+you know the cheatr server you want to access.
+
+## Cheat sheet contents
+
+Although cheatr does not enforce any format to the contents of cheat sheets,
+it assumes they consist of markdown text.  Thus is highly beneficial to adhere
+to this convention, and embrace it.
+
+### Cheat sheet hyperlinks
+
+In addition to standard markdown syntax, cheatr supports a minor custom
+extension, that becomes useful when browsing a cheatr server in a web
+browser.  This is related to linking in between cheat sheets, as hinted in the
+previous section.
+
+This is best shown with an example.
+
+```
+Dynamic languages, like {{ruby}} and {{python}}, are more versatile than
+{{c++|cplusplus}} in many situations.
+```
+
+Noticed the slices of text surrounded by doble braces?  These are cheatr
+hyperlinks.  When showing pages through the web interface in a browser, these
+will be converted to links to the appropriate cheat sheet.
+
+Note also the link to the `cplusplus` cheat sheet.  The text before the
+vertical bar will be used as the link text, whereas the text after it is the
+name of the cheat sheet to link to.
+
+In the command line, these "links" will be shown unmodified, still serving the
+purpose of discovery, because the user can identify these "links" and discover
+new related topics to continue "browsing" and learning.
+
+## Contributing
+
+Feel free to dive into the code to understand more about how cheatr works, or
+just for fun.  Please note that this is a very young project with very rough
+edges still.  Issues reports and pull requests are welcome!
+
+In case you decide to step in:
+
+1. Fork the repo (`git clone https://github.com/gnapse/cheatr.git`)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Thanks
+
+Thanks to [defunkt][] for [cheat][], which provided the idea for this project.
+
+[defunkt]: https://github.com/defunkt
+[cheat]: https://github.com/defunkt/cheat

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/cheatr

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+
+require "slop"
+require "cheatr"
+
+def check(condition, message)
+  unless condition
+    $stderr.puts message
+    exit
+  end
+end
+
+unless ARGV.first == 'config'
+  check Cheatr::Client.server, "Run 'cheatr config server <location>' to set the remote cheatr server."
+end
+
+Slop.parse help: true do
+
+  command :server do
+    banner 'Usage: cheatr server [options] [repository-path]'
+    on 'p', 'port=', 'The port where the server will listen to.'
+    run do |opts, args|
+      check args.length <= 1, opts
+      repository = args.first || Dir.pwd
+      Cheatr::Server.run(repository, opts)
+    end
+  end
+
+  command :show do
+    banner 'Usage: cheatr show [options] <sheet-name>'
+    on 'r', 'remote', 'Forces retrieving contents from remote, ignoring the cache, if any.'
+    run do |opts, args|
+      check args.length == 1, opts
+      name = args.first
+      if name.include?('*')
+        Cheatr::Client.search_sheets(name)
+      else
+        Cheatr::Client.display_sheet(name, ignore_cache: opts[:remote])
+      end
+    end
+  end
+
+  command :browse do
+    banner 'Usage: cheatr browse [query]'
+    run do |opts, args|
+      check args.length <= 1, opts
+      Cheatr::Client.browse(args.first)
+    end
+  end
+
+  command :search do
+    banner 'Usage: cheatr search <query>'
+    run do |opts, args|
+      check args.length == 1, opts
+      Cheatr::Client.search_sheets(args.first)
+    end
+  end
+
+  command :all do
+    banner 'Usage: cheatr all'
+    run do |opts, args|
+      check args.length == 0, opts
+      Cheatr::Client.search_sheets
+    end
+  end
+
+  command :edit do
+    banner 'Usage: cheatr edit [options] <sheet-name>'
+    on 'y', 'yes', 'Do not ask for confirmation after editing.'
+    run do |opts, args|
+      check args.length == 1, opts
+      Cheatr::Client.edit_sheet(args.first, skip_confirmation: opts[:yes])
+    end
+  end
+
+  command :fetch do
+    banner 'Usage: cheatr fetch [options] <sheet-name>+'
+    on 'q', 'quiet', 'Do not print anything to standard output. Overrides --errors.'
+    on 'e', 'errors', 'Print error messages only.'
+    run do |opts, args|
+      Cheatr::Client.fetch_sheets(args, opts)
+    end
+  end
+
+  command :clear do
+    banner 'Usage: cheatr clear [options] [sheet-name]'
+    on 'a', 'all', 'Clear all cached cheat sheets. Requires confirmation by default.'
+    on 'y', 'yes', 'Do not ask for confirmation for clearing the cache completely.'
+    on 'q', 'quiet', 'Do not print anything to standard output. Implies --yes, skipping confirmation.'
+    run do |opts, args|
+      if opts[:all]
+        Cheatr::Client.clear_cache(:all, skip_confirmation: opts[:yes], quiet: opts[:quiet])
+      else
+        check(args.length == 1, opts)
+        Cheatr::Client.clear_cache(args.first, quiet: opts[:quiet])
+      end
+    end
+  end
+
+  command :config do
+    banner 'Usage: cheatr config <param> <value>'
+    run do |opts, args|
+      check args.length == 2, opts
+      Cheatr::Client.set_config(args.first => args.last)
+    end
+  end
+
+end

data/cheatr.gemspec

@@ -0,0 +1,37 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cheatr/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "cheatr"
+  spec.version       = Cheatr::VERSION
+  spec.authors       = ["Ernesto García"]
+  spec.email         = ["gnapse@gmail.com"]
+  spec.description   = %q{Display cheat sheets for a variety of programs, tools and libraries, right on the command line.}
+  spec.summary       = %q{Display cheat sheets right on the command line.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "slop"
+
+  # server dependencies
+  spec.add_dependency "git"
+  spec.add_dependency "sinatra"
+  spec.add_dependency "activemodel"
+  spec.add_dependency "redcarpet"
+
+  # client dependencies
+  spec.add_dependency "rest-client"
+  spec.add_dependency "pager"
+
+  # test dependencies
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

data/lib/cheatr.rb

@@ -0,0 +1,6 @@
+module Cheatr
+  autoload :Client, 'cheatr/client'
+  autoload :Server, 'cheatr/server'
+
+  SHEET_NAME_REGEXP = /\A[a-z]+([\.\-\_][a-z]+)*\z/
+end

data/lib/cheatr/client.rb

@@ -0,0 +1,133 @@
+require "yaml"
+require "pager"
+require "cheatr/client/sheet"
+
+module Cheatr
+  module Client
+    extend Pager
+
+    # Actions
+
+    def self.search_sheets(query = nil)
+      query += '*' unless query.nil? || query.include?('*')
+      page
+      puts Sheet.all(query)
+    end
+
+    def self.display_sheet(name, opts = {})
+      sheet = Sheet.new(name, opts)
+      if sheet.contents
+        page
+        puts "(cached version)" unless sheet.remote?
+        puts sheet.contents
+      else
+        puts sheet.errors.first
+      end
+    end
+
+    def self.edit_sheet(name, opts = {})
+      sheet = Sheet.new(name, ignore_cache: true)
+
+      file = Tempfile.new([name, '.md'])
+      file.write(sheet.contents) if sheet.contents
+      file.close
+      system "#{editor} #{file.path}"
+      file.open
+      contents = file.read
+      file.close
+
+      if contents.strip.empty?
+        puts "Edited sheet contents were empty so nothing was saved."
+        return
+      end
+
+      if opts[:skip_confirmation] || confirm("Do you want to update the '#{name}' cheat sheet?")
+        sheet.contents = contents
+        if sheet.save
+          puts "Sheet '#{name}' was updated successfully."
+        else
+          puts "Sheet '#{name}' could not be updated."
+          $stderr.puts "Error: #{sheet.errors.first}" if sheet.errors
+        end
+      else
+        puts "Sheet '#{name}' was left unchanged."
+      end
+    end
+
+    def self.browse(query = nil)
+      open_cmd = `uname` =~ /Darwin/ ? 'open' : 'xdg-open'
+      uri = "http://#{server}/#{query}"
+      exec "#{open_cmd} #{uri}"
+    end
+
+    def self.fetch_sheets(arr, opts = {})
+      arr.each do |name|
+        sheet = Sheet.new(name, ignore_cache: true)
+        if sheet.contents
+          puts "Sheet '#{name}' fetched successfully." unless opts[:quiet] || opts[:errors]
+        else
+          message = sheet.errors.first || "Sheet '#{name}' could not be fetched."
+          puts message unless opts[:quiet]
+        end
+      end
+    end
+
+    def self.clear_cache(name = :all, opts = {})
+      if name == :all
+        if opts[:quiet] || opts[:skip_confirmation] || confirm("Are you sure you want clear all cheat sheets cache?")
+          FileUtils.rm Dir.glob("#{cache_dir}/*.md")
+          puts "All cached cheat sheets have been removed." unless opts[:quiet]
+        else
+          puts "Cached cheat sheets were not removed." unless opts[:quiet]
+        end
+      else
+        FileUtils.rm "#{cache_dir}/#{name}.md", force: true
+        puts "Removed cached version of '#{name}'." unless opts[:quiet]
+      end
+    end
+
+    # Configuration settings
+
+    def self.mkdir(dir)
+      FileUtils.mkdir_p dir
+      dir
+    end
+
+    def self.cheatr_dir
+      @@cheatr_dir ||= mkdir File.join(File.expand_path("~"), ".cheatr")
+    end
+
+    def self.cache_dir
+      @@cache_dir ||= mkdir File.join(cheatr_dir, 'cache', server.gsub(/:\d+\z/, ''))
+    end
+
+    def self.server
+      @@sever ||= config['server']
+    end
+
+    def self.editor
+      @@editor ||= ENV['EDITOR']
+    end
+
+    def self.config_file
+      @@config_file ||= File.join(cheatr_dir, 'config.yml')
+    end
+
+    def self.config
+      @@config ||= YAML.load_file(config_file) || {} rescue {}
+    end
+
+    def self.set_config(options)
+      config.merge!(options)
+      File.open(config_file, 'w') { |f| f.write config.to_yaml }
+    end
+
+    private
+
+    def self.confirm(message)
+      print "#{message} (yes/no) "
+      answer = $stdin.gets.chomp
+      %w(yes Yes YES y Y).include? answer
+    end
+  end
+end