ocg 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8e9901f2790c6f74257fc4a081df5bbacefb6084fcbd5f1e31c5bf1cd5e69b7f
+  data.tar.gz: 602a5952e6ece5235fd19b469113903cf4a3750043aa35fdfe5091cb865d4903
+SHA512:
+  metadata.gz: 683e94067c89e54ffa979c682d40ef6739c8c3a4d92be87a6250cde5c6981498dde7dc42adddb1f78561303954b4344ca7642b15693c616920e6313f589fcb85
+  data.tar.gz: 10a4f52d299916f8237ccdfa65258a261d1b49811700fc7d73813575a36547aafed3d4ae96686445cc63936b88db90cc3eae7547da335c1589984df9da82fc30

data/AUTHORS

@@ -0,0 +1 @@
+Andrew Aladjev

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 AUTHORS
+
+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.

data/README.md

@@ -0,0 +1,167 @@
+# Option combination generator
+
+[![Travis test status](https://travis-ci.org/andrew-aladev/ocg.svg?branch=master)](https://travis-ci.org/andrew-aladev/ocg)
+[![AppVeyor test status](https://ci.appveyor.com/api/projects/status/github/andrew-aladev/ocg?branch=master&svg=true)](https://ci.appveyor.com/project/andrew-aladev/ocg/branch/master)
+[![Cirrus test status](https://api.cirrus-ci.com/github/andrew-aladev/ocg.svg?branch=master)](https://cirrus-ci.com/github/andrew-aladev/ocg)
+[![Circle test status](https://circleci.com/gh/andrew-aladev/ocg/tree/master.svg?style=shield)](https://circleci.com/gh/andrew-aladev/ocg/tree/master)
+
+## Installation
+
+```sh
+gem install ocg
+```
+
+You can build it from source.
+
+```sh
+rake gem
+gem install pkg/ocg-*.gem
+```
+
+## Usage
+
+```ruby
+require "ocg"
+
+generator = OCG.new(
+  :a => %w[a b],
+  :b => 1..2
+)
+.or(
+  :c => %i[c d],
+  :d => 3..4
+)
+.and(
+  :e => %w[e f],
+  :f => 5..6
+)
+.mix(
+  :g => %i[g h],
+  :h => 7..8
+)
+
+until generator.finished?
+  pp generator.next
+end
+```
+
+It will populate all option combinations.
+
+## Docs
+
+Options should be prepared in the following form:
+
+```ruby
+{
+  option_name => option_values,
+  ...
+}
+```
+
+Options hash should not be empty.
+`option_name` can be any valid hash key.
+`option_values` should be convertable to array using `to_a`.
+`option_values` should not be empty.
+
+`OCG.new options` will prepare a generator.
+It will provide all possible option combinations.
+
+You can combine generators using `and`, `mix` and `or`.
+
+`and` method will provide all combinations between generators.
+`mix` method will merge right generator combinations into left without combining. `mix` guarantees that both left and right generator combinations will be provided at least once.
+`or` method will concat generator combinations without merging.
+
+`reset` method allows to receive combinations once again.
+
+`next` method returns next combination.
+
+`last` method returns last combination.
+
+`started?` method returns true when at least one combination was generated.
+
+`finished?` method returns true when all combination were generated.
+
+`length` returns combinations length.
+
+## Why?
+
+Many software uses multiple options and have complex relations between them.
+We want to test this software.
+We need to provide optimal option combination to maximize test coverage.
+
+Let's look at [zstd compressor options](http://facebook.github.io/zstd/zstd_manual.html#Chapter5).
+
+`compressionLevel` option is a preset for `windowLog`, `hashLog`, etc options.
+We may set `compressionLevel` or other options, mixing is pointless.
+We can say that there are 2 option groups: group with single `compressionLevel` option and group with other options.
+
+```ruby
+general_generator = OCG.new(
+  :compressionLevel => -10..10
+)
+.or(
+  :windowLog => 0..10,
+  :hashLog => 0..10,
+  ...
+)
+```
+
+`enableLongDistanceMatching` option enables usage of `ldmHashLog`, `ldmMinMatch`, etc options.
+We may use `:enableLongDistanceMatching => false` or `:enableLongDistanceMatching => true` with other options.
+
+```ruby
+ldm_generator = OCG.new(
+  :enableLongDistanceMatching => [false]
+)
+.or(
+  :enableLongDistanceMatching => [true],
+  :ldmHashLog => 0..10,
+  :ldmMinMatch => 0..10,
+  ...
+)
+```
+
+General compression and long distance matching option groups correlate between each other.
+We want to have all possible combinations between these option groups.
+
+```ruby
+main_generator = general_generator.and ldm_generator
+```
+
+`contentSizeFlag`, `checksumFlag`, `dictIDFlag` options are additional options.
+These options don't correlate between each other or with main options.
+We want just to mix their values with main options.
+
+```ruby
+almost_complete_generator = main_generator.mix(
+  :contentSizeFlag => [true, false]
+)
+.mix(
+  :checksumFlag => [true, false]
+)
+.mix(
+  :dictIDFlag => [true, false]
+)
+```
+
+`nbWorkers`, `jobSize` and `overlapLog` options are thread related options.
+These options correlate between each other but don't correlate with main options.
+
+```ruby
+complete_generator = almost_complete_generator.mix(
+  :nbWorkers => 0..2,
+  :jobSize => 1..10,
+  :overlapLog => 0..9
+)
+```
+
+## CI
+
+Travis and Appveyor CI uses [scripts/toolchains.sh](scripts/toolchains.sh) directly.
+Cirrus and Circle CI uses prebuilt [scripts/test-images](scripts/test-images).
+Cirrus CI uses amd64 image, Circle CI - i686.
+
+## License
+
+MIT license, see LICENSE and AUTHORS.

data/lib/ocg.rb

@@ -0,0 +1,5 @@
+# Option combination generator.
+# Copyright (c) 2019 AUTHORS, MIT License.
+
+require_relative "ocg/main"
+require_relative "ocg/version"

data/lib/ocg/error.rb

@@ -0,0 +1,9 @@
+# Option combination generator.
+# Copyright (c) 2019 AUTHORS, MIT License.
+
+class OCG
+  class BaseError < ::StandardError; end
+
+  class NotImplementedError < BaseError; end
+  class ValidateError       < BaseError; end
+end

data/lib/ocg/main.rb

@@ -0,0 +1,41 @@
+# Option combination generator.
+# Copyright (c) 2019 AUTHORS, MIT License.
+
+require "forwardable"
+
+require_relative "error"
+require_relative "options"
+
+class OCG
+  extend ::Forwardable
+
+  DELEGATORS = %i[reset next last started? finished? length].freeze
+
+  def initialize(generator_or_options)
+    @generator = self.class.prepare_generator generator_or_options
+  end
+
+  def self.prepare_generator(generator_or_options)
+    return generator_or_options if generator_or_options.is_a? OCG
+
+    Options.new generator_or_options
+  end
+
+  def_delegators :@generator, *DELEGATORS
+
+  def and(generator_or_options)
+    Operator::AND.new self, generator_or_options
+  end
+
+  def mix(generator_or_options)
+    Operator::MIX.new self, generator_or_options
+  end
+
+  def or(generator_or_options)
+    Operator::OR.new self, generator_or_options
+  end
+end
+
+require_relative "operator/and"
+require_relative "operator/mix"
+require_relative "operator/or"

data/lib/ocg/operator/abstract.rb

@@ -0,0 +1,44 @@
+# Option combination generator.
+# Copyright (c) 2019 AUTHORS, MIT License.
+
+require_relative "../error"
+
+class OCG
+  module Operator
+    class Abstract < OCG
+      def initialize(left_generator_or_options, right_generator_or_options)
+        @left_generator  = OCG.prepare_generator left_generator_or_options
+        @right_generator = OCG.prepare_generator right_generator_or_options
+
+        reset
+      end
+
+      def reset
+        @left_generator.reset
+        @right_generator.reset
+
+        nil
+      end
+
+      def next
+        raise NotImplementedError, "\"next\" is not implemented"
+      end
+
+      def last
+        raise NotImplementedError, "\"last\" is not implemented"
+      end
+
+      def started?
+        raise NotImplementedError, "\"started?\" is not implemented"
+      end
+
+      def finished?
+        raise NotImplementedError, "\"finished?\" is not implemented"
+      end
+
+      def length
+        raise NotImplementedError, "\"length\" is not implemented"
+      end
+    end
+  end
+end

data/lib/ocg/operator/and.rb

@@ -0,0 +1,44 @@
+# Option combination generator.
+# Copyright (c) 2019 AUTHORS, MIT License.
+
+require_relative "abstract"
+
+class OCG
+  module Operator
+    class AND < Abstract
+      def next
+        return nil if finished?
+
+        if @right_generator.finished?
+          @right_generator.reset
+          @left_generator.next.merge @right_generator.next
+        else
+          left_last = @left_generator.last
+          left_last = @left_generator.next if left_last.nil?
+          left_last.merge @right_generator.next
+        end
+      end
+
+      def last
+        left_last  = @left_generator.last
+        right_last = @right_generator.last
+
+        return nil if left_last.nil? || right_last.nil?
+
+        left_last.merge right_last
+      end
+
+      def started?
+        @left_generator.started? || @right_generator.started?
+      end
+
+      def finished?
+        @left_generator.finished? && @right_generator.finished?
+      end
+
+      def length
+        @left_generator.length * @right_generator.length
+      end
+    end
+  end
+end

data/lib/ocg/operator/mix.rb

@@ -0,0 +1,50 @@
+# Option combination generator.
+# Copyright (c) 2019 AUTHORS, MIT License.
+
+require_relative "abstract"
+
+class OCG
+  module Operator
+    class MIX < Abstract
+      def initialize(*args)
+        super
+
+        @main_generator = \
+          if @right_generator.length > @left_generator.length
+            @right_generator
+          else
+            @left_generator
+          end
+      end
+
+      def next
+        return nil if finished?
+
+        @left_generator.reset if @left_generator.finished?
+        @right_generator.reset if @right_generator.finished?
+        @left_generator.next.merge @right_generator.next
+      end
+
+      def last
+        left_last  = @left_generator.last
+        right_last = @right_generator.last
+
+        return nil if left_last.nil? || right_last.nil?
+
+        left_last.merge right_last
+      end
+
+      def started?
+        @main_generator.started?
+      end
+
+      def finished?
+        @main_generator.finished?
+      end
+
+      def length
+        @main_generator.length
+      end
+    end
+  end
+end

data/lib/ocg/operator/or.rb

@@ -0,0 +1,43 @@
+# Option combination generator.
+# Copyright (c) 2019 AUTHORS, MIT License.
+
+require_relative "abstract"
+
+class OCG
+  module Operator
+    class OR < Abstract
+      def next
+        return nil if finished?
+
+        if @left_generator.finished?
+          @right_generator.next
+        else
+          @left_generator.next
+        end
+      end
+
+      def last
+        left_last  = @left_generator.last
+        right_last = @right_generator.last
+
+        if right_last.nil?
+          left_last
+        else
+          right_last
+        end
+      end
+
+      def started?
+        @left_generator.started? || @right_generator.started?
+      end
+
+      def finished?
+        @left_generator.finished? && @right_generator.finished?
+      end
+
+      def length
+        @left_generator.length + @right_generator.length
+      end
+    end
+  end
+end

data/lib/ocg/options.rb

@@ -0,0 +1,77 @@
+# Option combination generator.
+# Copyright (c) 2019 AUTHORS, MIT License.
+
+require_relative "validation"
+
+class OCG
+  class Options
+    def initialize(options)
+      Validation.validate_options options
+      @options = Hash[options.map { |name, values| [name, values.to_a] }]
+
+      # End to start is more traditional way of making combinations.
+      @keys = @options.keys.reverse
+
+      @last_options = nil
+
+      reset_value_indexes
+
+      @is_finished = false
+    end
+
+    protected def reset_value_indexes
+      @value_indexes = Hash[@options.map { |name, _values| [name, 0] }]
+    end
+
+    def reset
+      return nil unless started?
+
+      @last_options = nil
+
+      # If state is finished than all value indexes are already zero.
+      reset_value_indexes unless @is_finished
+
+      @is_finished = false
+
+      nil
+    end
+
+    def next
+      return nil if @is_finished
+
+      @last_options = Hash[@value_indexes.map { |name, value_index| [name, @options[name][value_index]] }]
+
+      @is_finished = @keys.all? do |name|
+        values          = @options[name]
+        new_value_index = @value_indexes[name] + 1
+
+        if new_value_index < values.length
+          @value_indexes[name] = new_value_index
+          next false
+        end
+
+        # Reset value index to zero.
+        @value_indexes[name] = 0
+        true
+      end
+
+      @last_options
+    end
+
+    def last
+      @last_options
+    end
+
+    def started?
+      !@last_options.nil?
+    end
+
+    def finished?
+      @is_finished
+    end
+
+    def length
+      @options.reduce(1) { |length, (_name, values)| length * values.length }
+    end
+  end
+end

data/lib/ocg/validation.rb

@@ -0,0 +1,18 @@
+# Option combination generator.
+# Copyright (c) 2019 AUTHORS, MIT License.
+
+require_relative "error"
+
+class OCG
+  module Validation
+    def self.validate_options(options)
+      raise ValidateError, "invalid options hash" unless options.is_a? ::Hash
+      raise ValidateError, "options should not be empty" if options.empty?
+
+      options.each do |_name, values|
+        raise ValidateError, "option values should respond to \"to_a\"" unless values.respond_to? :to_a
+        raise ValidateError, "option values should not be empty" if values.to_a.empty?
+      end
+    end
+  end
+end

data/lib/ocg/version.rb

@@ -0,0 +1,6 @@
+# Option combination generator.
+# Copyright (c) 2019 AUTHORS, MIT License.
+
+class OCG
+  VERSION = "1.0.0".freeze
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: ocg
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Andrew Aladjev
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-10-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.75'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.75'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+description: 
+email: aladjev.andrew@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AUTHORS
+- LICENSE
+- README.md
+- lib/ocg.rb
+- lib/ocg/error.rb
+- lib/ocg/main.rb
+- lib/ocg/operator/abstract.rb
+- lib/ocg/operator/and.rb
+- lib/ocg/operator/mix.rb
+- lib/ocg/operator/or.rb
+- lib/ocg/options.rb
+- lib/ocg/validation.rb
+- lib/ocg/version.rb
+homepage: https://github.com/andrew-aladev/ocg
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+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.6
+signing_key: 
+specification_version: 4
+summary: Option combination generator.
+test_files: []