kat 0.1.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1666db6fd7cf5f49236cfea2499c32073800ccc0
-  data.tar.gz: a6c24a63dcc968c552804ed7a22005defd63e86b
+  metadata.gz: 6431728ef307439d3dff0b3f60e3619c0ae4d37c
+  data.tar.gz: 914cef06e731347f85c4c8ba9c5363711d134e4a
 SHA512:
-  metadata.gz: 249bcc1134cd966ebaa3ace2ebb91d4cbc538366205588f764562cff82f270878b63a37b01c7596e431f0076a3b20585d84bdc32008eebf634b2dd43a2dea246
-  data.tar.gz: 3acb8c04eb256cb39ed597743d9ebe9f38dc1db756e2d2c79184b308094276e7908ff32d496a3fd971c2621854631e987781af110c1acc89a35183eeb13cec04
+  metadata.gz: d64ef6998d9d27411680c8aa08e42d6cf5d15dbe33a82122a9ede9ba04c75841e24a93b98c126207beadd3713e4d7102c67ccbd5fdd0411b716011050ed33030
+  data.tar.gz: 7ec114ce7cf00ca98b9d94345c8cc1b6dbaf3aaf812334146fe58ae7e84f224cb92ec677c3e948d4593939e17d4058d3c4c11b967a75317fac8baa133668aa56

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.0.0

data/Gemfile

@@ -2,3 +2,7 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in kat.gemspec
 gemspec
+
+group :test do
+  gem 'rake'
+end

data/LICENSE

@@ -1,20 +1,20 @@
-The MIT License (MIT)
-
-Copyright (c) 2013 Fission Xuiptz
-
-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.
+The MIT License (MIT)
+
+Copyright (c) 2013 Fission Xuiptz
+
+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/Rakefile

@@ -1 +1,9 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+task :default => :test
+
+Rake::TestTask.new do |t|
+  t.libs.push 'lib'
+  t.test_files = FileList['test/*_test.rb']
+end

data/lib/kat.rb

@@ -1,60 +1,109 @@
-# TODO: Implement field sort and sort order
-#       Lookup advanced search for language and platform values
-#       Comments
-#       Tests
+# TODO: Lookup advanced search for language and platform values
 
 require 'nokogiri'
 require 'open-uri'
 
 class Kat
   KAT_URL = 'http://kickass.to'
-  SEARCH_URL = "#{KAT_URL}/usearch/"
+  EMPTY_URL = "new"
+  SEARCH_URL = "usearch"
   ADVANCED_URL = "#{KAT_URL}/torrents/search/advanced/"
 
   STRING_FIELDS = [ :category, :seeds, :user, :age, :files, :imdb, :season, :episode ]
+
+  # The names of these fields are transposed for ease of use
   SELECT_FIELDS = [ { :name => :language, :id => :lang_id }, { :name => :platform, :id => :platform_id } ]
+
+  # If these are set to anything but nil or false, they're turned on in the query
   SWITCH_FIELDS = [ :safe, :verified ]
 
-  attr_reader :results, :pages, :error
+  SORT_FIELDS   = %w(size files_count time_add seeders leechers)
+
+  # The number of pages of results
+  attr_reader :pages
+
+  # Any error in searching is stored here
+  attr_reader :error
 
+  #
+  # Create a new +Kat+ object to search Kickass Torrents.
+  #
+  # The search term can be nil, a string/symbol, or an array of strings/symbols.
+  #
+  # Valid options are in STRING_FIELDS, SELECT_FIELDS or SWITCH_FIELDS
+  #
   def initialize search_term = nil, opts = {}
     @search_term = []
     @options = opts.is_a?(Hash) ? opts : {}
     self.query = search_term.is_a?(Array) ? search_term.dup : search_term
   end
 
+  #
+  # Use Kat.search(search_term) to do a quick search
+  #
   def self.search search_term
     self.new(search_term).search
   end
 
+  #
+  # Generate a query string from the stored options, supplying an optional page number
+  #
   def query page = 0
