mdn_query 0.1.0

data/lib/mdn_query/entry.rb

@@ -0,0 +1,62 @@
+module MdnQuery
+  # An entry of the Mozilla Developer Network documentation.
+  class Entry
+    # @return [String]
+    attr_reader :title, :description, :url
+
+    # Creates a new entry.
+    #
+    # @param title [String] the title of the entry
+    # @param description [String] a small excerpt of the entry
+    # @param url [String] the URL to the entry on the web
+    # @return [MdnQuery::Entry]
+    def initialize(title, description, url)
+      @title = title
+      @description = description
+      @url = url
+    end
+
+    # Returns the string representation of the entry.
+    #
+    # @return [String]
+    def to_s
+      "#{title}\n#{description}\n#{url}"
+    end
+
+    # Opens the entry in the default web browser.
+    #
+    # @return [void]
+    def open
+      Launchy.open(@url)
+    end
+
+    # Returns the content of the entry.
+    #
+    # The content is fetched from the Mozilla Developer Network's documentation.
+    # The fetch occurs only once and subsequent calls return the previously
+    # fetched content.
+    #
+    # @raise [MdnQuery::HttpRequestFailed] if a HTTP request fails
+    # @return [MdnQuery::Document] the content of the entry
+    def content
+      return @content unless @content.nil?
+      @content = retrieve(url)
+    end
+
+    private
+
+    def retrieve(url)
+      begin
+        response = RestClient::Request.execute(method: :get, url: url,
+                                               headers: { accept: 'text/html' })
+      rescue RestClient::Exception, SocketError => e
+        raise MdnQuery::HttpRequestFailed.new(url, e),
+              'Could not retrieve entry'
+      end
+      dom = Nokogiri::HTML(response.body)
+      title = dom.css('h1').text
+      article = dom.css('article')
+      MdnQuery::TraverseDom.create_document(article, title, url)
+    end
+  end
+end

data/lib/mdn_query/errors.rb

@@ -0,0 +1,42 @@
+module MdnQuery
+  # The standard error.
+  class Error < StandardError; end
+
+  # The error when no entries were found.
+  class NoEntryFound < MdnQuery::Error
+    # @return [String] the query that was searched for
+    attr_reader :query
+
+    # @return [Hash] the options used for the search
+    attr_reader :options
+
+    # Creates a new NoEntryFound error.
+    #
+    # @param query [String] the query that was searched for
+    # @param options [Hash] the options used for the search
+    # @return [MdnQuery::NoEntryFound]
+    def initialize(query, options = {})
+      @query = query
+      @options = options
+    end
+  end
+
+  # The error for failed HTTP request of any kind.
+  class HttpRequestFailed < MdnQuery::Error
+    # @return [String] the URL of the request
+    attr_reader :url
+
+    # @return [SocketError, RestClient::Exception] the original error
+    attr_reader :http_error
+
+    # Creates a new HttpRequestFailed error.
+    #
+    # @param url [String] the URL of the request
+    # @param error [SocketError, RestClient::Exception] the original error
+    # @return [MdnQuery::HttpRequestFailed]
+    def initialize(url, error)
+      @url = url
+      @http_error = error
+    end
+  end
+end

data/lib/mdn_query/list.rb

@@ -0,0 +1,82 @@
+module MdnQuery
+  # A list from a search result.
+  class List
+    # @return [String] the query that was searched for
+    attr_reader :query
+
+    # @return [Array<MdnQuery::Entry>]
+    attr_reader :items
+
+    # Creates a new list of search results.
+    #
+    # @param query [String] the query that was searched for
+    # @param items [MdnQuery::Entry] the items in the list
+    # @return [MdnQuery::List]
+    def initialize(query, *items)
+      items = [] if items.nil?
+      @query = query
+      @items = items
+    end
+
+    # Returns the first item in the list.
+    #
+    # @return [MdnQuery::Entry] the first item
+    def first
+      items.first
+    end
+
+    # Retrieves the item at the given position.
+    #
+    # @param pos [Fixnum] the position of the item
+    # @return [MdnQuery::Entry] the item at position `pos`
+    def [](pos)
+      items[pos]
+    end
+
+    # Returns whether the list is empty.
+    #
+    # @return [Boolean] whether the list is empty
+    def empty?
+      items.empty?
+    end
+
+    # Returns the number of items in the list.
+    #
+    # @return [Fixnum] the number of items
+    def size
+      items.size
+    end
+
+    # Calls the given block for every item.
+    #
+    # @param block [Block] block to be executed for every item.
+    # @return [void]
+    def each(&block)
+      items.each(&block)
+    end
+
+    # Returns the string representation of the list.
+    #
+    # @return [String]
+    def to_s
+      return "No results for '#{query}'" if empty?
+      "Results for '#{query}':\n#{number_items(items).join("\n")}\n"
+    end
+
+    private
+
+    def number_items(items)
+      num_width = items.size / 10 + 1
+
+      items.map.with_index do |item, index|
+        entry = "#{(index + 1).to_s.rjust(num_width)}) "
+        entry << pad_left(item.to_s, num_width + 2)
+      end
+    end
+
+    def pad_left(str, num)
+      pad = ' ' * num
+      str.gsub("\n", "\n#{pad}")
+    end
+  end
+end

