solr_lite 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 4130e04f0ee49e7d45b2bc833a4e9bec1b404f5f
-  data.tar.gz: 8a812c8c94f95756cd6ba9001b9ff921e676dac6
+SHA256:
+  metadata.gz: acee17a7d6d3d09c7777502658cbd008768fc8c08c16a474b5880dfa1fee9e08
+  data.tar.gz: 56fb2f341bf5ea7ca3729c1baa9501450b4176388c89f7f484600d1b03edee60
 SHA512:
-  metadata.gz: d55a65d9d56e681d7e92e2297d82a067a3e49a10007665b88961e511c74a2b9bb3d6661c674ec7e9e230f1c81d06c7bbeb694b75e792f6a9202940cc7c0f8c41
-  data.tar.gz: 4bea5f25c2caf7d525c48a2cacd98d8d460aa53ee7e0071cdaf4277e6b5ead40277c5b6b2533d01ecee9a5f6ac4664fa3352b863c4b72a749f7715ad97cbed50
+  metadata.gz: dae1e89e0f1bba8c6fa59b2a982890cb5240837b5c9593f17996f4af1079dc26307700e90342c1def2c75053ad08c95d6599d1825a9164cc914ac413f5538f14
+  data.tar.gz: 229cb68d206b08835ca786c1477a2600fa43ee453165d18b016823a6cc3fc79146307d64b7c96cf1f7a2b6113b73fcdf3e21ea87659d32cca1518153c6ce1c66

data/lib/search_params.rb

@@ -1,12 +1,54 @@
 require "filter_query.rb"
 require "facet_field.rb"
 module SolrLite
+
+  # Represents the parameters to send to Solr during a search.
   class SearchParams
-    attr_accessor :a, :q, :fq, :facets, :page, :page_size, :fl, :sort, :facet_limit,
-      :spellcheck, :hl, :hl_fl, :hl_snippets
+
+    # [String] The q value to pass to Solr.
+    attr_accessor :q
+
+    # [Array] Array of {SolrLite::FilterQuery} objects to pass to Solr.
+    attr_accessor :fq
+
+    # [Array] Array of {SolrLite::FacetField} objects to pass to Solr.
+    attr_accessor :facets
+
+    # [Integer] Page number to request from Solr.
+    attr_accessor :page
+
+    # [Integer] Number of documents per page to request from Solr.
+    attr_accessor :page_size
+
+    # [String] List of fields to request from Solr.
+    attr_accessor :fl
+
+    # [String] Sort string to pass to Solr.
+    attr_accessor :sort
+
+    # [Integer] Number of facet values to request from Solr.
+    attr_accessor :facet_limit
+
+    # [Bool] True to request Solr to use spellchecking (defaults to false).
+    attr_accessor :spellcheck
+
+    #  [Bool] Set to true to request hit highlighting information from Solr.
+    attr_accessor :hl
+
+    #  [String] Sets the highlight fields (hl.fl) to request from Solr.
+    attr_accessor :hl_fl
+
+    #  [Integer] Sets the number of hit highlights to request from Solr.
+    attr_accessor :hl_snippets
 
     DEFAULT_PAGE_SIZE = 20
 
+    # Creates an instance of the SearchParams class.
+    #
+    # @param q [String] The q value to use.
+    # @param fq [Array] An array of {SolrLite::FilterQuery} objects to pass to Solr.
+    # @param facets [Array] An array of {SolrLite::FacetField} objects to pass to Solr.
+    #
     def initialize(q = "", fq = [], facets = [])
       @q = q
       @fq = fq          # array of FilterQuery
@@ -23,10 +65,21 @@ module SolrLite
       @hl_snippets = 1
     end
 
+    # Returns facet information about a given field.
+    #
+    # @param field [String] Name of the field.
+    # @return [SolrLite::FacetField] An object with the facet information.
+    #
     def facet_for_field(field)
       @facets.find {|f| f.name == field}
     end
 
+    # Sets the `remove_url` value for the given facet and value.
+    #
+    # @param field [String] Name of facet field.
+    # @param value [String] Value of the facet field.
+    # @param url [String] URL to set.
+    #
     def set_facet_remove_url(field, value, url)
       facet = facet_for_field(field)
       if facet != nil
@@ -34,10 +87,15 @@ module SolrLite
       end
     end
 
+    # Calculates the starting row number.
+    #
+    # @return [Integer] The starting row number for the current page and page_size.
+    #
     def start_row()
       (@page - 1) * @page_size
     end
 
+    # Sets the starting row number and recalculates the current page based on the current page_size.
     def star_row=(start)
       # recalculate the page
       if @page_size == 0
