gamera 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7007ce468ed9467af78521e0e36a52dab78663fc
+  data.tar.gz: 31c9a98bd54d7444bcafc59cd800624f7cdb4146
+SHA512:
+  metadata.gz: eab144b8457ab116a3d956cf31bdcbb871ec35bfcb1a273892d62b0c21c1a54973614f0b3fe1d562f4e3eb87125a684604669d33a2e291ab63ed0ec71eca38bb
+  data.tar.gz: 20d1199ef3b546c9b7030b92f723a7efc28e11dfc17c219c1f5439643070efae0c91ab04c73968440112ae773cfef29ee5a4021adf98e9b59495e2e753d6b576

data/lib/gamera.rb

@@ -0,0 +1,9 @@
+require_relative 'gamera/builder'
+require_relative 'gamera/builders/sequel_fixture_builder'
+require_relative 'gamera/exceptions'
+require_relative 'gamera/page'
+
+require_relative 'gamera/page_sections/form'
+require_relative 'gamera/page_sections/table'
+
+require_relative 'gamera/utils/database_cleaner'

data/lib/gamera/builder.rb

@@ -0,0 +1,244 @@
+# encoding:utf-8
+#--
+# The MIT License (MIT)
+#
+# Copyright (c) 2015, The Gamera Development Team. See the COPYRIGHT file at
+# the top-level directory of this distribution and at
+# http://github.com/gamera-team/gamera/COPYRIGHT.
+#
+# 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.
+#++
+
+require 'forwardable'
+
+module Gamera
+  # Builders provide a generic, standard interface for creating/setting
+  # data in an app.
+  #
+  # For easy creation of a builder use the +with_options()+ class
+  # builder method. For example:
+  #
+  #     class UserBuilder < Builder.with_options(:name, :bday, :nickname)
+  #       def build
+  #         User.create!(name: name, bday: bday, nickname: nickname)
+  #       end
+  #     end
+  #
+  # The created builder will automatically have methods to set each of the
+  # options. In the example above the +UserBuilder#with_nickname+ method
+  # will return a new +UserBuilder+ that has the specified nickname.
+  #
+  #     UserBuilder.new
+  #       .with_nickname("shorty")
+  #       .result
+  #       #=> User(name: nil, bday: nil, nickname: "shorty")
+  #
+  # Sometimes the way you refer to values inside the builder may be
+  # different than how clients do. In that case, builders can define
+  # setter methods that use terminology that matches the client's point
+  # of view.
+  #
+  #     class UserBuilder < Builder.with_options(:name, :bday)
+  #       def born_on(a_date)
+  #         refine_with bday: a_date
+  #       end
+  #     end
+  #
+  # Default values can be specified using the +default_for+ class
+  # method.
+  #
+  #     class UserBuilder < Builder.with_options(:name, :bday)
+  #       default_for :name, "Jane"
+  #       default_for :bday { Time.now }
+  #     end
+  #
+  # You can handle type conversions using coercion methods.
+  #
+  #     class UserBuilder < Builder.with_options(:name, :bday)
+  #       def name_coercion(new_name)
+  #         new_name ? new_name.to_s : "Bob"
+  #       end
+  #     end
+  #
+  # To use this builder:
+  #
+  #    UserBuilder.new
+  #      .born_on(25.years.ago)
+  #      .result
+  #    #=> User(name: "Bob", bday: #<Date: Sat, 09 Dec 1989>)
+  #
+  # or
+  #
+  #    UserBuilder.new
+  #      .with_bday(25.years.ago)
+  #      .result
+  #    #=> User(name: "Bob", bday: #<Date: Sat, 09 Dec 1989>)
+  #
+  # or
+  #
+  #    UserBuilder.new(bday: 25.years.ago)
+  #      .result
+  #    #=> User(name: "Bob", bday: #<Date: Sat, 09 Dec 1989>)
+  class Builder
+    extend Forwardable
+
+    # One way to create builders.
+    #
+    #    b = Builder.create_with(name: "Bob", bday: 25.years.ago) do
+    #      User.create!(name: name, bday: bday)
+    #    end
+    #
+    #    b.build
+    #    #=> User(name: "Bob", bday: #<Date: Sat, 09 Dec 1989>)
+    def self.create_with(spec, &block)
+      struct = Struct.new(*(spec.keys)) do
+        def initialize(options = {})
+          super
+          options.each { |opt, value| self[opt] = value }
+        end
+
+        def with(options, &block)
+          new_struct = dup
+          options.each { |opt, value| new_struct[opt] = value }
+          if block_given?
+            new_struct.class.class_eval do
+              define_method :build, &block
+            end
+          end
+          new_struct
+        end
+
+        members.each do |opt|
+          define_method "with_#{opt}" do |value, &inner_block|
+            with(opt => value, &inner_block)
+          end
+        end
+
+        define_method :build, &block
+      end
+
+      struct.new spec
+    end
+
+    # Module to extend the Builder DSL
+    module Dsl
+      # Sets the default value of an option
+      #
+      # @param option_name [String] Name of the builder option
+      # @param val [Object] the simple default value of the option
+      # @param gen [Block] block that returns default values
+      #
+      # Yields self to block (+gen+) if a block is provided. Return
+      # value will be the default value.
+      def default_for(option_name, val = nil, &gen)
+        gen ||= ->(_) { val }
+
+        prepend(Module.new do
+          define_method :"#{option_name}_coercion" do |v|
+            super v.nil? ? gen.call(self) : v
+          end
+        end)
+      end
+    end
+
+    extend Dsl
+
+    # Another way to create builders.
+    #
+    # For easy creation of a builder use the +with_options()+ class
+    # builder method. For example:
+    #
+    #     class UserBuilder < Builder.with_options(:name, :bday, :nickname)
+    #       def build
+    #         User.create!(name: name, bday: bday, nickname: nickname)
+    #       end
+    #     end
+    #
+    # The created builder will automatically have methods to set each of the
+    # options. In the example above the +UserBuilder#with_nickname+ method
+    # will return a new +UserBuilder+ that has the specified nickname.
+    #
+    #     UserBuilder.new
+    #       .with_nickname("shorty")
+    #       .result
+    #       #=> User(name: nil, bday: nil, nickname: "shorty")
+    #
+    def self.with_options(*option_names)
+      init_arg_list = option_names.map { |o| "#{o}: nil" }.join(', ')
+      args_to_ivars = option_names.map { |o| "@#{o} = #{o}_coercion(#{o})" }.join('; ')
+
+      Class.new(self) do
+        module_eval <<-METH
+        def initialize(#{init_arg_list})  # def initialize(tags: nil, name: nil)
+        #{args_to_ivars}                #   @tags = tags_coercion(tags); @name = name_coercion(name)
+                       super()                         #   super()
+        end                               # end
+        METH
+
+        # +with_...+ methods
+        option_names.each do |name|
+          define_method(:"with_#{name}") do |new_val, *extra|
+            val = if extra.any?
+                    # called with multiple params, eg (p1,p2,p3,...), so
+                    # package those as an array and pass them in
+                    [new_val] + extra
+                  else
+                    # called with single param
+                    new_val
+                  end
+
+            refine_with(name => val)
+          end
+        end
+
+        protected
+
+        attr_reader(*option_names)
+
+        define_method(:options) do
+          Hash[option_names.map { |o| [o, send(o)] }]
+        end
+
+        option_names.each do |o_name|
+          define_method(:"#{o_name}_coercion") { |new_val| new_val }
+        end
+      end
+    end
+
+    # The object built by this builder
+    def result
+      @result ||= build
+    end
+
+    # Executes the builder
+    #
+    # @note Don't call this method directly, use +#result+ instead.
+    def build
+      fail NotImplementedError
+    end
+
+    def_delegator :self, :build, :call
+
+    # Returns a clone of this object but with options listed in
+    # +alterations+ updated to match.
+    def refine_with(alterations)
+      self.class.new options.merge(alterations)
+    end
+  end
+end

data/lib/gamera/builders/sequel_fixture_builder.rb

@@ -0,0 +1,249 @@
+# encoding:utf-8
+#--
+# The MIT License (MIT)
+#
+# Copyright (c) 2015, The Gamera Development Team. See the COPYRIGHT file at
+# the top-level directory of this distribution and at
+# http://github.com/gamera-team/gamera/COPYRIGHT.
+#
+# 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.
+#++
+
+require 'yaml'
+require 'sequel'
+require 'sequel-fixture'
+
+module Gamera
+  module Builders
+    # A builder for loading YAML fixtures using a Sequel DB connection.
+    #
+    # Usage:
+    #
+    #   Gamera::Builders::SequelFixtureBuilder.new(
+    #     database_config:          "/path/to/database.yml",
+    #     fixture_directory:        "/path/to/fixtures/",
+    #     database_cleaner_options: { skip: false, tables: ['users', 'messages'] }
+    #   ).build
+    #
+    # Or:
+    #
+    #   Gamera::Builders::SequelFixtureBuilder.new.
+    #     with_database_config("/path/to/database.yml").
+    #     with_fixture_directory("/path/to/fixtures/").
+    #     with_database_cleaner_options({ skip: false, tables: ['users', 'messages'] }).
+    #     build
+    #
+    # Defaults:
+    #   database_config:    ./config/database.yml
+    #   fixture_directory:  ./spec/fixtures/ or ./test/fixtures/
+    #   database_cleaner_options:
+    #     skip:   false
+    #     tables: (all tables in the database)
+    #
+    # So if you follow these defaults, you can simply do:
+    #
+    #   Gamera::Builders::SequelFixtureBuilder.new.build
+    class SequelFixtureBuilder < Gamera::Builder.with_options(:database_config, :fixture_directory, :database_cleaner_options)
+      DEFAULT_DATABASE_CONFIG        = './config/database.yml'
+      DEFAULT_SPEC_FIXTURE_DIRECTORY = './spec/fixtures'
+      DEFAULT_TEST_FIXTURE_DIRECTORY = './test/fixtures'
+
+      # Truncates the database and imports the fixtures.
+      # Returns a +Sequel::Fixture+ object, containing
+      # hashes of all the fixtures by table name
+      # (https://github.com/whitepages/sequel-fixture).
+      def build
+        # Truncate all tables
+        unless skip_database_cleaner
+          cleaner = Utils::DatabaseCleaner.new(db, database_cleaner_tables)
+          cleaner.clean
+        end
+
+        fixture_path, fixture_dir = File.split(path_to_fixtures)
+
+        Sequel::Fixture.path = fixture_path
+
+        Sequel::Fixture.new(fixture_dir.to_sym, db)
+      end
+
+      # The +Sequel+ database connection.
+      # Raises +Gamera::DatabaseNotConfigured+ if it fails
+      # to initialize the database from the given config
+      # or defaults.
+      def db
+        @db ||= self.class.db(database_config)
+      end
+
+      # Finds the full path to the fixtures directory.
+      # Uses the given +fixture_directory+ if given.
+      # Otherwise tries to use ./spec/fixtures or ./test/fixtures.
+      #
+      # Raises +Gamera::DatabaseNotConfigured+ if it cannot find
+      def path_to_fixtures
+        @path_to_fixtures ||= begin
+          if fixture_directory && !fixture_directory.empty?
+            unless File.exist?(fixture_directory)
+              fail DatabaseNotConfigured, "Invalid fixture directory #{fixture_directory}"
+            end
+            fixture_directory
+          elsif File.exist?(DEFAULT_SPEC_FIXTURE_DIRECTORY)
+            DEFAULT_SPEC_FIXTURE_DIRECTORY
+          elsif File.exist?(DEFAULT_TEST_FIXTURE_DIRECTORY)
+            DEFAULT_TEST_FIXTURE_DIRECTORY
+          else
+            fail DatabaseNotConfigured, 'Unable to find fixtures to load'
+          end
+        end
+      end
+
+      private
+
+      # The cache of +Sequel+ database connections by database config.
+      # Raises +Gamera::DatabaseNotConfigured+ if it fails to initialize
+      # the database from the given config
+      def self.db(database_config)
+        @db ||= {}
+        @db[database_config || DEFAULT_DATABASE_CONFIG] ||= begin
+          config = database_config_from_file(database_config) || database_config_from_hash(database_config) || database_config_from_default
+          if config
+            Sequel.connect(config)
+          else
+            fail DatabaseNotConfigured, 'Unable to connect to database'
+          end
+        end
+      end
+
+      # Attempts to load database config by interpretting the given
+      # config as a string path to a YAML config file.
+      #
+      # Can accept a file with top-level keys matching environments,
+      # like those found in Rails database.yml files,
+      # in which case, it chooses the 'test' environment.
+      #
+      # Alternatively, it can accept a file with top-level keys matching
+      # the database config keys.
+      #
+      # Database config keys are:
+      # => adapter
+      # => database
+      # => username
+      # => password (optional)
+      # => host (optional)
+      #
+      # Returns hash containing the database config options
+      # if possible, and nil if not.
+      def self.database_config_from_file(config = nil)
+        return nil unless config.is_a?(String) && File.exist?(config)
+
+        db_config = YAML.load_file(config) rescue nil
+        return nil unless db_config
+
+        database_config_from_hash(db_config)
+      end
+
+      # Attempts to load database config by interpretting the given
+      # config as a hash with the config options.
+      #
+      # Can accept a hash with top-level keys matching environments,
+      # like those found in Rails database.yml files,
+      # in which case, it chooses the 'test' or :test environment.
+      #
+      # Alternatively, it can accept a hash with top-level keys matching
+      # the database config keys.
+      #
+      # Database config keys are:
+      # => adapter
+      # => database
+      # => username
+      # => password (optional)
+      # => host (optional)
+      #
+      # Returns hash containing the database config options
+      # if possible, and nil if not.
+      def self.database_config_from_hash(config = nil)
+        return nil unless config.is_a?(Hash)
+
+        db_config = if config.key?('test')
+                      config['test']
+                    elsif config.key?(:test)
+                      config[:test]
+                    else
+                      config
+                    end
+
+        verify_database_config(db_config)
+
+        db_config
+      end
+
+      # Attempts to load the database config from the default
+      # location of ./config/database.yml if the file exists.
+      #
+      # Delegates to #database_config_from_file
+      def self.database_config_from_default
+        database_config_from_file(DEFAULT_DATABASE_CONFIG)
+      end
+
+      # Given a hash, confirms all required DB config fields are
+      # present. Otherwise raises +Gamera::DatabaseNotConfigured+.
+      #
+      # Required fields (string or symbol):
+      # => adapter
+      # => database
+      # => username
+      def self.verify_database_config(db_config)
+        db_config ||= {}
+        missing_fields = [:adapter, :database, :username].reject do |field|
+          db_config.key?(field) || db_config.key?(field.to_s)
+        end
+        unless missing_fields.empty?
+          fail DatabaseNotConfigured, "Unable to connect to database: Missing config for #{missing_fields.join(', ')}"
+        end
+      end
+
+      # Boolean from database_cleaner_options.
+      # Defaults to +false+ if not set.
+      def skip_database_cleaner
+        database_cleaner_option(:skip, false)
+      end
+
+      # Array of table names from database_cleaner_options.
+      # Defaults to +nil+, which is interpretted as "all tables".
+      def database_cleaner_tables
+        database_cleaner_option(:tables, nil)
+      end
+
+      # Retrieves options from the +database_cleaner_options+
+      # hash, returning the given +default+ if the
+      # database_cleaner_options don't exist, or the given
+      # key (as a symbol or string) isn't set.
+      def database_cleaner_option(symbol, default)
+        options = database_cleaner_options || {}
+
+        if options.key?(symbol)
+          options[symbol]
+        elsif options.key?(symbol.to_s)
+          options[symbol.to_s]
+        else
+          default
+        end
+      end
+    end
+  end
+end