hsql 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 810e7d83e6fe91c3977b1c9e6cbedb33bcc9e4b3
-  data.tar.gz: b6a8e21fe109d511e326bd451cdbc6863a664a99
+  metadata.gz: ad536a4589ef6fd47d79acfbbdefe48e99515cb5
+  data.tar.gz: d8d754d2e5e6284be8273edb111ebeeee17ad402
 SHA512:
-  metadata.gz: 635ffcf8efbd6827af5aa18b819a99f7e944cab8eaa9677d65c8c35e874ae7304394b164bda7092e16d7bcfda71b08ac5ad2db4eb6680ae28f8cd94e17b39c5a
-  data.tar.gz: e64eae6f4c2064db51985b561ff103ed339f79e665f3bb4ef43f3b9163fd009ac72c26eb671f67ac86b95f53fb94d34467efda1c9a6d208c9fd23ae5ff05724a
+  metadata.gz: 4e81cd7ba8c73332637181929b64e50d91398402bd391e22fba68afd12f0fa662a128dcb34de0ec26945b6384e02be7f7851fbe967926389dd3adb16358ada34
+  data.tar.gz: 08f0d9f2a3a1ec99f99e6cfc32c53fd0be8710075f21b3d227d99fb57dfc8f4a5b50270fda18167e6865bdbe3fd4dd56029a735b99ca885eb17f45ff063d0c6b

data/.rubocop.yml

@@ -0,0 +1,14 @@
+
+Style/TrailingComma:
+  EnforcedStyleForMultiline: comma
+
+Metrics/LineLength:
+  Max: 110
+
+StructInheritance:
+  Enabled: false
+
+# `module_function` is strictly worse than `extend self` due to the confusion
+# `module_function` introduces by not copying private methods to the class.
+Style/ModuleFunction:
+  Enabled: false

data/.travis.yml

@@ -1,4 +1,6 @@
 language: ruby
 rvm:
+  - 2.0.0
   - 2.2.1
+script: bundle exec rake
 before_install: gem install bundler -v 1.10.5

data/README.md

@@ -13,19 +13,21 @@ Rather than specifying variables and metadata for a set of database
 queries in a `.rb`,`.py` or other programming language source file the queries
 should be written to a .sql file directly.
 
-        # filename: daily_summary.sql
-        owner: jackdanger
-        schedule: hourly
-        data:
-          production:
-            output_table: summaries
-            update_condition:
-          development:
-            output_table: jackdanger_summaries
-            update_condition: WHERE 1 <> 1
-        ---
-        INSERT INTO {{{output_table}}} SELECT * FROM interesting_information;
-        UPDATE summaries_performed SET complete = 1 {{{update_condition}}};
+```sql
+# filename: daily_summary.sql
+owner: jackdanger
+schedule: hourly
+data:
+  production:
+    output_table: summaries
+    update_condition:
+  development:
+    output_table: jackdanger_summaries
+    update_condition: WHERE 1 <> 1
+---
+INSERT INTO {{{output_table}}} SELECT * FROM interesting_information;
+UPDATE summaries_performed SET complete = 1 {{{update_condition}}};
+```
 
 The above is a SQL file and any text editor will allow analysts to use
 code completion and syntax highlighting for their queries.

data/Rakefile

@@ -1,6 +1,10 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
 
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new
+RuboCop::RakeTask.new
 
-task default: :spec
+task default: [:lint, :spec]
+task test: :spec
+task lint: :rubocop

data/bin/hsql

@@ -3,34 +3,72 @@
 require 'optparse'
 require 'yaml'
 require 'json'
+require 'active_support/time'
 
 options = {}
 option_parser = OptionParser.new do |opts|
   opts.banner = <<-BANNER
-USAGE: #{__FILE__} file environment [--yaml]
+Usage: #{__FILE__} file [environment] [--yaml]
 
-file:        Any *.sql file that has a YAML header ending in three hyphens.
-environment: Must be one of the keys of the "data" hash in the YAML header of the .sql file.
---yaml:      Outputs only the YAML metadata from the file, not the SQL queries themselves.
+ARGUMENTS
+  file: Any *.sql file that has a YAML header ending in three hyphens.
 
-for details, run:
-  open https://github.com/JackDanger/hsql
+OPTIONS
 BANNER
 