@@ -48,12 +106,17 @@ module SolrLite
       nil
     end
 
-    # Returns the string that we need render on the Browser to execute
+    # Calculates the query string that we need render on the browser to execute
     # a search with the current parameters.
     #
-    # facet_to_ignore: a FilterQuery object with a value to ignore when
-    #   creating the query string.
-    # q_override: a string with a Solr query to use instead of the current q value
+    # @param facet_to_ignore [SolrLite::FilterQuery] Object with a specific facet to ignore when
+    #     creating the query string. This is used to create the "remove this facet from the search"
+    #     links that are shown to the user.
+    # @param q_override [String] The q value to use if we want to use a different value
+    #     from the current one.
+    #
+    # @return [String] The string calculated.
+    #
     def to_user_query_string(facet_to_ignore = nil, q_override = nil)
       qs = ""
       q_value = q_override != nil ? q_override : @q
@@ -75,12 +138,21 @@ module SolrLite
       qs
     end
 
+    # Calculates the query string that we need render on the browser to execute
+    # a search with the current parameters and NO q parameter.
+    #
+    # @return [String] The string calculated.
+    #
     def to_user_query_string_no_q()
       to_user_query_string(nil, '')
     end
 
-    # Returns the string that we need to pass Solr to execute a search
-    # with the current parameters.
+    # Calculates the query string that needs to be passed to Solr to issue a search
+    # with the current search parameters.
+    #
+    # @param extra_fqs [Array] Array of {SolrLite::FilterQuery} objects to use.
+    # @return [String] Query string to pass to Solr for the current parameters.
+    #
     def to_solr_query_string(extra_fqs = [])
       qs = ""
       if @q != ""
@@ -123,10 +195,12 @@ module SolrLite
       qs
     end
 
-    # Returns an array of values that can be added to an HTML form
-    # to represent the current search parameters. Notice that we do
-    # NOT include the `q` parameter there is typically an explicit
-    # HTML form value for it on the form.
+    # Returns an array of values that can be added to an HTML form to represent the current
+    # search parameters. Notice that we do NOT include the `q` parameter because there is
+    # typically an explicit HTML form value for it on the form.
+    #
+    # @return [Array] An array of Hash objects with the values for the current search.
+    #
     def to_form_values()
       values = []
 
@@ -144,10 +218,21 @@ module SolrLite
       values
     end
 
+    # Returns a friendly string version of this object.
+    #
+    # @return [String] With information about the current search parameters.
+    #
     def to_s()
       "q=#{@q}\nfq=#{@fq}"
     end
 
+    # Creates a SearchParams object with the values in a query string.
+    # This is the inverse of `to_user_query_string()`.
+    #
+    # @param qs [String] A query string with the search parameters to use.
+    # @param facet_fields [Array] An array of {SolrLite::FacetField} to set in the returned object.
+    # @return [SolrLite::SearchParams] An object prepopulated with the values indicated in the query string.
+    #
     def self.from_query_string(qs, facet_fields = [])
       params = SearchParams.new
       params.facets = facet_fields

data/lib/solr.rb

@@ -11,31 +11,45 @@ module SolrLite
     end
   end
 
+  # Represents a Solr instance.
+  # This is the main public interface to submit commands (get, search, delete, update) to Solr.
+  #
   class Solr
+
+    # [String] Set this value if you want to send a query parser (defType) attribute to Solr
+    # when submitting commands. Leave as nil to use the value configured on the server.
+    attr_accessor :def_type
+
     # Creates an instance of the Solr class.
-    # Parameters:
-    #   solr_url: string with the URL to Solr ("http://localhost:8983/solr/bibdata")
-    #   logger: an instance of Rails::logger if using Rails.
-    #       Could also be SolrLite::DefaultLogger which defaults to the console.
-    #       Or nil to omit logging.
+    #
+    # @param solr_url [String] URL to Solr, e.g. "http://localhost:8983/solr/bibdata"
+    # @param logger [Object] An object that provides an `info` method to log information about the requests.
+    #     It could be an instance of Rails::logger if using Rails or an instance of SolrLite::DefaultLogger
+    #     that outputs to the console. Use `nil` to omit logging.
+    #
     def initialize(solr_url, logger = nil)
       raise "No solr_url was indicated" if solr_url == nil
       @solr_url = solr_url
       @logger = logger
+      @def_type = nil
     end
 
     # Fetches a Solr document by id.
-    # Parameters:
-    #   id: ID of the document to fetch.
-    #   q_field: Query field (defaults to "q")
-    #   fl: list of fields to fetch (defaults to "*")
     #