-    @query.join(' ').gsub(/[^a-z0-9: _-]/i, '') + (page > 0 ? "/#{page + 1}" : '') + (@query.empty? ? '' : '/')
+    q = [ SEARCH_URL, @query.join(' ').gsub(/[^a-z0-9: _-]/i, '') ]
+    q = [ EMPTY_URL ] if q[1].empty?
+    q << page + 1 if page > 0
+    q << if SORT_FIELDS.include? @options[:sort].to_s
+      "?field=#{options[:sort].to_s}&sorder=#{options[:asc] ? 'asc' : 'desc'}"
+    else
+      ''    # ensure a trailing slash after the search terms or page number
+    end
+    q.join '/'
   end
 
+  #
+  # Change the search term for the query, triggering a rebuild of the query string
+  # and clearing past results.
+  #
+  # Raises ArgumentError if search_term is not a String, Symbol or Array
+  #
   def query= search_term
     @search_term = case search_term
-      when nil    then []
-      when String then [ search_term ]
-      when Array  then search_term.flatten.select {|el| el.is_a? String }
-      else raise ArgumentError, "search_term must be a String or Array object. #{search_term.inspect} given."
+      when nil then []
+      when String, Symbol then [ search_term ]
+      when Array then search_term.flatten.select {|el| [ String, Symbol ].include? el.class }
+      else raise ArgumentError, "search_term must be a String, Symbol or Array. #{search_term.inspect} given."
     end
     build_query
   end
 
+  #
+  # Get a copy of the search options hash
+  #
   def options
     @options.dup
   end
 
+  #
+  # Change search options with a hash, triggering a rebuild of the query string and
+  # clearing past results.
+  #
+  # Raises ArgumentError if opts is not a Hash
+  #
   def options= opts
-    raise ArgumentError, "opts must be a Hash object. #{opts.inspect} given." unless opts.is_a? Hash
+    raise ArgumentError, "opts must be a Hash. #{opts.inspect} given." unless opts.is_a? Hash
     @options.merge! opts
     build_query
   end
 
+  #
+  # Perform the search, supplying an optional page number to search on. Returns
+  # a result set limited to the 25 results Kickass Torrents returns itself. Will
+  # cache results for subsequent calls of search with the same query string.
+  #
   def search page = 0
-    unless query.empty? or @results[page] or (@pages > 0 and page >= @pages)
+    unless query.empty? or @results[page] or (@pages > -1 and page >= @pages)
       begin
-        doc = Nokogiri::HTML(open("#{SEARCH_URL}#{URI::encode(query page)}"))
+        doc = Nokogiri::HTML(open("#{KAT_URL}/#{URI::encode(query page)}"))
         @results[page] = doc.css('td.torrentnameCell').map do |node|
           { :title    => node.css('a.normalgrey').text,
             :magnet   => node.css('a.imagnet').first.attributes['href'].value,
@@ -65,30 +114,55 @@ class Kat
             :seeds    => (node = node.next_element).text.to_i,
             :leeches  => (node = node.next_element).text.to_i }
         end
-        @pages = doc.css('div.pages > a').last.text.to_i if @pages == 0
-        @pages = 1 if @pages == 0
+
+        # If we haven't previously performed a search with this query string, get the
+        # number of pages from the pagination bar at the bottom of the results page.
+        @pages = doc.css('div.pages > a').last.text.to_i if @pages < 0
+
+        # If there was no pagination bar and the previous statement didn't trigger
+        # a NoMethodError, there are results but only 1 page worth.
+        @pages = 1 if @pages <= 0
+      rescue NoMethodError
+        # The results page had no pagination bar, but did return some results.
+        @pages = 1
       rescue => e
-        if e.name == :text
-          @pages = 1
-        else
-          @error = { :error => e, :query => query(page) }
-        end
+        # No result throws a 404 error.
+        @pages = 0 if e.class == OpenURI::HTTPError and e.message['404 Not Found']
+        @error = { :error => e, :query => query(page) }
       end
     end
 
