wise_gopher 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7568e5308f8025d5b1f9d9cf2a869a6560b6a0377aed7ca3a79c063c5abe76ec
-  data.tar.gz: cd076d93f65ff85e50c4279e67604b7ba4caa6811390bdc1bbdba48197d8e50c
+  metadata.gz: dc88a6090305daa53b83df1cd298531d6209dbb74cce4aa2c1492a2c3987c168
+  data.tar.gz: 874dc19cf652522bdb9ebf89e45543c5ce912dd8a636d6dd01bc7ab7e78e10ec
 SHA512:
-  metadata.gz: 7a0d433f7e6c9dbabde1505caaa3b9a0c9318462969458d873280e0bd567c28724172fa1779f1b3163ca7334c8be2b189af9691c27654f1a26f9fc9f77e5ad57
-  data.tar.gz: 1517fed4b04a5c50640d8824fb9e97827905163c26155e5841dc733ef3349d3f5d27de31f8168f05bb2c9442782075cd71968edb8a42783fed61787dc6154625
+  metadata.gz: 4b0f65b90b90414aa03e572e33e0d3ac360f886c61afd19dc3b026b9ff0e76c9fd7040b77cf8c1b1bf89dcddd665d36e1125ff5ec27ff21c73d232b42dfeab09
+  data.tar.gz: ed4ceb261617680856ad9896b68b1ac0711ae911edf264d3d14fde7a5b7405b2d6843cd03333be036927fe762e45b7054e023d6f53e353cd19e117f05e451db7

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [0.2.0] - 2021-08-04
+
+- Add raw_params to `WiseGopher::Base` to insert raw sql in query before handling other params
+
 ## [0.1.0] - 2021-06-22
 
 - Initial release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    wise_gopher (0.1.0)
+    wise_gopher (0.2.0)
       activerecord (>= 5, < 7)
 
 GEM

data/README.md

@@ -50,7 +50,7 @@ class PopularArticle < WiseGopher::Base
     INNER JOIN ratings ON ratings.article_id = articles.id
     WHERE author_username = {{ username }}
     GROUP BY articles.id
-    HAVING average_rating > {{ mininum_rating }}
+    HAVING AVG(ratings.stars) > {{ mininum_rating }}
     ORDER BY averating_rating
   SQL
   
@@ -75,14 +75,14 @@ Which you would use this way:
 result = PopularArticle.execute_with(minimum_rating: 3, username: "PageHey ")
 # => [#<PopularArticle::Row:0x0000560c37e9de48 @title="My first gem is out!", @average_rating=3.5 ...>, ...]
 puts result.first
-# => Article 'My first gem is out!' by PageHey is rated 3.5/5.
+# => Article 'My first gem is out!' by PageHey is rated 3.50/5.
 result.first.class
 # => PopularArticle::Row
 ```
 
 ------
 
-So, basically what you need to do is make your class inherits from `WiseGopher::Base` and provide your SQL with `.query`. You can then declare what columns will be present in result with `.column` in a block given to `row`.
+So, basically what you need to do is make your class inherits from `WiseGopher::Base` and provide your SQL with `query`. You can then declare what columns will be present in result with `column` in a block given to `row`.
 
 
 If your query doesn't need any parameter like this one:
@@ -95,7 +95,7 @@ class PopularArticle < WiseGopher::Base
     end
 end
 ```
-You can simply get result with `.execute`:
+You can simply get result with `execute`:
 ```ruby
 PopularArticle.execute
 ```