-  opts.on('-y', '--yaml', 'Output metadata for this file as YAML') do |option|
+  opts.on('-d DATE',
+          '--date DATE',
+          '--timestamp DATE', 'The time that the SQL will consider to be "now".') do |option|
+    options[:timestamp] = Time.parse(option) if option
+  end
+  opts.on('-e ENV',
+          '--env ENV',
+          'Which key of the YAML header "data:" key you want to interpolate.') do |option|
+    options[:environment] = option
+  end
+  opts.on('-y', '--yaml', 'Output just the metadata for this file as YAML') do |_option|
     options[:meta_only] = 'yaml'
   end
-  opts.on('-j', '--json', 'Output metadata for this file as JSON') do |option|
+  opts.on('-j', '--json', 'Output just the metadata for this file as JSON') do |_option|
     options[:meta_only] = 'json'
   end
-end
+  opts.on_tail('-v', '--version', 'Show the current version of HSQL') do |_option|
+    puts HSQL::VERSION
+    exit 1
+  end
+  opts.on('-h', '--help', 'Show the full help documentation') do |_option|
+    require_relative '../lib/hsql/data'
+    <<-HELP
+TEMPLATE
+
+You can use the Mustache syntax (three curly braces) to interpolate any of your
+'data' into your SQL. You specify the data in the YAML header like so:
+
+    data:
+      production:     # whatever you want to be interpolated into your SQL
+        name: Alison  # when you pass 'production' as the environment argument
+      development:
+        name: Kailey
+    ---
+    SELECT * FROM users WHERE name = '{{{name}}}'
 
+
+There are some common date values available to you at all times, without having
+to be defined in the YAML header:
+
+#{HSQL::Data.for_humans}
+
+For more details, run:
+  open https://github.com/JackDanger/hsql
+HELP
+  end
+end
 option_parser.parse!
 
-filename, env = ARGV
+filename = ARGV.first
 
-unless filename && env
-  puts option_parser.banner
+unless filename
+  puts option_parser
   exit 1
 end
 
@@ -43,7 +81,7 @@ end
 
 require_relative '../lib/hsql'
 
-file = HSQL.parse_file(file, env)
+file = HSQL::File.parse_file(file, options)
 if 'yaml' == options[:meta_only]
   puts file.metadata.to_yaml
 elsif 'json' == options[:meta_only]

data/examples/date_math.sql

@@ -0,0 +1,69 @@
+/*
+Demonstrating use of the builtin time and date variables.
+No YAML front matter was necessary for this file to work.
+
+To see all possible variables you can use run:
+
+    $ hsql --help
+
+To see yourself how this file works run:
+
+    $ hsql examples/date_math.sql
+
+To change the values of the times just pass a --date or --timestamp argument:
+
+    $ hsql examples/date_math.sql --timestamp '1986-01-12 17:12:00'
+
+*/
+
+SELECT * FROM users WHERE created_at = {{{now}}};
+/* Becomes:
+SELECT * FROM users WHERE created_at = '2015-08-19 21:13:82 -0700' */
+
+SELECT * FROM users WHERE created_at BETWEEN {{{beginning_of_hour}}} AND {{{end_of_hour}}};
+/* Becomes:
+SELECT * FROM users WHERE created_at >= '2015-08-19 21:00:00 -0700' AND created_at <= '2015-08-19 21:59:59 -0700' */
+
+SELECT * FROM users WHERE created_at BETWEEN {{{beginning_of_previous_hour}}} AND {{{end_of_previous_hour}}};
+/* Becomes:
+SELECT * FROM users WHERE created_at >= '2015-08-19 20:00:00 -0700' AND created_at <= '2015-08-19 20:59:59 -0700' */
+
+SELECT * FROM users WHERE created_at BETWEEN {{{beginning_of_day}}} AND {{{end_of_day}}};
+/* Becomes:
+SELECT * FROM users WHERE created_at >= '2015-08-19 00:00:00 -0700' AND created_at <= '2015-08-19 23:59:59 -0700' */
+
+SELECT * FROM users WHERE created_at BETWEEN {{{beginning_of_previous_day}}} AND {{{end_of_previous_day}}};
+/* Becomes:
+SELECT * FROM users WHERE created_at >= '2015-08-18 00:00:00 -0700' AND created_at <= '2015-08-18 23:59:59 -0700' */
+
+SELECT * FROM users WHERE created_at BETWEEN {{{beginning_of_week}}} AND {{{end_of_week}}};
+/* Becomes:
+SELECT * FROM users WHERE created_at >= '2015-08-17 00:00:00 -0700' AND created_at <= '2015-08-23 23:59:59 -0700' */
+
+SELECT * FROM users WHERE created_at BETWEEN {{{beginning_of_previous_week}}} AND {{{end_of_previous_week}}};
+/* Becomes:
+SELECT * FROM users WHERE created_at >= '2015-08-10 00:00:00 -0700' AND created_at <= '2015-08-16 23:59:59 -0700' */
+
+SELECT * FROM users WHERE created_at BETWEEN {{{beginning_of_month}}} AND {{{end_of_month}}};
+/* Becomes:
+SELECT * FROM users WHERE created_at >= '2015-08-01 00:00:00 -0700' AND created_at <= '2015-08-31 23:59:59 -0700' */
+
+SELECT * FROM users WHERE created_at BETWEEN {{{beginning_of_previous_month}}} AND {{{end_of_previous_month}}};
+/* Becomes:
+SELECT * FROM users WHERE created_at >= '2015-07-01 00:00:00 -0700' AND created_at <= '2015-07-31 23:59:59 -0700' */
+
+SELECT * FROM users WHERE created_at BETWEEN {{{beginning_of_quarter}}} AND {{{end_of_quarter}}};
+/* Becomes:
+SELECT * FROM users WHERE created_at >= '2015-07-01 00:00:00 -0700' AND created_at <= '2015-09-30 23:59:59 -0700' */
+
+SELECT * FROM users WHERE created_at BETWEEN {{{beginning_of_previous_quarter}}} AND {{{end_of_previous_quarter}}};
+/* Becomes:
+SELECT * FROM users WHERE created_at >= '2015-04-01 00:00:00 -0700' AND created_at <= '2015-06-30 23:59:59 -0700' */
+
+SELECT * FROM users WHERE created_at BETWEEN {{{beginning_of_year}}} AND {{{end_of_year}}};
+/* Becomes:
+SELECT * FROM users WHERE created_at >= '2015-01-01 00:00:00 -0800' AND created_at <= '2015-12-31 23:59:59 -0800' */
+
+SELECT * FROM users WHERE created_at BETWEEN {{{beginning_of_previous_year}}} AND {{{end_of_previous_year}}};
+/* Becomes:
+SELECT * FROM users WHERE created_at >= '2014-01-01 00:00:00 -0800' AND created_at <= '2014-12-31 23:59:59 -0800' */