-    @results[page]
+    results[page]
+  end
+
+  #
+  # Get a copy of the results
+  #
+  def results
+    @results.dup
   end
 
+  #
+  # If the method_sym or its plural is a field name in the results list, this will tell us
+  # if we can fetch the list of values. It'll only happen after a successful search.
+  #
   def respond_to? method_sym, include_private = false
-    return true if not @results.empty? and (@results.last.first[method_sym] or @results.last.first[method_sym.to_s.chop.to_sym])
+    if not (@results.empty? or @results.last.empty?) and
+           (@results.last.first[method_sym] or @results.last.first[method_sym.to_s.chop.to_sym])
+      return true
+    end
     super
   end
 
 private
 
+  #
+  # Clear out the query and rebuild it from the various stored options. Also clears out the
+  # results set and sets pages back to -1
+  #
   def build_query
     @query = @search_term.dup
-    @pages = 0
+    @pages = -1
     @results = []
 
     @query << "\"#{@options[:exact]}\"" if @options[:exact]
@@ -100,13 +174,18 @@ private
     SWITCH_FIELDS.each {|f| @query << "#{f}:1" if @options[f] }
   end
 
+  #
+  # If method_sym or its plural form is a field name in the results list, fetch the list of values.
+  # Can only happen after a successful search.
+  #
   def method_missing method_sym, *arguments, &block
+    # Don't need no fancy schmancy pluralizing method. Just try chopping off the 's'.
     m = method_sym.to_s.chop.to_sym
-    if not @results.empty? and (@results.last.first[method_sym] or @results.last.first[m])
-      @results.compact.map {|rs| rs.map {|r| r[method_sym] || r[m] } }.flatten
-    else
-      super
+    if not (@results.empty? or @results.last.empty?) and
+           (@results.last.first[method_sym] or @results.last.first[m])
+      return @results.compact.map {|rs| rs.map {|r| r[method_sym] || r[m] } }.flatten
     end
+    super
   end
 
 end

data/lib/kat/version.rb

@@ -1,3 +1,3 @@
 class Kat
-  VERSION = '0.1.3'
+  VERSION = '0.3.0'
 end

data/test/kat_test.rb