@@ -116,28 +116,28 @@ class PopularArticle < WiseGopher::Base
     end
 end
 ```
-You should declare the params with `.param` so you can pass the parameters as a hash to `.execute_with`:
+You should declare the params with `param` so you can pass the parameters as a hash to `execute_with`:
 ```ruby
 PopularArticle.execute_with(author_name: "PageHey", published_after: Date.today - 1.month)
 ```
 
-If any parameter is missing or if you call `.execute` for a class that needs some, it will raise `WiseGopher::ArgumentError`.
+If any parameter is missing or if you call `execute` for a class that needs some, it will raise `WiseGopher::ArgumentError`.
 
 Before query execution, the placeholders will be replaced with the standard `?` placeholder or with the `$1`, `$2` ... numbered placeholders for PostgreSQL database.
 
-To declare the column in result, you should use `.row` and pass it a block. Calling this method will create a `Row` class nested into your query class. The block will be then executed in `Row` class context. In this context you can use `.column` but also define method, include module, basicaly write any code you would find in a class delacration.
+To declare the column in result, you should use `row` and pass it a block. Calling this method will create a `Row` class nested into your query class. The block will be then executed in `Row` class context. In this context you can use `column` but also define method, include module, basicaly write any code you would find in a class delacration.
 
-The goal of this syntax is to gather in the same file the input and output logic of the query while keeping dedicated classes for each logic.
-You can provide a custom class to `.row` if you prefer. If you still pass the block to the method, the `WiseGopher::Row` module will be included in the class before evaluating it, so you can have this syntax:
+The goal of this syntax is to gather in the same file the inputs and outputs of the query while keeping dedicated classes for each subject.
+You can provide a custom class to `row` if you prefer. If you still pass the block to the method, the `WiseGopher::Row` module will be included in the class before evaluating it, so you can have this syntax:
 ```ruby
-_/my_custom_row.rb_
+# /my_custom_row.rb
 class MyCustomRow
     def some_custom_method
         # [...]
     end
 end
 
-_/my_query_class.rb
+# /my_query_class.rb
 class MyQueryClass < WiseGopher::Base
     query "SELECT title FROM articles"
     