data/hsql.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ['gems@jackcanty.com']
 
   spec.summary       = 'Store a hash of data with your SQL queries.'
-  spec.description   = 'Write SQL queries in a .sql format and ship them with metadata about how they should be executed'
+  spec.description   = 'Write SQL queries with Mustache and easily render them for specific dates/times'
   spec.homepage      = 'https://github.com/JackDanger/hsql'
   spec.license       = 'MIT'
 
@@ -20,10 +20,12 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_dependency 'mustache', '> 0'
+  spec.add_dependency 'activesupport', '> 0'
   #  spec.add_dependency 'pg_query', '>= 0.6.2'
   spec.add_development_dependency 'bundler', '~> 1.10'
   spec.add_development_dependency 'rubocop', '~> 0.3'
   spec.add_development_dependency 'rake', '> 0'
   spec.add_development_dependency 'rspec', '~> 3.3'
+  spec.add_development_dependency 'timecop', '~> 0.8.0'
   spec.add_development_dependency 'pry-byebug', '> 3'
 end

data/lib/hsql/data.rb

@@ -0,0 +1,95 @@
+require 'active_support/time'
+module HSQL
+  # This module provides a set of useful values to be inserted into templates.
+  module Data
+    extend self
+
+    # The internal API for reading this data and inserting it into queries.
+    def for_machines(time)
+      Hash[
+        calendar_moments(time).map { |name, value, _documentation| [name, "'#{value}'"] }
+      ]
+    end
+
+    # For presenting to users the possible template variables they can use.
+    def for_humans
+      values = calendar_moments(Time.current)
+      for_screen = values.map do |name, _, description|
+        ["{{{#{name}}}}", description]
+      end
+      width = for_screen.max_by { |name, _| name.size }.first.size
+
+      for_screen.map do |name, documentation|
+        "    #{name.ljust(width, ' ')} #{documentation}"
+      end.join("\n")
+    end
+
+    private
+
+    # A set of template variables that are always available and defined in
+    # relation to the provided time or date.
+    # The structure is designed to make generating documentation easier.
+    #
+    # rubocop:disable Metrics/LineLength, Metrics/MethodLength, Metrics/AbcSize
+    def calendar_moments(time)
+      # Time ranges surrounding the moment provided.
+      moment = time
+      moments = []
+
+      moments += [
+        ['now', moment, 'The moment provided via --date or --timestamp (defaults to the current system time)'],
+      ]
+
+      moments += [
+        ['beginning_of_hour',    moment.beginning_of_hour,    'The first second of the hour'],
+        ['beginning_of_day',     moment.beginning_of_day,     'The first second of the day'],
+        ['beginning_of_week',    moment.beginning_of_week,    'The first second of the week'],
+        ['beginning_of_month',   moment.beginning_of_month,   'The first second of the month'],
+        ['beginning_of_quarter', moment.beginning_of_quarter, 'The first second of the quarter'],
+        ['beginning_of_year',    moment.beginning_of_year,    'The first second of the year'],
+        ['end_of_hour',          moment.end_of_hour,          'The last second of the hour'],
+        ['end_of_day',           moment.end_of_day,           'The last second of the day'],
+        ['end_of_week',          moment.end_of_week,          'The last second of the week'],
+        ['end_of_month',         moment.end_of_month,         'The last second of the month'],
+        ['end_of_quarter',       moment.end_of_quarter,       'The last second of the quarter'],
+        ['end_of_year',          moment.end_of_year,          'The last second of the year'],
+      ]
+
+      # Time ranges immediately preceding the one in which `time` appears.
+      moment = time - 1.hour
+      moments += [
+        ['beginning_of_previous_hour', moment.beginning_of_hour, 'The first second of the previous hour'],
+        ['end_of_previous_hour',       moment.end_of_hour,       'The last second of the previous hour'],
+      ]
+
+      moment = time - 1.day
+      moments += [
+        ['beginning_of_previous_day',  moment.beginning_of_day, 'The first second of the previous day'],
+        ['end_of_previous_day',        moment.end_of_day,       'The last second of the previous day'],
+      ]
+
+      moment = time - 1.week
+      moments += [
+        ['beginning_of_previous_week',  moment.beginning_of_week, 'The first second of the previous week'],
+        ['end_of_previous_week',        moment.end_of_week,       'The last second of the previous week'],
+      ]
+      moment = time - 1.month
+      moments += [
+        ['beginning_of_previous_month',  moment.beginning_of_month, 'The first second of the previous month'],
+        ['end_of_previous_month',        moment.end_of_month,       'The last second of the previous month'],
+      ]
+      moment = time - 3.months
+      moments += [
+        ['beginning_of_previous_quarter',  moment.beginning_of_quarter, 'The first second of the previous quarter'],
+        ['end_of_previous_quarter',        moment.end_of_quarter,       'The last second of the previous quarter'],
+      ]
+      moment = time - 1.year
+      moments += [
+        ['beginning_of_previous_year',  moment.beginning_of_year, 'The first second of the previous year'],
+        ['end_of_previous_year',        moment.end_of_year,       'The last second of the previous year'],
+      ]
+
+      moments
+    end
+  end
+end

