mdn_query 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 80ea4f6f65d473f50f9f4c14a06137c4c8a33231
+  data.tar.gz: 893ee7f7c9439f46f84e27de7c44f2958b276f3b
+SHA512:
+  metadata.gz: 156b7420731927a3c003014c4fdba0628cb24ffcdb5660ae6f1bab2844b2f3228b4aa40dcd5066fdfa3c7885a92d720961c69b7db989ea0508232ad6d9d56e2d
+  data.tar.gz: 487e05bf5a4968c63f512ec86393f8b4a8b43069d0a87f8bef4dfca6fab986cc01f0a111717044d06d57fd962ee20f43d360660ebc0442c33bad6e93e4322c45

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rubocop.yml

@@ -0,0 +1,34 @@
+Metrics/BlockLength:
+  CountComments: false
+  Max: 25
+  Exclude:
+    - mdn_query.gemspec
+    - lib/mdn_query/traverse_dom.rb
+Metrics/ClassLength:
+  CountComments: false
+  Max: 100
+  Exclude:
+    - test/**/*.rb
+    - lib/mdn_query/traverse_dom.rb
+Metrics/ModuleLength:
+  CountComments: false
+  Max: 100
+  Exclude:
+    - test/**/*.rb
+Metrics/AbcSize:
+  Max: 20
+  Exclude:
+    - lib/mdn_query/traverse_dom.rb
+Metrics/CyclomaticComplexity:
+  Max: 10
+  Exclude:
+    - lib/mdn_query/traverse_dom.rb
+Metrics/MethodLength:
+  CountComments: false
+  Max: 25
+  Exclude:
+    - lib/mdn_query/traverse_dom.rb
+Metrics/PerceivedComplexity:
+  Max: 10
+  Exclude:
+    - lib/mdn_query/traverse_dom.rb

data/.travis.yml

@@ -0,0 +1,16 @@
+sudo: false
+language: ruby
+os:
+  - linux
+  - osx
+cache:
+  bundler: true
+rvm:
+  - 2.3.1
+  - ruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+  fast_finish: true
+notifications:
+  email: false

data/Gemfile

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