@@ -147,13 +147,88 @@ class MyQueryClass < WiseGopher::Base
 end
 ```
 
-**If you don't give any block to `.row`, make sure you include `WiseGopher::Row` in your class.**
+**If you don't give any block to `row`, make sure you include `WiseGopher::Row` in your class.**
 
+------
+## Raw params
+If you need to dinamically interpolate raw SQL in your query, you can use `raw_param`. The value passed with `execute_with` will be interpolated in the base query before inserting the other params.
+```ruby
+class AnnualReport < WiseGopher::Base
+    query <<-SQL
+        SELECT month, revenue
+        FROM heavy_computations
+        WHERE employee_id = {{ id }}
+        {{ order_by }}
+    SQL
+    
+    param :id, :integer
+    
+    raw_param :order_by
+end
+
+AnnualReport.execute_with(id: 1, order_by: "ORDER BY id ASC")
+```
+executed query will look like this:
+```SQL
+SELECT month, revenue
+FROM heavy_computations
+WHERE employee_id = ?
+ORDER BY id ASC
+```
+By default, `raw_param` is required but you can pass `optional: true`. You can then omit the param and the placeholder will be remove for this query instance.
+```ruby
+AnnualReport.execute_with(id: 1, order_by: "ORDER BY id ASC")
+```
+```SQL
+SELECT month, revenue
+FROM heavy_computations
+WHERE employee_id = ?
+```
+
+You can also provide _prefix_ and/or _suffix_ to `raw_param` to make the `raw_param` clearer and the argument lighter.
+```ruby
+class AnnualReport < WiseGopher::Base
+    query <<-SQL
+        SELECT month, revenue
+        FROM heavy_computations
+        WHERE employee_id = {{ id }}
+        {{ order_by }}
+    SQL
+    
+    param :id, :integer
+    
+    raw_param :order_by, prefix: "ORDER BY ", suffix: " ASC" # note the spacings
+end
+AnnualReport.execute_with(id: 1, order_by: "id")
+```
+Finally, a default option is also supported, thus making the param optional:
+```ruby
+class AnnualReport < WiseGopher::Base
+    query <<-SQL
+        SELECT month, revenue
+        FROM heavy_computations
+        WHERE employee_id = {{ id }}
+        {{ order_by }}
+    SQL
+    
+    param :id, :integer
+    
+    raw_param :order_by, prefix: " ORDER BY ", suffix: " ASC ", default: "id"
+end
+AnnualReport.execute_with(id: 1)
+```
+executed query:
+```SQL
+SELECT month, revenue
+FROM heavy_computations
+WHERE employee_id = ?
+ORDER BY id ASC
+```
 
 ------
 ## Methods documentation
 ### WiseGopher::Base (class)
-#### .param
+#### ::param
 ```ruby
 param(name, type, transform: nil)
 ```
@@ -162,10 +237,23 @@ Argument | Required | Descrition
 ------------ | ------------- | ------------- 
 name | true | The name of the parameter as written in the `{{ placeholder }}`
 type | true | The type of the column. It can be any type registred as ActiveRecord::Type. Including yours
-transform: | false | `Proc` or `Symbol`. An operation that will be call before creating the bind parameter when you call `.execute_with`.
+transform: | false | `Proc` or `Symbol`. An operation that will be call before creating the bind parameter when you call `execute_with`.
+
+#### ::raw_param
+```ruby
+raw_param(name, prefix: nil, suffix: nil, default: nil, optional: false)
+```
+
+Argument | Required | Descrition
+------------ | ------------- | ------------- 
+name | true | The name of the parameter as written in the `{{ placeholder }}`
+prefix: | false | The string to be inserted **before** the value passed as argument. No spaces will be added around to allow maximum customization.
+suffix: | false | The string to be inserted **after** the value passed as argument. No spaces will be added around to allow maximum customization.
+default: | false | The default value used if none is passed when calling the query
+optional: | false | an empty string will be inserted in place of the placeholder if neither argument or default is provided.
 
 ###  WiseGopher::Row (module)
-#### .column
+#### ::column
 ```ruby
 column(name, type, transform: nil, as: nil)
 ```
@@ -180,10 +268,10 @@ as: | false | The name of the getter you want on the row instance for this colum
 ------
 ## Tips
 #### transform: argument as proc
-If you provide a proc to the `transform:` argument (either on `.column` or `.param`), you can expect one argument or none. If one argument is expected the value of the param or column will be passed.
+If you provide a proc to the `transform:` argument (either on `column` or `param`), you can expect one argument or none. If one argument is expected the value of the param or column will be passed.
 
 #### Prepare query for later execution
-You can prepare the query with param without executing it by simply calling `.new` on your class and providing the params an later call `.execute`.
+You can prepare the query with param without executing it by simply calling `new` on your class and providing the params an later call `execute`.
 ```ruby
 class PopularArticle < WiseGopher::Base
     query <<-SQL
@@ -203,7 +291,7 @@ last_month_articles.execute # => [#<PopularArticle::Row:0x0000560c37e9de48 ...>]
 ```
 
 #### Ignore column in result
-If for some reason, you have a column in your result that you don't want to retrieve on the row instances, you can use `.ignore`.
+If for some reason, you have a column in your result that you don't want to retrieve on the row instances, you can use `ignore`.
 ```ruby
 class MyQuery < WiseGopher::Base
     query "SELECT title, rating FROM articles"
