how 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 48c8bf4b4a85f36d528ac753d12c49abb0757417
+  data.tar.gz: d6eab7ef8176e1656aa72ee98804afcde05f194a
+SHA512:
+  metadata.gz: 57db65eea8c56c6ae4ec4962500a1dfed07657abf34ff8293d19612f2f54c666d13cf388847d6e88486bba9d6b54244140b37ed2b2df3a6d766797562d286de7
+  data.tar.gz: 253e335a0d5336a8d29dba75ad26ff30e8bca00b504ff7113f434b06f18d5664a17e45e2b3c6fe4e3441a90b65e1dd1acc7489c12f18a8cff40078bb7d1acc90

data/.gitignore

@@ -0,0 +1,21 @@
+/*.gem
+/*.rbc
+/.bundle
+/.config
+/coverage
+/InstalledFiles
+/lib/bundler/man
+/pkg
+/rdoc
+/spec/reports
+/test/tmp
+/test/version_tmp
+/tmp
+
+# YARD artifacts
+/.yardoc
+/_yardoc
+/doc/
+
+
+/reference/javascript/node_modules

data/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2014, Nick Sinopoli <nsinopoli@gmail.com>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this
+  list of conditions and the following disclaimer in the documentation and/or
+  other materials provided with the distribution.
+
+* Neither the name of Nick Sinopoli nor the names of his
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Makefile

@@ -0,0 +1,14 @@
+all: style test
+
+install:
+	gem install rubocop
+
+style:
+	rubocop lib
+
+test:
+	ruby spec.rb
+
+.PHONY: test
+
+

data/README.md

@@ -0,0 +1,34 @@
+# how
+
+**how** is a reference manual for programmers.
+
+## Installation
+
+```bash
+gem install how
+```
+
+For syntax highlighting, be sure to install [Pygments](http://pygments.org/).
+
+## Usage
+
+```bash
+how [domain] [keywords]
+```
+
+**how** takes two arguments:
+
+1. `domain` is the domain to be searched. The following domains are currently supported:
+
+    + [js](reference/javascript/README.md) (JavaScript)
+
+1. `keywords` are the search terms. (All keywords are used to find a match. If your search yields no results, try using fewer keywords.)
+
+### Example
+
+```bash
+# How do I capitalize a string in JavaScript?
+how js capitalize string
+```
+
+The results will be paged in the program set in `$PAGER`. (If `$PAGER` isn't set, [less](http://www.greenwoodsoftware.com/less/) will be used.) Additionally, if [Pygments](http://pygments.org/) is installed, the syntax will be highlighted.

data/bin/how

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.dirname(File.realpath(__FILE__)) + '/../lib')
+
+require 'how'
+
+def run(argv)
+  args = { domain: argv.shift, keywords: argv }
+
+  domain_path = How::IO.get_domain_path args[:domain]
+  abort 'Invalid domain.' if !domain_path
+
+  matches = Dir.glob(domain_path).reduce([]) do |list, filename|
+    contents = File.read filename
+    blocks = How::Text.find_blocks contents, args[:keywords]
+    next list if blocks.empty?
+    list << blocks.map { |block| How::Text.drop_first_and_last_lines block }
+  end
+
+  abort 'No results found. Try changing your search terms.' if matches.empty?
+
+  results = matches.join "\n\n"
+
+  if RUBY_PLATFORM =~ /win32/ || !$stdout.tty?
+    return $stdout.puts results
+  end
+
+  if How::IO.which 'pygmentize'
+    lexer = How::SyntaxHighlighter.get_pygments_lexer args[:domain]
+    results = How::IO.pygmentize results, lexer
+  end
+
+  How::IO.page results
+end
+
+run ARGV

data/how.gemspec

@@ -0,0 +1,18 @@
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require 'how/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'how'
+  gem.version       = How::Version::VERSION
+  gem.summary       = 'A reference manual for programmers'
+  gem.description   = 'Eliminates the tedium of hunting for answers to common programming questions'
+  gem.license       = 'BSD (3-Clause)'
+  gem.authors       = ['Nick Sinopoli']
+  gem.email         = 'NSinopoli@gmail.com'
+  gem.homepage      = 'https://github.com/NSinopoli/how'
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(spec)/})
+  gem.require_paths = ['lib']
+end

data/lib/how.rb

@@ -0,0 +1,5 @@
+require 'how/version'
+
+require 'how/io'
+require 'how/syntax_highlighter'
+require 'how/text'

data/lib/how/io.rb

@@ -0,0 +1,65 @@
+module How
+  # This module contains methods to handle IO-related operations.
+  module IO
+    # Retrieves the filepath (relative to the root of this project) of the
+    # reference files for the supplied domain.
+    #
+    # @param [String] domain The domain
+    # @return [String, nil]
+    def self.get_domain_path(domain)
+      root = File.expand_path '../..', File.dirname(__FILE__)
+
+      case domain.downcase
+      when 'rb', 'ruby'
+        File.join root, 'reference', 'ruby', 'lib', '*.rb'
+      when 'js', 'javascript'
+        File.join root, 'reference', 'javascript', 'lib', '*.js'
+      end
+    end
+
+    # Runs the supplied text through the pager defined in $PAGER.
+    #
+    # @param [String] text The text
+    def self.page(text)
+      pager = ENV['PAGER'] || 'less'
+      ::IO.popen(pager, 'w') { |process| process.puts text }
+    end
+
+    # Pygmentizes the supplied text. A lexer will be inferred (based on
+    # syntax) if it is not supplied.
+    #
+    # @param [String] text The text to be pygmentized
+    # @param [String] lexer The lexer
+    # @return [String]
+    def self.pygmentize(text, lexer = nil)
+      if !lexer
+        command = 'pygmentize -g'
+      else
+        command = "pygmentize -l '#{lexer}'"
+      end
+
+      ::IO.popen(command, 'r+') do |process|
+        process.puts text
+        process.close_write
+        process.read
+      end
+    end
+
+    # Finds the supplied command (if it exists) within the $PATH.
+    #
+    # @param [String] command The command
+    # @return [String, nil]
+    def self.which(command)
+      extensions = ENV['PATHEXT'] ? ENV['PATHEXT'].split(';') : ['']
+
+      ENV['PATH'].split(File::PATH_SEPARATOR).each do |path|
+        extensions.each do |extension|
+          exe = File.join path, "#{command}#{extension}"
+          return exe if File.executable? exe
+        end
+      end
+
+      nil
+    end
+  end
+end

data/lib/how/syntax_highlighter.rb

@@ -0,0 +1,18 @@
+module How
+  # This module contains methods to handle syntax highlighting.
+  module SyntaxHighlighter
+    # Retrieves the Pygments lexer corresponding to the supplied syntax type.
+    #
+    # @see http://pygments.org/docs/lexers/
+    # @param [String] syntax The type of syntax
+    # @return [String, nil]
+    def self.get_pygments_lexer(syntax)
+      case syntax.downcase
+      when 'rb', 'ruby'
+        'rb'
+      when 'js', 'javascript'
+        'js'
+      end
+    end
+  end
+end

data/lib/how/text.rb

@@ -0,0 +1,32 @@
+module How
+  # This module contains methods to handle text manipulation.
+  module Text
+    # Drops the first and last lines of the supplied text.
+    #
+    # @param [String] text The text
+    # @return [String]
+    def self.drop_first_and_last_lines(text)
+      _, *body, _ = text.lines
+      body.join.chomp
+    end
+
+    # Finds the blocks identified by the supplied keywords within the
+    # supplied text.
+    #
+    # @param [String] text The text
+    # @param [Array] keywords The keywords
+    # @return [Array]
+    def self.find_blocks(text, keywords)
+      return [] if keywords.empty?
+
+      # If keywords is, for example, ['capitalize', 'string'], this will
+      # create a regex that looks like this:
+      # (?=Tags:.*\bcapitalize\b)(?=Tags:.*\bstring\b)[\S\s]*?!~!
+      block_regex = keywords.reduce('') do |result, keyword|
+        result + '(?=Tags:.*\b' + keyword.downcase + '\b)'
+      end + '[\S\s]*?!~!'
+
+      text.scan(/#{block_regex}/)
+    end
+  end
+end

data/lib/how/version.rb

@@ -0,0 +1,7 @@
+module How
+  # This module holds the How version information.
+  module Version
+    # The current version
+    VERSION = '0.0.1'
+  end
+end

data/reference/javascript/.jshintrc

@@ -0,0 +1,57 @@
+{
+  /*
+   * ENVIRONMENTS
+   * =================
+   */
+
+  // Define globals exposed by modern browsers.
+  "browser": true,
+
+  // Define globals exposed by jQuery.
+  "jquery": true,
+
+  // Define globals exposed by Node.js.
+  "node": true,
+
+  /*
+   * ENFORCING OPTIONS
+   * =================
+   */
+
+  // Force all variable names to use either camelCase style or UPPER_CASE
+  // with underscores.
+  "camelcase": true,
+
+  // Prohibit use of == and != in favor of === and !==.
+  "eqeqeq": true,
+
+  // Suppress warnings about == null comparisons.
+  "eqnull": true,
+
+  // Enforce tab width of 2 spaces.
+  "indent": 2,
+
+  // Prohibit use of a variable before it is defined.
+  "latedef": true,
+
+  // Require capitalized names for constructor functions.
+  "newcap": true,
+
+  // Enforce use of single quotation marks for strings.
+  "quotmark": "single",
+
+  // Prohibit trailing whitespace.
+  "trailing": true,
+
+  // Prohibit use of explicitly undeclared variables.
+  "undef": true,
+
+  // Warn when variables are defined but never used.
+  "unused": true,
+
+  // Enforce line length to 80 characters
+  "maxlen": 80,
+
+  // Enforce placing 'use strict' at the top function scope
+  "strict": true
+}