data/LICENSE.md

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+=====================
+
+Copyright © 2016 Michael Jungo
+
+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,150 @@
+# MdnQuery
+
+[![Build Status][travis-img]][travis]
+
+Query the [Mozilla Developer Network][mdn] documentation. Unfortunately they do
+not provide an API to fetch the documentation entries, which means that all
+informations are extracted from the HTML pages to create a Markdown-like
+representation. Another drawback is that it requires two network requests to
+retrieve a single entry based on a search term, which is frequently desired as
+a precise search term almost always yields the concrete entry as the first
+result.
+
+## CLI
+
+The binary `mdn-query` provides an interactive command line interface to easily
+search a query. By default it only searches for results in the JavaScript topic.
+
+```
+Usage: mdn-query [options] <search-term>
+
+Options:
+    -v, --version               Shows the program's version
+    -h, --help                  Shows this help message
+    -f, --first, --first-match  Returns the first match instead of a list
+    -o, --open, --open-browser  Opens the appropriate page in the default web browser
+    -t, --topics                The topics to search in, delimited by commas
+```
+
+### Examples
+
+```sh
+mdn-query bind                  # Searches for 'bind'
+mdn-query bind --first          # Retrieves first match of the search result
+mdn-query bind --open           # Opens the search results in the default browser
+mdn-query bind --first --open   # Opens the first match in the default browser
+mdn-query bind --topics js,css  # Searches in the topics 'js' and 'css'
+```
+
+### Demo
+
+![Demo][demo]
+
+## Library
+
+### Top level methods
+
+The following methods, that each take the search query and optional search
+options as parameters, cover the most common use cases:
+
+#### MdnQuery.list(query, options)
+
+Creates a list with the search results. The entries in the list do not yet
+contain the content of the corresponding documentation entries. They need to be
+fetched individually.
+
+```ruby
+list = MdnQuery.list('bind')
+# Searches in the topics 'js' and 'css'
+list = MdnQuery.list('bind', topics: ['js', 'css'])
+# Prints a numbered list of the search result with a small description
+puts list
+# Finds all items that include 'Object' in their title
+object_entries = list.items.select { |e| e.title =~ /Object/ }
+```
+
+#### MdnQuery.first_match(query, options)
+
+Retrieves the content of the first entry of the search results. This requires
+two network requests, because it is required to first search the Mozilla
+Developer Network and then fetch the page of the respective entry.
+
+```ruby
+content = MdnQuery.first_match('bind')
+# Prints a Markdown-like representation of the entry
+puts content
+```
+
+#### MdnQuery.open_list(query, options)
+
+Opens the search query in the default web browser instead of retrieving the
+results, therefore there is no network request made.
+
+```ruby
+MdnQuery.open_list('bind')
+```
+
+#### MdnQuery.open_first_match(query, options)
+
+Opens the first entry in the default web browser instead of fetching the
+corresponding page. This means there is only one network request to retrieve the
+list of search results.
+
+```ruby
+MdnQuery.open_first_match('bind')
+```
+
+### Search
+
+```ruby
+# Creates a new search that is not executed yet
+search = MdnQuery::Search.new('bind', topics: ['js', 'css'])
+# Opens the search results in the default web browser
+search.open
+# Executes the search request
+search.execute
+# Creates a list of the search results
+list = search.result.to_list
+```
+
+A search result can contain multiple pages. To easily navigate through the
+pages, the methods `next_page` and `previous_page` are available, that retrieve
+the next and previous page respectively, if it exists.
+
+```ruby
+# Retrieves the next page of the search results
+search.next_page
+# Retrieves the previous page of the search results
+search.previous_page
+```
+
+### Entry
+
+The content of an entry can be retrieved with the method `content`, which
+fetches the documentation entry once, and simply returns it on further calls.
+
+```ruby
+list = MdnQuery.list('bind', topics: ['js', 'css'])
+entry = list.first
+# Opens the entry in the default web browser
+entry.open
+# Prints the entry's content, performing a network request
+puts entry.content
+# Prints the content again without another network request
+puts entry.content
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub][github-repo].
+
+## License
+
+The gem is available as open source under the terms of the [MIT License][mit].
+
+[demo]: screenshots/demo.gif
+[github-repo]: https://github.com/jungomi/mdn-query
+[mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript
+[mit]: http://opensource.org/licenses/MIT
+[travis]:  https://travis-ci.org/jungomi/mdn_query
+[travis-img]: https://travis-ci.org/jungomi/mdn_query.svg?branch=master

data/Rakefile

@@ -0,0 +1,18 @@
+require 'bundler/gem_tasks'
+require 'mdn_query'
+require 'rake/testtask'
+require 'rubocop/rake_task'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = if ARGV.size > 1
+                   FileList[*ARGV[1..-1]]
+                 else
+                   FileList['test/**/*_test.rb']
+                 end
+end
+
+RuboCop::RakeTask.new(:lint)
+
+task default: [:lint, :test]

data/bin/mdn-query

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+
+lib = File.expand_path('../../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'mdn_query'
+require 'launchy'
+require 'slop'
+require 'tty-pager'
+require 'tty-prompt'
+
+prompt = TTY::Prompt.new
+pager = TTY::Pager.new
+
+opts = Slop.parse do |o|
+  o.banner = 'Usage: mdn-query [options] <search-term>'
+  o.separator ''
+  o.separator 'Options:'
+  o.on '-v', '--version', "Shows the program's version" do
+    puts MdnQuery::VERSION
+  end
+  o.on '-h', '--help', 'Shows this help message' do
+    prompt.say o
+    exit
+  end
+  o.bool '-f', '--first', '--first-match',
+         'Returns the first match instead of a list'
+  o.bool '-o', '--open', '--open-browser',
+         'Opens the appropriate page in the default web browser'
+  o.array '-t', '--topics',
+          'The topics to search in, delimited by commas'
+end
+
+if opts.arguments.empty?
+  prompt.say opts
+  exit
+end
+
+search_term = opts.arguments.join(' ')
+topics = opts[:topics]
+topics = ['js'] if topics.empty?
+
+case [opts.first?, opts.open?]
+when [true, true]
+  begin
+    MdnQuery.open_first_match(search_term, topics: topics)
+  rescue MdnQuery::NoEntryFound => e
+    prompt.say e.message
+    exit
+  end
+when [true, false]
+  begin
+    pager.page MdnQuery.first_match(search_term, topics: topics)
+  rescue MdnQuery::NoEntryFound => e
+    prompt.say e.message
+    exit
+  end
+when [false, true]
+  MdnQuery.open_list(search_term, topics: topics)
+when [false, false]
+  begin
+    list = MdnQuery.list(search_term, topics: topics)
+  rescue MdnQuery::NoEntryFound
+    prompt.say "No results for '#{search_term}'"
+    exit
+  end
+  begin
+    selected_entry = prompt.select("Results for '#{search_term}'") do |menu|
+      menu.enum ')'
+      list.each do |entry|
+        menu.choice entry.title, entry
+      end
+    end
+    pager.page selected_entry.content
+  rescue TTY::Prompt::Reader::InputInterrupt
+    puts
+    exit
+  end
+end

data/lib/mdn_query.rb

@@ -0,0 +1,77 @@
+require 'English'
+require 'nokogiri'
+require 'launchy'
+require 'rest-client'
+
+require 'mdn_query/document'
+require 'mdn_query/entry'
+require 'mdn_query/errors'
+require 'mdn_query/list'
+require 'mdn_query/search_result'
+require 'mdn_query/search'
+require 'mdn_query/section'
+require 'mdn_query/table'
+require 'mdn_query/traverse_dom'
+require 'mdn_query/version'
+
+# Query the Mozilla Developer Network documentation.
+module MdnQuery
+  # The base url for the search queries.
+  BASE_URL = 'https://developer.mozilla.org/search'.freeze
+
+  # Searches the given query and creates a list with the results.
+  #
+  # @param query [String] the query to search for
+  # @param options [Hash] additional query options (see
+  #   {MdnQuery::Search#initialize})
+  # @raise [MdnQuery::HttpRequestFailed] if a HTTP request fails
+  # @raise [MdnQuery::NoEntryFound] if no entry was found
+  # @return [MdnQuery::List] the list of results
+  def self.list(query, options = {})
+    search = MdnQuery::Search.new(query, options)
+    list = search.execute.to_list
+    if list.empty?
+      raise MdnQuery::NoEntryFound.new(query, options), 'No entry found'
+    end
+    list
+  end
+
+  # Searches the given query and returns the first fetched entry in the list.
+  #
+  # @param query [String] the query to search for
+  # @param options [Hash] additional query options (see
+  #   {MdnQuery::Search#initialize})
+  # @raise [MdnQuery::HttpRequestFailed] if a HTTP request fails
+  # @raise [MdnQuery::NoEntryFound] if no entry was found
+  # @return [MdnQuery::Document] the document of entry
+  def self.first_match(query, options = {})
+    entry = list(query, options).first
+    entry.content
+  end
+
+  # Searches the given query and opens the result in the default browser.
+  #
+  # @param query [String] the query to search for
+  # @param options [Hash] additional query options (see
+  #   {MdnQuery::Search#initialize})
+  # @raise [MdnQuery::HttpRequestFailed] if a HTTP request fails
+  # @raise [MdnQuery::NoEntryFound] if no entry was found
+  # @return [void]
+  def self.open_list(query, options = {})
+    search = MdnQuery::Search.new(query, options)
+    search.open
+  end
+
+  # Searches the given query and opens the first entry in the default browser.
+  #
+  # @param query [String] the query to search for
+  # @param options [Hash] additional query options (see
+  #   {MdnQuery::Search#initialize})
+  # @raise [MdnQuery::HttpRequestFailed] if a HTTP request fails
+  # @raise [MdnQuery::NoEntryFound] if no entry was found
+  # @return [void]
+  def self.open_first_match(query, options = {})
+    entry = list(query, options).first
+    entry.open
+  end
+end

data/lib/mdn_query/document.rb

@@ -0,0 +1,36 @@
+module MdnQuery
+  # A document of an entry of the Mozilla Developer Network documentation.
+  class Document
+    # @return [String]
+    attr_reader :title, :url
+
+    # @return [MdnQuery::Section] the top level section
+    attr_reader :section
+
+    # Creates a new document with an initial top level section.
+    #
+    # @param title [String] the titel of the top level section
+    # @param url [String] the URL to the document on the web
+    # @return [MdnQuery::Document]
+    def initialize(title, url = nil)
+      @title = title
+      @url = url
+      @section = MdnQuery::Section.new(title)
+    end
+
+    # Opens the document in the default web browser if a URL has been specified.
+    #
+    # @return [void]
+    def open
+      Launchy.open(@url) unless @url.nil?
+    end
+
+    # Returns the string representation of the document.
+    #
+    # @return [String]
+    def to_s
+      @section.to_s
+    end
+    alias to_md to_s
+  end
+end