-    # Returns a hash with the document information or nil if no document was found.
-    # Raises an exception if more than one document was found.
+    # @param id [String] ID of the document to fetch.
+    # @param q_field [String] Query field.
+    # @param fl [String] List of fields to fetch.
+    #
+    # @return [Hash] The document found or nil if no document was found.
+    #     Raises an exception if more than one document was found.
+    #
     def get(id, q_field = "q", fl = "*")
       query_string = "#{q_field}=id%3A#{id}"     # %3A => :
       query_string += "&fl=#{fl}"
       query_string += "&wt=json&indent=on"
+      if @def_type != nil
+        query_string += "&defType=#{@def_type}"
+      end
       url = "#{@solr_url}/select?#{query_string}"
       solr_response = Response.new(http_get(url), nil)
       if solr_response.num_found > 1
@@ -45,16 +59,17 @@ module SolrLite
     end
 
     # Issues a search request to Solr.
-    # Parameters:
-    #   params: an instance of SolrParams.
-    #   extra_fqs: array of FilterQuery objects. This is used to
+    #
+    # @param params [SolrParams] Search parameters.
+    # @param extra_fqs [Array] Array of [SolrLite::FilterQuery] objects. This is used to
     #     add filters to the search that we don't want to allow the
     #     user to override.
-    #   qf: Used to override the server's qf value.
-    #   mm: Used to override the server's mm value.
-    #   debug: true to include debugQuery info in the response. (defaults to false)
+    # @param qf [String] Use to override the server's qf value.
+    # @param mm [String] Use to override the server's mm value.
+    # @param debug [Bool] Set to `true` to include `debugQuery` info in the response.
+    #
+    # @return [SolrLite::Response] The result of the search.
     #
-    # Returns an instance of SolrLite::Response
     def search(params, extra_fqs = [], qf = nil, mm = nil, debug = false)
       if params.fl != nil
         query_string = "fl=#{params.fl.join(",")}"
@@ -78,28 +93,55 @@ module SolrLite
         query_string += "&debugQuery=true"
       end
 
+      if @def_type != nil
+        query_string += "&defType=#{@def_type}"
+      end
+
       url = "#{@solr_url}/select?#{query_string}"
       http_response = http_get(url)
       response = Response.new(http_response, params)
       response
     end
 
-    # shortcut for search
+    # Shortcut for the `search` method.
+    #
+    # @param terms [String] the value to use as the query (q) in Solr.
+    # @return [SolrLite::Response] The result of the search.
+    #
     def search_text(terms)
       params = SearchParams.new(terms)
       search(params)
     end
 
+    # Calculates the starting row for a given page and page size.
+    #
+    # @param page [Integer] Page number.
+    # @param page_size [Integer] Number of documents per page.
+    #
+    # @return [Integer] The row number to pass to Solr to start at the given page.
+    #
     def start_row(page, page_size)
       (page - 1) * page_size
     end
 
+    # Issues an update to Solr with the data provided.
+    #
+    # @param json [String] String the data in JSON format to sent to Solr.
+    #     Usually in the form `"[{ f1:v1, f2:v2 }, { f1:v3, f2:v4 }]"`
+    # @return [SolrLite::Response] The result of the update.
+    #
     def update(json)
       url = @solr_url + "/update?commit=true"
       solr_response = http_post_json(url, json)
       solr_response
     end
 
+
+    # Deletes a Solr document by id.
+    #
+    # @param id [String] ID of the document to delete.
+    # @return [SolrLite::Response] The result of the delete.
+    #
     def delete_by_id(id)
       # Use XML format here because that's the only way I could get
       # the delete to recognize ids with a colon (e.g. bdr:123).
@@ -113,6 +155,11 @@ module SolrLite
       solr_response
     end
 
+    # Deletes all documents that match a query in Solr.
+    #
+    # @param query [String] The query to pass to Solr.
+    # @return [SolrLite::Response] The result of the delete.
+    #
     def delete_by_query(query)
       url = @solr_url + "/update?commit=true"
       payload = '{ "delete" : { "query" : "' + query + '" } }'
@@ -120,6 +167,10 @@ module SolrLite
       solr_response
     end
 
+    # Deletes all documents in Solr.
+    #
+    # @return [SolrLite::Response] The result of the delete.
+    #
     def delete_all!()
       delete_by_query("*:*")
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solr_lite
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors:
 - Hector Correa
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-23 00:00:00.000000000 Z
+date: 2018-12-20 00:00:00.000000000 Z
 dependencies: []
 description: A lightweight gem to connect to Solr and run queries. Requires no extra
   dependencies.
@@ -47,7 +47,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2.1
+rubygems_version: 2.7.7
 signing_key: 
 specification_version: 4
 summary: A lightweight gem to connect to Solr and run queries