@@ -0,0 +1,256 @@
+require 'minitest/autorun'
+
+begin
+  require 'minitest/pride'
+rescue LoadError
+end
+
+require 'kat'
+
+describe Kat do
+  before do
+    @kat = { :vanilla  => Kat.new,
+             :basic    => Kat.new('test'),
+             :advanced => Kat.new('test', { :category => 'books' }) }
+  end
+
+# Quick search tests
+
+  describe 'when quick searching' do
+    it 'returns a result set' do
+      Kat.search('test').must_be_instance_of Array
+      Kat.search('test').size.must_equal 25
+    end
+  end
+
+# Vanilla query tests
+
+  describe 'when checking if a vanilla query responds to result field before searching' do
+    it 'returns false' do
+      [ :titles, :magnets, :downloads, :sizes, :files, :ages, :seeds, :leeches ].each do |s|
+        @kat[:vanilla].respond_to?(s).must_equal false
+      end
+    end
+  end
+
+  describe 'when checking if a vanilla query responds to result fields after searching' do
+    it 'returns true' do
+      @kat[:vanilla].search
+      [ :titles, :magnets, :downloads, :sizes, :files, :ages, :seeds, :leeches ].each do |s|
+        @kat[:vanilla].respond_to?(s).must_equal true
+      end
+    end
+  end
+
+  describe 'when building a vanilla query' do
+    it 'returns a query to new torrents' do
+      @kat[:vanilla].query.must_equal 'new/'
+    end
+  end
+
+  describe 'when searching with a vanilla query' do
+    it 'returns a full result set' do
+      @kat[:vanilla].search.must_be_instance_of Array
+      [ :search, :titles, :magnets, :downloads, :sizes, :files, :ages, :seeds, :leeches ].each do |s|
+        @kat[:vanilla].send(s).size.must_equal 25
+      end
+    end
+  end
+
+  describe 'when searching the 2nd page of a vanilla query' do
+    it 'returns a full result set' do
+      @kat[:vanilla].search(1).must_be_instance_of Array
+      @kat[:vanilla].search(1).size.must_equal 25
+    end
+  end
+
+  describe 'when searching 2 pages of a vanilla query' do
+    it 'returns 50 results for each result field' do
+      @kat[:vanilla].search
+      @kat[:vanilla].search(1)
+      if @kat[:vanilla].respond_to? :titles
+        [ :titles, :magnets, :downloads, :sizes, :files, :ages, :seeds, :leeches ].each do |s|
+          @kat[:vanilla].send(s).size.must_equal 50
+        end
+      else
+        # Returning a failure, not an error
+        proc { @kat[:vanilla].titles }.wont_raise NoMethodError
+      end
+    end
+  end
+
+  describe 'when rebuilding a vanilla query' do
+    it 'returns a query to new torrents' do
+      @kat[:vanilla].query = nil
+      @kat[:vanilla].query.must_equal 'new/'
+    end
+  end
+
+  describe 'when changing the search term on a vanilla query' do
+    it 'returns a query to usearch' do
+      @kat[:vanilla].query = 'test'
+      @kat[:vanilla].query.must_equal 'usearch/test/'
+    end
+  end
+
+  describe 'when adding an array of search terms to a vanilla query' do
+    it 'returns a query to usearch' do
+      @kat[:vanilla].query = [ 'test', 'category:books' ]
+      @kat[:vanilla].query.must_equal 'usearch/test category:books/'
+    end
+  end
+
+  describe 'when adding an array of crap to a vanilla query' do
+    it 'returns a valid query' do
+      @kat[:vanilla].query = [ 0, {}, [ 'test', 0..1 ] ]
+      @kat[:vanilla].query.must_equal 'usearch/test/'
+    end
+  end
+
+# Basic query tests
+
+  describe 'when checking if a basic query responds to result fields after searching' do
+    it 'returns true' do
+      @kat[:basic].search
+      [ :titles, :magnets, :downloads, :sizes, :files, :ages, :seeds, :leeches ].each do |s|
+        @kat[:basic].respond_to?(s).must_equal true
+      end
+    end
+  end
+
+  describe 'when building a basic query' do
+    it 'returns a query to usearch' do
+      @kat[:basic].query.must_equal 'usearch/test/'
+    end
+  end
+
+  describe 'when building a basic query with pages' do
+    it 'returns a query to usearch with page numbers' do
+      @kat[:basic].query(1).must_equal 'usearch/test/2/'
+    end
+  end
+
+  describe 'when changing the search term of a basic query to nil' do
+    it 'returns a query to new' do
+      @kat[:basic].query = nil
+      @kat[:basic].query.must_equal 'new/'
+    end
+  end
+
+  describe 'when adding options to a basic query' do
+    it 'returns a query to usearch with options' do
+      @kat[:basic].options = { :category => 'movies' }
+      @kat[:basic].options.must_equal({ :category => 'movies' })
+      @kat[:basic].query.must_equal 'usearch/test category:movies/'
+      @kat[:basic].results.must_be_empty
+      @kat[:basic].pages.must_be :==, -1
+    end
+  end
+
+  describe 'when adding options to a basic query with pages' do
+    it 'returns a query to usearch with options and page numbers' do
+      @kat[:basic].options = { :category => 'movies' }
+      @kat[:basic].options.must_equal({ :category => 'movies' })
+      @kat[:basic].query(1).must_equal 'usearch/test category:movies/2/'
+      @kat[:basic].results.must_be_empty
+      @kat[:basic].pages.must_be :==, -1
+    end
+  end
+
+  describe 'when searching with a basic query' do
+    it 'returns a result set' do
+      @kat[:basic].search.must_be_instance_of Array
+      @kat[:basic].search.size.must_equal 25
+      @kat[:basic].pages.must_be :>, 0
+    end
+  end
+
+  describe 'when searching the 2nd page of a basic query' do
+    it 'returns a result set' do
+      @kat[:basic].search(1).must_be_instance_of Array
+      @kat[:basic].search(1).size.must_equal 25
+      @kat[:basic].pages.must_be :>, 0
+    end
+  end
+
+  describe 'when searching with the same basic query twice' do
+    it 'returns the same result set' do
+      @kat[:basic].search.must_equal @kat[:basic].search
+    end
+  end
+
+  describe 'when searching for something that does not exist in a basic query' do
+    it 'returns an empty set, sets an error and sets pages to 0' do
+      @kat[:basic].query = 'owijefbvoweivf'
+      @kat[:basic].search.must_be_nil
+      @kat[:basic].error.must_be_instance_of Hash
+      @kat[:basic].error[:error].must_be_instance_of OpenURI::HTTPError
+      @kat[:basic].error[:error].message.must_equal '404 Not Found'
+      @kat[:basic].pages.must_equal 0
+    end
+  end
+
+  describe 'when searching for something with 1 page of results in a basic query' do
+    it 'returns a result set and sets the pages to 1' do
+      @kat[:basic].options = { :category => 'wallpapers' }
+      @kat[:basic].options.must_equal({ :category => 'wallpapers' })
+      @kat[:basic].search.wont_be_nil
+      @kat[:basic].search.size.wont_equal 0
+    end
+  end
+
+  describe 'when passing query= a Symbol' do
+    it 'works just like a String' do
+      @kat[:basic].query = :test
+      @kat[:basic].query.must_equal 'usearch/test/'
+    end
+  end
+
+  describe 'when passing a non-String-or-Array object to query=' do
+    it 'raises an ArgumentError' do
+      proc { @kat[:basic].query = { :foo => 'bar' } }.must_raise ArgumentError
+    end
+  end
+
+  describe 'when passing a non-Hash object to options=' do
+    it 'raises an ArgumentError' do
+      proc { @kat[:basic].options = 'foobar' }.must_raise ArgumentError
+    end
+  end
+
+# Advanced query tests
+
+  describe 'when building an advanced query' do
+    it 'returns a query with options to usearch' do
+      @kat[:advanced].query.must_equal 'usearch/test category:books/'
+    end
+  end
+
+  describe 'when building an advanced query with pages' do
+    it 'returns a query with options and page numbers' do
+      @kat[:advanced].query(1).must_equal 'usearch/test category:books/2/'
+    end
+  end
+
+  describe 'when building an advanced query with select fields' do
+    it 'returns a query with options to usearch' do
+      @kat[:advanced].options = { :language => 2 }
+      @kat[:advanced].query.must_equal 'usearch/test category:books lang_id:2/'
+    end
+  end
+
+  describe 'when using symbols instead of strings in an advanced query' do
+    it 'returns the same query string' do
+      @kat[:advanced].options = { :category => :books }
+      @kat[:advanced].query.must_equal 'usearch/test category:books/'
+    end
+  end
+
+  describe 'when sorting fields' do
+    it 'adds a sort part to the query string' do
+      @kat[:advanced].options = { :sort => :size }
+      @kat[:advanced].query.must_equal 'usearch/test category:books/?field=size&sorder=desc'
+    end
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kat
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Fission Xuiptz
@@ -31,6 +31,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - LICENSE
 - README.md
@@ -38,6 +39,7 @@ files:
 - kat.gemspec
 - lib/kat.rb
 - lib/kat/version.rb
+- test/kat_test.rb
 homepage: http://github.com/fissionxuiptz/kat
 licenses:
 - MIT
@@ -62,4 +64,5 @@ rubygems_version: 2.0.3
 signing_key: 
 specification_version: 4
 summary: Kickass Torrents Interface
-test_files: []
+test_files:
+- test/kat_test.rb