data/lib/hsql/file.rb

@@ -1,12 +1,36 @@
-# HSQL::File parses the input file and provides reader methods to the hash of
-# YAML data from the front matter section and a list of the queries in the SQL
-# portion.
 require 'yaml'
 require_relative 'query'
+require_relative 'data'
 module HSQL
-  class File < Struct.new(:string, :environment)
+  # HSQL::File parses the input file and provides reader methods to the hash of
+  # YAML data from the front matter section and a list of the queries in the SQL
+  # portion.
+  class File
+    attr_reader :string, :timestamp, :environment
+
+    # This is used to indicate when a source file is malformed.
+    class FormatError < StandardError
+    end
+
+    def initialize(string, options)
+      @string = string
+      @timestamp = options.fetch(:timestamp, Time.current)
+      @environment = options[:environment]
+    end
+
+    # Given the contents of a SQL file with YAML front matter (see README for an
+    # example) this will return a HSQL::File object providing access to the parts
+    # of that file.
+    def self.parse(string, options)
+      new(string, options).parse!
+    end
+
+    def self.parse_file(file, options)
+      parse(file.read, options)
+    end
+
     def metadata
-      @metadata ||= ::YAML.load(@front_matter)
+      @metadata ||= @front_matter ? ::YAML.load(@front_matter) : {}
     end
 
     def queries
@@ -23,9 +47,12 @@ module HSQL
 
     def split!
       @split ||= begin
-        @front_matter, divider, @sql = string.partition(/^---$/)
-        unless divider == '---'
-          fail FormatError, 'The YAML front matter is required, otherwise this is just a SQL file'
+        top_half, divider, rest = string.partition(/^---$/)
+        if divider.present?
+          @front_matter = top_half
+          @sql = rest
+        else # No divider found, therefore no YAML header
+          @sql = top_half
         end
         true
       end