data/reference/javascript/Makefile

@@ -0,0 +1,12 @@
+all: jshint test
+
+install:
+	npm install mocha should jshint
+
+jshint:
+	./node_modules/.bin/jshint lib
+
+test:
+	./node_modules/.bin/mocha --reporter list
+
+.PHONY: test

data/reference/javascript/README.md

@@ -0,0 +1,14 @@
+## Style Guide
+
+All code conforms to the
+[Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript).
+
+jshint?
+
+## Documentation
+
+All code is documented using [jsdoc](http://usejsdoc.org/).
+
+## Testing
+
+mocha

data/reference/javascript/lib/string.js

@@ -0,0 +1,16 @@
+'use strict';
+
+// Tags: capitalize capital uppercase first letter string
+// Compatibility notes: TODO
+/**
+ * Capitalizes the first letter of the supplied string.
+ *
+ * @param {string} string The string
+ * @returns {string} The capitalized string
+ */
+function capitalize(string) {
+  return string.charAt(0).toUpperCase() + string.slice(1);
+}
+// !~!
+
+exports.capitalize = capitalize;

data/reference/javascript/test/string.js

@@ -0,0 +1,21 @@
+'use strict';
+
+var should = require('should'),
+    string = require('../lib/string.js');
+
+describe('capitalize', function() {
+
+  it('capitalizes the first letter of the supplied string', function() {
+    string.capitalize('hello world!').should.equal('Hello world!');
+    string.capitalize('Hello world!').should.equal('Hello world!');
+  });
+
+  it('leaves the other letters unchanged', function() {
+    string.capitalize('FOO').should.equal('FOO');
+    string.capitalize('bar BAR bar').should.equal('Bar BAR bar');
+  });
+
+  it('returns an empty string when supplied with an empty string', function() {
+    string.capitalize('').should.equal('');
+  });
+});

data/spec.rb

@@ -0,0 +1,3 @@
+Dir.glob('spec/**/*.rb').each do |file|
+  require_relative file.sub(/\.rb$/, '')
+end

data/spec/lib/io_spec.rb

@@ -0,0 +1,40 @@
+require 'minitest/autorun'
+require_relative '../../lib/how/io'
+
+describe How::IO do
+
+  describe '.get_domain_path' do
+
+    root = File.expand_path '../..', File.dirname(__FILE__)
+
+    describe 'when the domain can be identified' do
+      it 'returns the correct path' do
+        %w(rb ruby RB Ruby).each do |contents|
+          actual = How::IO.get_domain_path contents
+          expected = File.join root, 'reference', 'ruby', 'lib', '*.rb'
+          actual.must_equal expected
+        end
+
+        %w(js javascript JS JavaScript).each do |contents|
+          actual = How::IO.get_domain_path contents
+          expected = File.join root, 'reference', 'javascript', 'lib', '*.js'
+          actual.must_equal expected
+        end
+      end
+    end
+
+    describe 'when the domain cannot be identified' do
+      it 'returns nil' do
+        contents = 'doesnotexist'
+        actual = How::IO.get_domain_path contents
+        expected = nil
+        actual.must_equal expected
+
+        contents = ''
+        actual = How::IO.get_domain_path contents
+        expected = nil
+        actual.must_equal expected
+      end
+    end
+  end
+end

data/spec/lib/syntax_highlighter_spec.rb

@@ -0,0 +1,38 @@
+require 'minitest/autorun'
+require_relative '../../lib/how/syntax_highlighter'
+
+describe How::SyntaxHighlighter do
+
+  describe '.get_pygments_lexer' do
+    describe 'when the syntax can be identified' do
+      it 'returns the correct lexer' do
+        %w(rb ruby RB Ruby).each do |contents|
+          actual = How::SyntaxHighlighter.get_pygments_lexer contents
+          expected = 'rb'
+          actual.must_equal expected
+        end
+
+        %w(js javascript JS JavaScript).each do |contents|
+          actual = How::SyntaxHighlighter.get_pygments_lexer contents
+          expected = 'js'
+          actual.must_equal expected
+        end
+      end
+    end
+
+    describe 'when the syntax cannot be identified' do
+      it 'returns nil' do
+        contents = 'doesnotexist'
+        actual = How::SyntaxHighlighter.get_pygments_lexer contents
+        expected = nil
+        actual.must_equal expected
+
+        contents = ''
+        actual = How::SyntaxHighlighter.get_pygments_lexer contents
+        expected = nil
+        actual.must_equal expected
+      end
+    end
+  end
+
+end

data/spec/lib/text_spec.rb

@@ -0,0 +1,134 @@
+require 'minitest/autorun'
+require_relative '../../lib/how/text'
+
+describe How::Text do
+
+  describe '.drop_first_and_last_lines' do
+    describe 'when the supplied string contains at least three lines' do
+      it 'removes the first and last lines' do
+        contents = "first\nmiddle\nlast"
+        actual = How::Text.drop_first_and_last_lines contents
+        expected = 'middle'
+        actual.must_equal expected
+
+        contents = "first\nsecond\nthird\nfourth"
+        actual = How::Text.drop_first_and_last_lines contents
+        expected = "second\nthird"
+        actual.must_equal expected
+      end
+    end
+
+    describe 'when the supplied string contains less than three lines' do
+      it 'returns an empty string' do
+        contents = "first\nlast"
+        actual = How::Text.drop_first_and_last_lines contents
+        expected = ''
+        actual.must_equal expected
+
+        contents = 'first'
+        actual = How::Text.drop_first_and_last_lines contents
+        expected = ''
+        actual.must_equal expected
+
+        contents = ''
+        actual = How::Text.drop_first_and_last_lines contents
+        expected = ''
+        actual.must_equal expected
+      end
+    end
+  end
+
+  describe '.find_blocks' do
+    contents = []
+    contents << <<-BLOCK
+      // Tags: capitalize capital uppercase first letter string
+      /**
+      * Capitalizes the first letter of the supplied string.
+      *
+      * @param {string} string The string
+      * @returns {string} The capitalized string
+      */
+      function capitalize(string) {
+        return string.charAt(0).toUpperCase() + string.slice(1);
+      }
+      // !~!
+    BLOCK
+
+    contents << <<-BLOCK
+      # Tags: nothing
+      # Does nothing.
+      #
+      # @param [String] flavor The flavor of nothing
+      # @return [nil]
+      def nothing(flavor)
+        nil
+      end
+      # !~!
+    BLOCK
+
+    contents << <<-BLOCK
+      # Tags: reverse string
+      def reverse(string):
+          """Reverse a string.
+
+          :Parameters:
+            - `string`: The string to reverse
+          """
+          return string[::-1]
+      # !~!
+    BLOCK
+
+    describe 'when the supplied keyword matches multiple blocks' do
+      it 'finds all of the matching blocks' do
+        actual = How::Text.find_blocks contents.join, ['string']
+        expected = trim_blocks [contents[0], contents[2]]
+        actual.must_equal expected
+      end
+    end
+
+    describe 'when the supplied keyword matches only one block' do
+      it 'finds the one matching block' do
+        actual = How::Text.find_blocks contents.join, ['capitalize']
+        expected = trim_blocks [contents[0]]
+        actual.must_equal expected
+      end
+    end
+
+    describe 'when the keyword matches only one block' do
+      it 'finds the one matching block' do
+        actual = How::Text.find_blocks contents.join, ['capitalize']
+        expected = trim_blocks [contents[0]]
+        actual.must_equal expected
+      end
+    end
+
+    describe 'when the (case-insensitive) keyword matches a block' do
+      it 'finds the one matching block' do
+        actual = How::Text.find_blocks contents.join, ['NOTHING']
+        expected = trim_blocks [contents[1]]
+        actual.must_equal expected
+      end
+    end
+
+    describe 'when the keywords match no blocks' do
+      it 'returns an empty array' do
+        actual = How::Text.find_blocks contents.join, %w(nothing sorry)
+        expected = []
+        actual.must_equal expected
+
+        actual = How::Text.find_blocks contents.join, ['sorry']
+        expected = []
+        actual.must_equal expected
+      end
+
+    end
+  end
+
+end
+
+def trim_blocks(blocks)
+  blocks.map do |block|
+    first, *rest = block.lines
+    first.gsub(/^.*?T/, 'T') + rest.join.chomp
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: how
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Nick Sinopoli
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-01-30 00:00:00.000000000 Z
+dependencies: []
+description: Eliminates the tedium of hunting for answers to common programming questions
+email: NSinopoli@gmail.com
+executables:
+- how
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- LICENSE
+- Makefile
+- README.md
+- bin/how
+- how.gemspec
+- lib/how.rb
+- lib/how/io.rb
+- lib/how/syntax_highlighter.rb
+- lib/how/text.rb
+- lib/how/version.rb
+- reference/javascript/.jshintrc
+- reference/javascript/Makefile
+- reference/javascript/README.md
+- reference/javascript/lib/string.js
+- reference/javascript/test/string.js
+- spec.rb
+- spec/lib/io_spec.rb
+- spec/lib/syntax_highlighter_spec.rb
+- spec/lib/text_spec.rb
+homepage: https://github.com/NSinopoli/how
+licenses:
+- BSD (3-Clause)
+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.1.4
+signing_key: 
+specification_version: 4
+summary: A reference manual for programmers
+test_files:
+- spec/lib/io_spec.rb
+- spec/lib/syntax_highlighter_spec.rb
+- spec/lib/text_spec.rb