eno 0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eb697b829ee2858e69995a4485607463b4b2c0740cb78f2c984bd25ffa188108
+  data.tar.gz: 40850710021d688e6a916e0f8c21ee5511990012f015c8c9541e9e700f815b59
+SHA512:
+  metadata.gz: cf6d28da3a66cc2db0121914f2ae29c578ec67f9d5ea72bc9acb9fc0d0c85215145f424092095b73abc6d68b094661ef5a73a318f84d3a70d2dba91c1f75a4b7
+  data.tar.gz: dec76ece5872f0f4688d1654ff2894809680e870f728165269516167101828be9e8379f77ef643f137604f4cf082a73d03c88ce0a05be34248350f32b40081b7

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+0.4 2019-01-21
+--------------
+
+* Implement query mutation
+* Can now use `!` as `not` operator
+* Clauses as real expressions
+* Implement context injection
+* Refactor and simplify code
+
+0.1 2019-01-16
+--------------
+
+* First working version

data/README.md

@@ -0,0 +1,164 @@
+# Eno is Not an ORM
+
+[INSTALL](#installing-eno) |
+[TUTORIAL](#getting-started) |
+[EXAMPLES](examples)
+
+## What is Eno?
+
+Eno is an experimental Ruby gem for working with SQL databases. Eno provides
+tools for writing SQL queries using plain Ruby and specifically for querying
+PostgreSQL and SQLite databases.
+
+Eno provides the following features:
+
+- Compose `SELECT` statements using plain Ruby syntax
+- Create arbitrarily complex `WHERE` clauses
+- Support for common table expressions (CTE) and joins
+- Compose queries and sub-queries
+- Create parametric queries using context variables
+- Reusable queries can be further refined and mutated
+
+## What is it good for?
+
+So why would anyone want to compose queries in Ruby instead of in plain SQL?
+That's actually a very good question. Libraries like ActiveRecord and Sequel
+already provide tools for querying relational databases. There's usage patterns
+like ActiveRecord's `where`:
+
+```ruby
+Client.where(order_count: [1, 3, 5])
+```
+
+And Sequel is a bit more flexible:
+
+```ruby
+Client.where { order_count > 10 }
+```
+
+But both stumble when it comes to putting together more complex queries.
+ActiveRecord queries in particular aren't really composable, making it actually
+easier to filter and manipulate records inside your app code than in your
+database.
+
+With both ActiveRecord and Sequel you'll need to eventually provide snippets of
+literal SQL. This is time-consuming, prevents your queries from being composable
+and makes it easy to expose your app to SQL injection.
+
+## Installing eno
+
+Using bundler:
+
+```ruby
+gem 'eno'
+```
+
+Or manually:
+
+```bash
+$ gem install eno
+```
+
+## Getting started
+
+To use eno in your code just require it:
+
+```ruby
+require 'eno'
+```
+
+Alternatively, you can import it using [Modulation](https://github.com/digital-fabric/modulation):
+
+```ruby
+Eno = import('eno')
+```
+
+## Putting together queries
+
+Eno makes it easy to compose SQL queries using plain Ruby syntax. It takes care
+of formatting table and column identifiers and literals, and allows you to
+compose multiple queries into a single `SELECT` statement.
+
+To compose a query use the `Kernel#Q` method, providing a block in which the
+query is built:
+
+```ruby
+Q {
+  select a, b
+  from c
+}
+```
+
+To turn the query into SQL, use the `#to_sql` method:
+
+```ruby
+Q {
+  select a, b
+  from c
+}.to_sql #=> "select a, b from c"
+```
+
+## Using expressions
+
+Once inside the query block, you can build arbitrarily complex expressions. You
+can mix logical and arithmetic operators:
+
+```ruby
+Q { select (a + b) & (c * d) }.to_sql #=> select (a + b) and (c * d)
+```
+
+You can also use SQL functions:
+
+```ruby
+Q {
+  select user_id, max(score)
+  from exams
+  group_by user_id
+}
+```
+
+## Hooking up Eno to your database
+
+In and of itself, Eno is just an engine for building SQL queries. To actually
+run your queries, you'll need to hook Eno to your database. Here's an example
+of how to open a connection to a PostgreSQL database and then easily issue
+queries to it:
+
+```ruby
+require 'pg'
+
+DB = PG.connect(host: '/tmp', dbname: 'myapp', user: 'myuser')
+def DB.q(**ctx, &block)
+  query(**ctx, &block).to_a
+end
+
+# issue a query
+DB.q {
+  from users
+  select 
+}
+```
+
+Another way to issue queries is by defining methods on Eno::Query:
+
+```ruby
+def Eno::Query.each(**ctx, &block)
+  DB.query(to_sql(**ctx)).each(&block)
+end
+```
+
+## Roadmap
+
+Eno is intended as a complete solution for eventually expressing *any* SQL query
+in Ruby (including `INSERT`, `UPDATE` and `DELETE` and `ALTER TABLE`
+statements).
+
+In the future, Eno could be used to manipulate queries in other ways:
+
+- `EXPLAIN` your queries.
+- Introspect different parts of a query (for example look at results of
+  subqueries or CTE's).
+- Transform CTE's into subqueries (for example to overcome optimization
+  boundaries).
+- Create views from queries.
+- Compose data manipulation statements using `SELECT` subqueries.

data/lib/eno.rb

@@ -0,0 +1,486 @@
+# frozen_string_literal: true
+
+require 'modulation/gem'
+
+export :Query, :SQL, :Expression, :Identifier, :Alias
+
+module ::Kernel
+  def Q(**ctx, &block)
+    Query.new(**ctx, &block)
+  end
+end
+
+class Expression
+  def self.quote(expr)
+    case expr
+    when Query
+      "(#{expr.to_sql.strip})"
+    when Expression
+      expr.to_sql
+    when Symbol
+      expr.to_s
+    when String
+      "'#{expr}'"
+    else
+      expr.inspect
+    end
+  end
+
+  attr_reader :members, :props
+
+  def initialize(*members, **props)
+    @members = members
+    @props = props
+  end
+
+  def as(sym = nil, &block)
+    if sym
+      Alias.new(self, sym)
+    else
+      Alias.new(self, Query.new(&block))
+    end
+  end
+
+  def desc
+    Desc.new(self)
+  end
+
+  def over(sym = nil, &block)
+    Over.new(self, sym || WindowExpression.new(&block))
+  end
+
+  def ==(expr2)
+    Operator.new('=', self, expr2)
+  end
+
+  def !=(expr2)
+    Operator.new('<>', self, expr2)
+  end
+
+  def <(expr2)
+    Operator.new('<', self, expr2)
+  end
+
+  def >(expr2)
+    Operator.new('>', self, expr2)
+  end
+
+  def <=(expr2)
+    Operator.new('<=', self, expr2)
+  end
+
+  def >=(expr2)
+    Operator.new('>=', self, expr2)
+  end
+
+  def &(expr2)
+    Operator.new('and', self, expr2)
+  end
+
+  def |(expr2)
+    Operator.new('or', self, expr2)
+  end
+
+  def +(expr2)
+    Operator.new('+', self, expr2)
+  end
+
+  def -(expr2)
+    Operator.new('-', self, expr2)
+  end
+
+  def *(expr2)
+    Operator.new('*', self, expr2)
+  end
+
+  def /(expr2)
+    Operator.new('/', self, expr2)
+  end
+
+  def %(expr2)
+    Operator.new('%', self, expr2)
+  end
+
+  # not
+  def !@
+    Not.new(self)
+  end
+  
+  def null?
+    IsNull.new(self)
+  end
+
+  def not_null?
+    IsNotNull.new(self)
+  end
+
+  def join(sym, **props)
+    Join.new(self, sym, **props)
+  end
+
+  def inner_join(sym, **props)
+    join(sym, props.merge(type: :inner))
+  end
+end
+
+class Operator < Expression
+  def initialize(*members, **props)
+    op = members[0]
+    if Operator === members[1] && op == members[1].op
+      members = [op] + members[1].members[1..-1] + members[2..-1]
+    end
+    if Operator === members[2] && op == members[2].op
+      members = members[0..1] + members[2].members[1..-1]
+    end
+
+    super(*members, **props)
+  end
+
+  def op
+    @members[0]
+  end
+
+  def to_sql
+    op = " #{@members[0]} "
+    "(%s)" % @members[1..-1].map { |m| Expression.quote(m) }.join(op)
+  end
+end
+
+class Desc < Expression
+  def to_sql
+    "#{Expression.quote(@members[0])} desc"
+  end
+end
+
+class Over < Expression
+  def to_sql
+    "#{Expression.quote(@members[0])} over #{Expression.quote(@members[1])}"
+  end
+end
+
+class Not < Expression
+  def to_sql
+    "(not #{Expression.quote(@members[0])})"
+  end
+end
+
+class IsNull < Expression
+  def to_sql
+    "(#{Expression.quote(@members[0])} is null)"
+  end
+
+  def !@
+    IsNotNull.new(members[0])
+  end
+end
+
+class IsNotNull < Expression
+  def to_sql
+    "(#{Expression.quote(@members[0])} is not null)"
+  end
+end
+
+class WindowExpression < Expression
+  def initialize(&block)
+    instance_eval(&block)
+  end
+
+  def partition_by(*args)
+    @partition_by = args
+  end
+
+  def order_by(*args)
+    @order_by = args
+  end
+
+  def range_unbounded
+    @range = 'between unbounded preceding and unbounded following'
+  end
+
+  def to_sql
+    "(%s)" % [
+      _partition_by_clause,
+      _order_by_clause,
+      _range_clause
+    ].join.strip
+  end
+
+  def _partition_by_clause
+    return nil unless @partition_by
+    "partition by %s " % @partition_by.map { |e| Expression.quote(e) }.join(', ')
+  end
+
+  def _order_by_clause
+    return nil unless @order_by
+    "order by %s " % @order_by.map { |e| Expression.quote(e) }.join(', ')
+  end
+
+  def _range_clause
+    return nil unless @range
+    "range #{@range} "
+  end
+
+  def method_missing(sym)
+    super if sym == :to_hash
+    Identifier.new(sym)
+  end
+end
+
+class QuotedExpression < Expression
+  def to_sql
+    Expression.quote(@members[0])
+  end
+end
+
+class Identifier < Expression
+  def to_sql
+    @members[0].to_s
+  end
+
+  def method_missing(sym)
+    super if sym == :to_hash
+    Identifier.new("#{@members[0]}.#{sym}")
+  end
+
+  def _empty_placeholder?
+    m = @members[0]
+    Symbol === m && m == :_
+  end
+end
+
+class Alias < Expression
+  def to_sql
+    "#{Expression.quote(@members[0])} as #{Expression.quote(@members[1])}"
+  end
+end
+
+class FunctionCall < Expression
+  def to_sql
+    fun = @members[0]
+    if @members.size == 2 && Identifier === @members.last && @members.last._empty_placeholder?
+      "#{fun}()"
+    else
+      "#{fun}(#{@members[1..-1].map { |a| Expression.quote(a) }.join(', ')})"
+    end
+  end
+end
+
+class Join < Expression
+  H_JOIN_TYPES = {
+    nil:    'join',
+    inner:  'inner join',
+    outer:  'outer join'
+  }
+
+  def to_sql
+    ("%s %s %s %s" % [
+      Expression.quote(@members[0]),
+      H_JOIN_TYPES[@props[:type]],
+      Expression.quote(@members[1]),
+      condition_sql
+    ]).strip
+  end
+
+  def condition_sql
+    if @props[:on]
+      'on %s' % Expression.quote(@props[:on])
+    elsif using_fields = @props[:using]
+      fields = using_fields.is_a?(Array) ? using_fields : [using_fields]
+      'using (%s)' % fields.map { |f| Expression.quote(f) }.join(', ')
+    else
+      nil
+    end
+  end
+end
+
+class From < Expression
+  def to_sql
+    "from %s" % @members.map { |m| member_sql(m) }.join(', ')
+  end
+
+  def member_sql(member)
+    if Query === member
+      "%s t1" % Expression.quote(member)
+    elsif Alias === member && Query === member.members[0]
+      "%s %s" % [Expression.quote(member.members[0]), Expression.quote(member.members[1])]
+    else
+      Expression.quote(member)
+    end
+  end
+end
+
+class With < Expression
+  def to_sql
+    "with %s" % @members.map { |e| Expression.quote(e) }.join(', ')
+  end
+end
+
+class Select < Expression
+  def to_sql
+    "select %s%s" % [distinct_clause, @members.map { |e| Expression.quote(e) }.join(', ')]
+  end
+
+  def distinct_clause
+    case (on = @props[:distinct])
+    when nil
+      nil
+    when true
+      "distinct "
+    when Array
+      "distinct on (%s) "  % on.map { |e| Expression.quote(e) }.join(', ')
+    else
+      "distinct on %s "  % Expression.quote(on)
+    end
+  end
+end
+
+class Where < Expression
+  def to_sql
+    "where %s" % @members.map { |e| Expression.quote(e) }.join(' and ')
+  end
+end
+
+class Window < Expression
+  def initialize(sym, &block)
+    super(sym)
+    @block = block
+  end
+
+  def to_sql
+    "window %s as %s" % [
+      Expression.quote(@members.first),
+      WindowExpression.new(&@block).to_sql
+    ]
+  end
+end
+
+class OrderBy < Expression
+  def to_sql
+    "order by %s" % @members.map { |e| Expression.quote(e) }.join(', ')
+  end
+end
+
+class Limit < Expression
+  def to_sql
+    "limit %d" % @members[0]
+  end
+end
+
+class Query
+  def initialize(**ctx, &block)
+    @ctx = ctx
+    @block = block
+  end
+
+  def to_sql(**ctx)
+    r = SQL.new(@ctx.merge(ctx))
+    r.to_sql(&@block)
+  end
+
+  def as(sym)
+    Alias.new(self, sym)
+  end
+
+  def where(&block)
+    old_block = @block
+    Query.new(@ctx) {
+      instance_eval(&old_block)
+      where instance_eval(&block)
+    }
+  end
+
+  def mutate(&block)
+    old_block = @block
+    Query.new(@ctx) {
+      instance_eval(&old_block)
+      instance_eval(&block)
+    }
+  end
+end
+
+class SQL
+  def initialize(ctx)
+    @ctx = ctx
+  end
+
+  def to_sql(&block)
+    instance_eval(&block)
+    [
+      @with,
+      @select || default_select,
+      @from,
+      @where,
+      @window,
+      @order_by,
+      @limit
+    ].compact.map { |c| c.to_sql }.join(' ')
+  end
+
+  def _q(expr)
+    QuotedExpression.new(expr)
+  end
+
+  def default_select
+    Select.new(:*)
+  end
+
+  def method_missing(sym, *args)
+    if @ctx.has_key?(sym)
+      value = @ctx[sym]
+      return Symbol === value ? Identifier.new(value) : value
+    end
+    
+    super if sym == :to_hash
+    if args.empty?
+      Identifier.new(sym)
+    else
+      FunctionCall.new(sym, *args)
+    end
+  end
+
+  def with(*members, **props)
+    @with = With.new(*members, **props)
+  end
+
+  H_EMPTY = {}.freeze
+
+  def select(*members, **props)
+    if members.empty? && !props.empty?
+      members = props.map { |k, v| Alias.new(v, k) }
+      props = {}
+    end
+    @select = Select.new(*members, **props)
+  end
+
+  def from(*members, **props)
+    @from = From.new(*members, **props)
+  end
+
+  def where(expr)
+    if @where
+      @where.members << expr
+    else
+      @where = Where.new(expr)
+    end
+  end
+
+  def window(sym, &block)
+    @window = Window.new(sym, &block)
+  end
+
+  def order_by(*members, **props)
+    @order_by = OrderBy.new(*members, **props)
+  end
+
+  def limit(*members)
+    @limit = Limit.new(*members)
+  end
+
+  def all(sym = nil)
+    if sym
+      Identifier.new("#{sym}.*")
+    else
+      Identifier.new('*')
+    end
+  end
+end

data/lib/eno/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Eno
+  VERSION = '0.4'
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: eno
+version: !ruby/object:Gem::Version
+  version: '0.4'
+platform: ruby
+authors:
+- Sharon Rosner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-01-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: modulation
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '0.18'
+description: 
+email: ciconia@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- CHANGELOG.md
+- README.md
+- lib/eno.rb
+- lib/eno/version.rb
+homepage: http://github.com/digital-fabric/eno
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/digital-fabric/eno
+post_install_message: 
+rdoc_options:
+- "--title"
+- eno
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.1
+signing_key: 
+specification_version: 4
+summary: 'Eno: Eno is Not an ORM'
+test_files: []