data/lib/mdn_query/search.rb

@@ -0,0 +1,111 @@
+module MdnQuery
+  # A search request to the Mozilla Developer Network documentation.
+  class Search
+    # @return [String] a search option (see {#initialize})
+    attr_accessor :css_classnames, :locale, :highlight, :html_attributes,
+                  :query, :result, :topics
+
+    # rubocop:disable Metrics/LineLength
+
+    # Creates a new search.
+    #
+    # The search request is not automatically executed (use {#execute}).
+    #
+    # @param query [String] the query to search for
+    # @param options [Hash] the search query options (more informations on
+    #   {https://developer.mozilla.org/en-US/docs/MDN/Contribute/Tools/Search#Search_query_format})
+    # @option options :css_classnames [String] the CSS classes to match
+    # @option options :highlight [Boolean] whether the query is highlighted
+    # @option options :html_attributes [String] the HTML attribute text to match
+    # @option options :locale [String] the locale to match against
+    # @option options :topics [Array<String>] the topics to search in
+    # @return [MdnQuery::Search]
+    def initialize(query, options = {})
+      @url = "#{MdnQuery::BASE_URL}.json"
+      @query = query
+      @css_classnames = options[:css_classnames]
+      @locale = options[:locale] || 'en-US'
+      @highlight = options[:highlight] || false
+      @html_attributes = options[:html_attributes]
+      @topics = options[:topics] || ['js']
+    end
+    # rubocop:enable Metrics/LineLength
+
+    # Creates the URL used for the request.
+    #
+    # @return [String] the full URL
+    def url
+      query_url = "#{@url}?q=#{@query}&locale=#{@locale}"
+      query_url << @topics.map { |t| "&topic=#{t}" }.join
+      unless @css_classnames.nil?
+        query_url << "&css_classnames=#{@css_classnames}"
+      end
+      unless @html_attributes.nil?
+        query_url << "&html_attributes=#{@html_attributes}"
+      end
+      query_url << "&highlight=#{@highlight}" unless @highlight.nil?
+      query_url
+    end
+
+    # Executes the search request.
+    #
+    # @return [MdnQuery::SearchResult] the search result
+    def execute
+      @result = retrieve(url, @query)
+    end
+
+    # Fetches the next page of the search result.
+    #
+    # If there is no search result yet, {#execute} will be called instead.
+    #
+    # @return [MdnQuery::SearchResult] if a new result has been acquired
+    # @return [nil] if there is no next page
+    def next_page
+      if @result.nil?
+        execute
+      elsif @result.next?
+        query_url = url
+        query_url << "&page=#{@result.current_page + 1}"
+        @result = retrieve(query_url, @query)
+      end
+    end
+
+    # Fetches the previous page of the search result.
+    #
+    # If there is no search result yet, {#execute} will be called instead.
+    #
+    # @return [MdnQuery::SearchResult] if a new result has been acquired
+    # @return [nil] if there is no previous page
+    def previous_page
+      if @result.nil?
+        execute
+      elsif @result.previous?
+        query_url = url
+        query_url << "&page=#{@result.current_page - 1}"
+        @result = retrieve(query_url, @query)
+      end
+    end
+
+    # Opens the search in the default web browser.
+    #
+    # @return [void]
+    def open
+      html_url = url.sub('.json?', '?')
+      Launchy.open(html_url)
+    end
+
+    private
+
+    def retrieve(url, query)
+      begin
+        response = RestClient::Request.execute(method: :get, url: url,
+                                               headers: { accept: 'json' })
+      rescue RestClient::Exception, SocketError => e
+        raise MdnQuery::HttpRequestFailed.new(url, e),
+              'Could not retrieve search result'
+      end
+      json = JSON.parse(response.body, symbolize_names: true)
+      MdnQuery::SearchResult.new(query, json)
+    end
+  end
+end

data/lib/mdn_query/search_result.rb