@@ -217,6 +305,45 @@ end
 MyQuery.execute # => no error raised
 ```
 
+#### Array of value as parameter
+You can pass an array as parameter value. The will then make a comma separated list of placeholders and pass the arguments as many bind parameters.
+```ruby
+class MyQuery < WiseGopher::Base
+    query "SELECT title FROM articles WHERE rating in ({{ ratings }})"
+    
+    param :ratings, :integer
+    
+    row do
+        column :title, :string
+    end
+end
+
+MyQuery.execute_with(ratings: [1, 2])
+# query will be "SELECT title FROM articles WHERE rating in (?, ?)"
+```
+
+#### Classic param in raw_param
+As the raw_params are interpolated before the classic params, you can have placeholders in them:
+```ruby
+class MyQuery < WiseGopher::Base
+    query <<-SQL
+        SELECT title FROM articles
+        WHERE rating > ({{ ratings }})"
+    SQL
+    
+    param :min_rating, :integer
+    
+    raw_param :or_condition, prefix: " OR "
+    
+    row do
+        column :title, :string
+    end
+end
+
+MyQuery.execute_with(min_rating: 1, or_condition: "rating = {{ min_rating }}")
+# query will be "SELECT title FROM articles WHERE rating > ? OR rating = ?"
+```
+
 ------
 
 ## Contributing

data/lib/wise_gopher.rb

@@ -4,6 +4,7 @@ require_relative "wise_gopher/version"
 require_relative "wise_gopher/base"
 require_relative "wise_gopher/column"
 require_relative "wise_gopher/param"
+require_relative "wise_gopher/raw_param"
 require_relative "wise_gopher/row"
 require_relative "wise_gopher/errors"
 

data/lib/wise_gopher/base.rb

@@ -7,7 +7,8 @@ module WiseGopher
   class Base
     def self.inherited(base)
       base.class_eval do
-        @params = {}
+        @raw_params = {}
+        @params     = {}
       end
       base.include Methods
       base.extend  ClassMethods
@@ -15,16 +16,26 @@ module WiseGopher
 
     # class methods for WiseGopher::Base
     module ClassMethods
-      attr_reader :row_class, :params
+      attr_reader :row_class, :params, :raw_params
 
       def query(query)
         const_set "QUERY", query.freeze
       end
 
       def param(name, type, transform = nil)
-        param = WiseGopher::Param.new(name, type, transform)
+        new_param = WiseGopher::Param.new(name, type, transform)
 
-        params[param.name] = param
+        ensure_param_name_is_available(new_param.name)
+
+        params[new_param.name] = new_param
+      end
+
+      def raw_param(name, **kwargs)
+        raw_param = WiseGopher::RawParam.new(name, **kwargs)
+
+        ensure_param_name_is_available(raw_param.name)
+
+        raw_params[raw_param.name] = raw_param
       end
 
       def row(base = nil, &block)
@@ -47,16 +58,26 @@ module WiseGopher
         new(inputs).execute
       end
 
+      def ensure_all_params_are_given(inputs = {})
+        missing_params = required_params.keys - inputs.keys.map(&:to_s)
+
+        raise WiseGopher::ArgumentError, required_params.slice(*missing_params) if missing_params.any?
+      end
+
       private
 
       def define_generic_row_class
         @row_class = const_set "Row", Class.new
       end
 
-      def ensure_all_params_are_given(inputs = {})
-        missing_params = params.keys - inputs.keys.map(&:to_s)
+      def ensure_param_name_is_available(name)
+        return unless params[name] || raw_params[name]
+
+        raise WiseGopher::ParamAlreadyDeclared, name
+      end
 
-        raise WiseGopher::ArgumentError, params.slice(*missing_params) if missing_params.any?
+      def required_params
+        params.merge(raw_params.reject { |_name, raw_param| raw_param.optional? })
       end
     end
 
@@ -72,13 +93,15 @@ module WiseGopher
         @bind_symbol    = WiseGopher.postgresql? ? +"$1" : "?"
         @query_prepared = false
 
+        self.class.ensure_all_params_are_given(inputs)
+
         prepare_query
       end
 
       def execute
         ensure_row_class_is_declared
 
-        result = connection.exec_query(@query.squish, query_class.to_s, @binds, prepare: true)
+        result = connection.exec_query(query.squish, query_class.to_s, @binds, prepare: true)
 
         ensure_all_columns_are_declared(result)
 
@@ -88,24 +111,32 @@ module WiseGopher
       def prepare_query
         return if @query_prepared
 
-        @query = query_class::QUERY.dup
+        prepare_raw_params
+
+        prepare_params
 
+        @query_prepared = true
+      end
+
+      private
+
+      def prepare_params
         query_class.params.each do |name, param|
           name  = name.to_sym
           value = @inputs[name]
 
           bind_params(value, param)
         end
-
-        @query_prepared = true
       end
 
-      private
-
       def query_class
         self.class
       end
 
+      def query
+        @query ||= query_class::QUERY.dup
+      end
+
       def bind_params(value, param)
         if value.is_a? Array
           bind_collection_param(value, param)
@@ -117,19 +148,19 @@ module WiseGopher
       def bind_collection_param(values, param)
         bindings = values.map { use_bind_symbol }
 
-        replace_binding_placeholder(param.name, bindings.join(", "))
+        replace_placeholder(param.name, bindings.join(", "))
 
         values.each { |value| register_binding(value, param) }
       end
 
       def bind_single_param(value, param)
-        replace_binding_placeholder(param.name, use_bind_symbol)
+        replace_placeholder(param.name, use_bind_symbol)
 
         register_binding(value, param)
       end
 
-      def replace_binding_placeholder(name, binding_symbol)
-        @query.gsub!(/{{ ?#{name} ?}}/, binding_symbol)
+      def replace_placeholder(name, value_to_insert)
+        query.gsub!(/{{ ?#{name} ?}}/, value_to_insert)
       end
 
       def register_binding(value, param)
@@ -161,6 +192,15 @@ module WiseGopher
       def connection
         ActiveRecord::Base.connection
       end
+
+      def prepare_raw_params
+        query_class.raw_params.each do |name, param|
+          name  = name.to_sym
+          value = @inputs[name]
+
+          replace_placeholder(name, param.to_s(value))
+        end
+      end
     end
   end
 end

data/lib/wise_gopher/errors.rb

@@ -11,7 +11,8 @@ module WiseGopher
 
     def initialize(params)
       @params = params.map do |name, param|
-        "- \"#{name}\" (#{param.type.type})"
+        param_type = param.respond_to?(:type) ? param.type.type : :raw_param
+        "- \"#{name}\" (#{param_type})"
       end.join("\n")
     end
 
@@ -62,13 +63,17 @@ module WiseGopher
   # raised when custom row class is given but doesn't include WiseGopher::Row
   class RowClassNeedsRowModule < Error
   end
-end
 
-# connection;
-# class Query < WiseGopher::Base
-#   query "SELECT title, rating FROM articles"
+  # raised when param are raw_param are declared with the same name
+  class ParamAlreadyDeclared < Error
+    attr_reader :param_name
+
+    def initialize(param_name)
+      @param_name = param_name
+    end
 
-#   row do
-#     column :title, :string
-#   end
-# end; Query.execute
+    def message
+      "'#{param_name}' is already declared either as 'raw_param' or standard 'param'."
+    end
+  end
+end

data/lib/wise_gopher/raw_param.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module WiseGopher
+  # Register query's raw_params and interpolate string in query
+  class RawParam
+    attr_reader :name, :optional, :default, :prefix, :suffix
+
+    def initialize(name, optional: false, default: nil, prefix: nil, suffix: nil)
+      @name     = name.to_s.freeze
+      @optional = optional
+      @default  = default
+      @prefix   = prefix.to_s.freeze
+      @suffix   = suffix.to_s.freeze
+    end
+
+    def to_s(string = nil)
+      raise ::ArgumentError, "value required" unless string || optional?
+
+      content = string || default
+
+      return "#{prefix}#{content}#{suffix}" if content
+
+      ""
+    end
+
+    def optional?
+      optional || !!default
+    end
+  end
+end

data/lib/wise_gopher/version.rb

@@ -3,7 +3,7 @@
 module WiseGopher
   module VERSION
     MAJOR = 0
-    MINOR = 1
+    MINOR = 2
     PATCH = 0
 
     STRING = [MAJOR, MINOR, PATCH].join(".")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wise_gopher
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - PageHey
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-06-29 00:00:00.000000000 Z
+date: 2021-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -199,6 +199,7 @@ files:
 - lib/wise_gopher/column.rb
 - lib/wise_gopher/errors.rb
 - lib/wise_gopher/param.rb
+- lib/wise_gopher/raw_param.rb
 - lib/wise_gopher/row.rb
 - lib/wise_gopher/version.rb
 - wise_gopher.gemspec
@@ -224,7 +225,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: Encapsulate raw SQL queries and return result as plain Ruby objects, using