@@ -33,20 +60,29 @@ module HSQL
 
     def data
       @data ||= begin
-        if metadata['data']
-          unless metadata['data'].key?(environment)
-            fail ArgumentError, "The environment #{environment.inspect} is not specified"
-          end
-          metadata['data'][environment]
-        end || {}
+        validate_environment_exists!
+
+        hash = metadata['data'] || {}
+        hash = hash[environment] || {} if environment
+        hash.merge(Data.for_machines(timestamp))
       end
     end
 
+    def validate_environment_exists!
+      return unless environment
+      return if metadata['data'].blank? || metadata['data'].key?(environment)
+      fail ArgumentError, "The environment #{environment.inspect} is not specified"
+    end
+
     def interpolate_data!
       template = Template.new(@sql)
       template.variable_names.each do |name|
-        unless data.key?(name)
+        next if data.key?(name)
+
+        if environment
           fail FormatError, "#{name.inspect} is not set in #{environment.inspect} environment"
+        else
+          fail FormatError, "#{name.inspect} is not set! Did you provide the right environment argument?"
         end
       end
 

data/lib/hsql/query.rb

@@ -1,6 +1,6 @@
-# PgQuery uses Postgres' own parser to parse and then deparse each query.
 require 'pg_query'
 module HSQL
+  # PgQuery uses Postgres' own parser to parse and then deparse each query.
   class Query < Struct.new(:ast)
     # Returns a list of queries found in the source SQL
     def self.parse(source)

data/lib/hsql/template.rb

@@ -1,6 +1,15 @@
 require 'mustache'
 module HSQL
-  class Template < Struct.new(:input)
+  # Given some SQL that may contain Mustache tags (e.g. {{{ variable }}} ),
+  # accept a hash of data that interpolates each tag.
+  # Throws an error if one of the tag names can't be found in the data.
+  class Template
+    attr_reader :input
+
+    def initialize(input)
+      @input = input
+    end
+
     def variable_names
       extract_variable_names(ast).uniq
     end
@@ -17,7 +26,7 @@ module HSQL
       if tree[1] == :fetch
         tree.last.first
       else
-        tree.map { |token| extract_variable_names(token) }.compact.flatten
+        tree.map { |token| extract_variable_names(token) }.flatten.compact
       end
     end
 

data/lib/hsql/version.rb

@@ -1,3 +1,4 @@
+# http://semver.org/
 module HSQL
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

data/lib/hsql.rb

@@ -2,22 +2,3 @@ require_relative 'hsql/version'
 require_relative 'hsql/template'
 require_relative 'hsql/file'
 require_relative 'hsql/query'
-require 'mustache'
-
-module HSQL
-  # This is used to indicate when a source file is malformed.
-  class FormatError < StandardError
-  end
-
-  # Given the contents of a SQL file with YAML front matter (see README for an
-  # example) this will return a HSQL::File object providing access to the parts
-  # of that file.
-  def self.parse(string, environment)
-    fail ArgumentError, 'The environment argument is required' unless environment
-    File.new(string, environment).parse!
-  end
-
-  def self.parse_file(file, environment)
-    parse(file.read, environment)
-  end
-end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hsql
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Jack Danger Canty
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-17 00:00:00.000000000 Z
+date: 2015-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mustache
@@ -24,6 +24,20 @@ dependencies:
     - - ">"
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -80,6 +94,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
 - !ruby/object:Gem::Dependency
   name: pry-byebug
   requirement: !ruby/object:Gem::Requirement
@@ -94,8 +122,7 @@ dependencies:
     - - ">"
       - !ruby/object:Gem::Version
         version: '3'
-description: Write SQL queries in a .sql format and ship them with metadata about
-  how they should be executed
+description: Write SQL queries with Mustache and easily render them for specific dates/times
 email:
 - gems@jackcanty.com
 executables:
@@ -105,6 +132,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
 - ".ruby-version"
 - ".travis.yml"
 - CODE_OF_CONDUCT.md
@@ -115,9 +143,11 @@ files:
 - bin/console
 - bin/hsql
 - bin/setup
+- examples/date_math.sql
 - examples/simple.sql
 - hsql.gemspec
 - lib/hsql.rb
+- lib/hsql/data.rb
 - lib/hsql/file.rb
 - lib/hsql/query.rb
 - lib/hsql/template.rb