@@ -0,0 +1,69 @@
+module MdnQuery
+  # A result from a search query.
+  class SearchResult
+    # @return [Array<Hash>] the raw items of the search result
+    attr_reader :items
+
+    # @return [Hash] information about the pages
+    attr_reader :pages
+
+    # @return [String] the query that was searched for
+    attr_reader :query
+
+    # @return [Fixnum] the total number of entries
+    attr_reader :total
+
+    # Creates a new search result.
+    #
+    # @param query [String] the query that was searched for
+    # @param json [Hash] the hash version of the JSON response
+    # @return [MdnQuery::SearchResult]
+    def initialize(query, json)
+      @query = query
+      @pages = {
+        count: json[:pages] || 0,
+        current: json[:page]
+      }
+      @total = json[:count]
+      @items = json[:documents]
+    end
+
+    # Returns whether there are any entries.
+    #
+    # @return [Boolean]
+    def empty?
+      @pages[:count].zero?
+    end
+
+    # Returns whether there is a next page.
+    #
+    # @return [Boolean]
+    def next?
+      !empty? && @pages[:current] < @pages[:count]
+    end
+
+    # Returns whether there is a previous page.
+    #
+    # @return [Boolean]
+    def previous?
+      !empty? && @pages[:current] > 1
+    end
+
+    # Returns the number of the current page.
+    #
+    # @return [Fixnum]
+    def current_page
+      @pages[:current]
+    end
+
+    # Creates a list with the items.
+    #
+    # @return [MdnQuery::List]
+    def to_list
+      items = @items.map do |i|
+        MdnQuery::Entry.new(i[:title], i[:excerpt], i[:url])
+      end
+      MdnQuery::List.new(query, *items)
+    end
+  end
+end

data/lib/mdn_query/section.rb

@@ -0,0 +1,98 @@
+module MdnQuery
+  # A section of an entry of the Mozilla Developer Network documentation.
+  class Section
+    # @return [Array<MdnQuery::Section>] the list of child sections
+    attr_reader :children
+
+    # @return [String] the name and title of the section
+    attr_reader :name
+
+    # @return [Fixnum] the level of the section
+    attr_reader :level
+
+    # @return [MdnQuery::Section] the parent section
+    attr_reader :parent
+
+    # @return [Array<String>] the text segments of the section
+    attr_reader :text
+
+    # Creates a new section.
+    #
+    # @param name [String] the name and title of the section
+    # @param level [Fixnum] the level of the section
+    # @param parent [MdnQuery::Section] the parent section
+    # @return [MdnQuery::Section]
+    def initialize(name, level: 1, parent: nil)
+      @name = name
+      @level = level
+      @parent = parent
+      @text = []
+      @children = []
+    end
+
+    # Creates a new child section.
+    #
+    # @param name [String] the name and title of the child section
+    # @return [MdnQuery::Section] the new child section
+    def create_child(name)
+      child = MdnQuery::Section.new(name, parent: self, level: @level + 1)
+      @children << child
+      child
+    end
+
+    # Appends a text segment to the section.
+    #
+    # Spaces before and after newlines are removed. If the text segment is empty
+    # (i.e. consists of just whitespaces), it is not appended.
+    #
+    # @param text [String] the text segment to append
+    # @return [void]
+    def append_text(text)
+      trimmed_text = text.gsub(/\n[[:blank:]]+|[[:blank:]]+\n/, "\n")
+      @text << trimmed_text unless text_empty?(trimmed_text)
+    end
+
+    # Appends a code segment to the section.
+    #
+    # If the code segment is empty (i.e. consists of just whitespaces), it is
+    # not appended. The given snippet is embedded in a Markdown code block.
+    #
+    # @example Add a JavaScript snippet
+    #   append_code("const name = 'My Name';", language: 'javascript')
+    #   # adds the following text:
+    #   # ```javascript
+    #   # const name = 'My Name';
+    #   # ```
+    #
+    # @param snippet [String] the code segment to append
+    # @param language [String] the language of the code
+    # @return [void]
+    def append_code(snippet, language: '')
+      @text << "\n```#{language}\n#{snippet}\n```\n" unless text_empty?(snippet)
+    end
+
+    # Returns the string representation of the section.
+    #
+    # @return [String]
+    def to_s
+      str = "#{'#' * level} #{name}\n\n#{join_text}\n\n#{join_children}\n"
+      str.gsub!(/\n+[[:blank:]]+\n+|\n{3,}/, "\n\n")
+      str.strip!
+      str
+    end
+
+    private
+
+    def join_text
+      text.join("\n")
+    end
+
+    def join_children
+      children.map(&:to_s).join("\n\n")
+    end
+
+    def text_empty?(text)
+      !text.match(/\A\s*\z/).nil?
+    end
+  end
+end