flagset 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1e36620b007fc35a4b3958aa81ad25d9d23042c4
+  data.tar.gz: f8862c9d9352cc2f403e7cd83007a5e30b0fa646
+SHA512:
+  metadata.gz: 715c230d4e172b077f8e5684963e3ada9a51bc9f1e2c7ddc7081cbfe1617b7458ccca4f48a5a18d379b97914ccc1e142f9ea19d909a7ff81082f77c1f2ccee2b
+  data.tar.gz: 3c4d1e911b572d5ffba929e8a94e46cfece977fa99b0ac54e4ec38bb5ab01cc801adb5913e796403406841dbe56cec29ca16bb010c70376660d4d3950be95e40

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.1
+before_install: gem install bundler -v 1.13.1

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in flagset.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Yusuke Takeuchi
+
+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,147 @@
+# FlagSet
+FlagSet is a Ruby library to make sets of finite flags.
+
+## Installation
+```
+gem install flagset
+```
+## Usage
+### define
+You define a class with FlagSet.define:
+```ruby
+Auth = FlagSet.define{
+  flag :allow_read_name
+  flag :allow_read_email
+  flag :allow_read_posts
+}
+```
+Simpler ways are also available:
+```ruby
+Auth = FlagSet.define{
+  flag :allow_read_name, :allow_read_email, :allow_read_posts
+}
+```
+Or
+```ruby
+Auth = FlagSet.define(:allow_read_name, :allow_read_email, :allow_read_posts)
+```
+
+### create
+```ruby
+Auth.new
+# => #<Auth: []> (empty set)
+Auth.new(:allow_read_name, :allow_read_posts)
+# => #<Auth: [:allow_read_name,:allow_read_posts]>
+Auth[:allow_read_name, :allow_read_posts]
+# => #<Auth: [:allow_read_name,:allow_read_posts]> (same as above)
+```
+
+### create with class methods
+```ruby
+Auth.allow_read_email
+# => #<Auth: [:allow_read_email]> (same as Auth.new(:allow_read_email))
+
+Auth.allow_read_name | Auth.allow_read_posts
+# => #<Auth: [:allow_read_name,:allow_read_posts]>
+```
+You can use special name *all* and *none*
+```ruby
+Auth.all
+# => #<Auth: [:allow_read_name,:allow_read_email,:allow_read_posts]>
+Auth.none
+# => #<Auth: []>
+```
+
+### aliases
+*all* and *none* are aliases that denotes set of flags. You can also define aliases your own.
+```ruby
+Auth2 = FlagSet.define{
+  aliased :read_all, [:read_name, :read_email, :read_posts]
+  flag :read_name, :read_email, :read_posts
+
+  flag :write_posts, :write_messages
+  aliased :write_all, [:write_posts, :write_messages]
+  # You can put aliased before or after the original names
+
+  aliased :read_write_all, [:read_all, :write_all]
+}
+
+Auth2.read_all
+# => #<Auth2: [:read_name,:read_email,:read_posts]>
+Auth2.write_all
+# => #<Auth2: [:write_posts,:write_messages]>
+Auth2.read_write_all == Auth2.all
+# => true
+```
+
+### Queries
+You can check the state of the flags with *has_all_of?* and *has_any_of?* methods:
+```ruby
+Auth2.read_name.has_all_of?(:read_all)
+# => false
+Auth2.read_all.has_all_of?(:read_name, :read_email)
+# => true
+Auth2.write_all.has_all_of?(Auth2[:write_posts, :write_messages])
+# => true
+Auth2[:read_all].has_any_of?(:read_posts)
+# => true
+Auth2.read_all.has_any_of?(:write_all)
+# => false
+Auth2.all.has_any_of?(:none)
+# => false
+```
+
+You can also use named query methods:
+```ruby
+Auth2.read_all.read_name?
+# => true
+Auth2.write_posts.write_all?
+# => true
+```
+Note that the query method *#foo?* is equivalent to *has_any_of?(:foo)*, so
+aliases can be confusing when used as query methods.
+
+There are special query methods *all?*, *any?*, *none?*
+```ruby
+# #all? returns true if self is equal to class.all
+Auth2.read_all.all? #=> false
+(Auth2.read_all | Auth2.write_all).all? #=> true
+
+# #any? returns true if self is not equal to class.none
+Auth2.read_email.any? # => true
+Auth2.new.any? # => false
+
+# #none? returns true if self is equal to class.none
+Auth2.read_posts.none? #=> false
+Auth2.none.none? #=> true
+```
+
+### Set operations
+Basic set operations are supported.
+```ruby
+Auth2.read_all & Auth2.read_name
+# => #<Auth2: [:read_name]>
+
+Auth2.read_name | Auth2.read_email
+# => #<Auth2: [:read_name,:read_email]>
+
+Auth2.read_all - :read_posts
+# => #<Auth2: [:read_name,:read_email]>
+
+Auth2[:read_name, :read_email] ^ [:read_email, :read_posts]
+# => #<Auth2: [:read_name,:read_posts]>
+
+~Auth2[:write_all]
+# => #<Auth2: [:read_name,:read_email,:read_posts]>
+```
+The arguments of .new and set operations can be one of these:
+
+* Symbol
+* the same class as self
+* Integer
+
+or a single Array of above.
+
+
+## License
+MIT License

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "flagset"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/flagset.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'flagset/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "flagset"
+  spec.version       = Flagset::VERSION
+  spec.authors       = ["Yusuke Takeuchi"]
+  spec.email         = ["v.takeuchi@gmail.com"]
+
+  spec.summary       = %q{Module to define classes respresenting a set of flags.}
+  spec.description   = spec.summary
+  spec.homepage      = "https://github.com/YusukeTakeuchi/flagset"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.13"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "equalizer"
+end

data/lib/flagset/version.rb

@@ -0,0 +1,3 @@
+module Flagset
+  VERSION = "0.1.0"
+end

data/lib/flagset.rb

@@ -0,0 +1,311 @@
+require 'tsort'
+require 'equalizer'
+require "flagset/version"
+
+module FlagSet
+
+  def self.define(*names, &block)
+    if names.any? and block
+      raise ArgumentError, 'symbols and block cannot be specified at once'
+    end
+    builder = Builder.new
+    unless block
+      block = lambda{| *_ |
+        names.each{| name |
+          flag name
+        }
+      }
+    end
+    builder.define(&block)
+    Class.new(Base){
+      define_singleton_method(:flagset_builder){
+        builder
+      }
+      define_flags_class_methods
+      define_flags_instance_methods
+    }
+  end
+
+  class Builder
+    attr_reader :elementary_flag_names
+    attr_reader :all_flags_and_ints
+    attr_reader :current_all_mask
+
+    def initialize
+      @elementary_flag_names = []
+      @all_flags_and_ints = {}
+      @current_all_mask = 0
+    end
+
+    def define(&block)
+      @unresolved_aliases = {}.extend(AliasResolvingTSort)
+      instance_eval(&block)
+      @all_flags_and_ints[:all] = @current_all_mask
+      @all_flags_and_ints[:none] = 0
+      aliases = @unresolved_aliases.keys
+      (@unresolved_aliases.tsort & aliases).each{| name |
+        @all_flags_and_ints[name] =
+          @unresolved_aliases[name].inject(0){| v,t_name |
+            v | (@all_flags_and_ints[t_name] or raise NameError, "unknown flag name: #{t_name}")
+          }
+      }
+    end
+
+    # @param [Array<Symbol>] names
+    # @option opts [Integer] :bits the bits to represent
+    # @option opts [Integer] :bit alias for :bits
+    def flag(*names, **opts)
+      if bits = opts[:bit] || opts[:bits]
+        if opts[:bit] and opts[:bits]
+          raise ArgumentError, 'bit and bits cannot be specified at once'
+        end
+        unless names.size == 1
+          raise ArgumentError, 'only one name can be specified with bit option'
+        end
+        if @current_all_mask & bits != 0
+          raise ArgumentError, 'conflicting bits'
+        end
+        name = names.first
+        error_if_already_in_use(name)
+        @elementary_flag_names << name
+        @all_flags_and_ints[name] = bits
+        @current_all_mask |= bits
+      else
+        names.each{| fname |
+          error_if_already_in_use(fname)
+          bit = next_available_bit
+          @elementary_flag_names << fname
+          @all_flags_and_ints[fname] = bit
+          @current_all_mask |= bit
+        }
+      end
+    end
+
+    def next_available_bit
+      bit = 1
+      until @current_all_mask & bit == 0
+        bit <<= 1
+      end
+      bit
+    end
+
+    def aliased(name, targets)
+      error_if_already_in_use(name)
+      targets = [targets] unless targets.kind_of?(Enumerable)
+      @unresolved_aliases[name] = targets
+    end
+
+    def error_if_already_in_use(name)
+      if @all_flags_and_ints[name] or @unresolved_aliases[name]
+        raise ArgumentError, "flag name #{name} is already in use"
+      end
+    end
+
+    module AliasResolvingTSort
+      include TSort
+
+      def tsort_each_node(&block)
+        each_key(&block)
+      end
+
+      def tsort_each_child(node, &block)
+        (self[node] || []).each(&block)
+      end
+    end
+  end
+
+  # The class FlagSet.define creates derives from Base
+  class Base
+    include Equalizer.new(:to_i)
+
+    def initialize(*args)
+      @int_value = args_to_int_value(*args)
+    end
+
+    def to_i
+      @int_value
+    end
+
+    def to_s
+      '#<%s: [%s]>' % [
+        self.class,
+        to_names.map(&:inspect).join(',')
+      ]
+    end
+    alias inspect to_s
+
+    def to_names
+      self.class.int_to_names(@int_value)
+    end
+
+    private
+    def args_to_int_value(*args)
+      if args.size == 1
+        if args.first.kind_of?(Enumerable)
+          objs = args.first
+        else
+          objs = [args.first]
+        end
+      else
+        objs = args
+      end
+      enum_to_int_value(objs)
+    end
+
+    # @param [Array<Symbol,Base,Integer>] objs
+    def enum_to_int_value(objs)
+      objs.inject(0){| v,obj |
+        v | (
+          case obj
+          when Symbol
+            self.class.name_to_int(obj) or
+              raise ArgumentError, "#{obj} is not defined in #{self.class}"
+          when self.class
+            obj.to_i
+          when Integer
+            unless consistent_int?(obj) and (~self.class.all_flags_mask & obj) == 0
+              raise ArgumentError, "0x#{obj.to_s(16)} is a flag value inconsistent with #{self.class}"
+            end
+            obj
+          else
+            raise TypeError, "cannot convert to #{self.class}: #{obj}"
+          end
+        )
+      }
+    end
+
+    # check if v is consistent with the set of flags
+    # v is inconsistent in cases like:
+    #   F = FlagSet.define{
+    #     flag :some_flag, bits: 0xFF
+    #   }
+    #   F.new(1)
+    # @param [Integer] v
+    def consistent_int?(v)
+      self.class.elementary_flag_names.all?{| name |
+        mask = self.class.all_flags_and_ints[name]
+        [0, mask].include?(mask & v)
+      }
+    end
+
+    class << self
+      def name_to_int(name)
+        all_flags_and_ints[name] or raise NameError, "unknown flag name for #{self.class}: #{name}"
+      end
+
+      def int_to_names(int)
+        elementary_flag_names.select{| name |
+          (int & (all_flags_and_ints[name])) != 0
+        }
+      end
+
+      def flagset_builder
+        # abstract
+      end
+
+      # elementary flags are flags that are not aliases
+      #
+      # @return [Array<Symbol>]
+      def elementary_flag_names
+        flagset_builder.elementary_flag_names
+      end
+
+      # @return [Hash<Symbol,Integer>]
+      def all_flags_and_ints
+        flagset_builder.all_flags_and_ints
+      end
+
+      # @return [Integer]
+      def all_flags_mask
+        flagset_builder.current_all_mask
+      end
+
+      def [](*args)
+        new(*args)
+      end
+
+      def define_flags_class_methods
+        all_flags_and_ints.each{| k,v |
+          define_singleton_method(k){
+            new(v)
+          }
+        }
+      end
+
+      def define_flags_instance_methods
+        all_flags_and_ints.each{| k,v |
+          next if [:all, :none].include?(k)
+          define_method("#{k}?"){
+            has_any_of?(v)
+          }
+        }
+      end
+    end
+
+    public
+    ### set manipulation methods ###
+
+    def &(*args)
+      self.class.new(@int_value & args_to_int_value(*args))
+    end
+    alias intersect &
+
+    def |(*args)
+      self.class.new(@int_value | args_to_int_value(*args))
+    end
+    alias union |
+    alias + |
+
+    def -(*args)
+      self.class.new(@int_value & ~args_to_int_value(*args))
+    end
+    alias difference -
+
+    def ^(*args)
+      self.class.new(@int_value ^ args_to_int_value(*args))
+    end
+
+    def ~@
+      self.class.new(self.class.all_flags_mask & ~@int_value)
+    end
+
+    def subset?(*args)
+      @int_value & ~args_to_int_value(*args) == 0
+    end
+
+    def proper_subset?(*args)
+      v = args_to_int_value(*args)
+      @int_value & ~v == 0 and @int_value != v
+    end
+
+    def superset?(*args)
+      ~@int_value & args_to_int_value(*args) == 0
+    end
+    alias has_all_of? superset?
+
+    def proper_superset?(*args)
+      v = args_to_int_value(*args)
+      ~@int_value & v == 0 and @int_value != v
+    end
+
+    def intersect?(*args)
+      @int_value & args_to_int_value(*args) != 0
+    end
+    alias has_any_of? intersect?
+    alias === intersect?
+
+    def all?
+      @int_value == self.class.all_flags_mask
+    end
+
+    def any?
+      @int_value != 0
+    end
+
+    def none?
+      @int_value == 0
+    end
+
+  end
+
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: flagset
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yusuke Takeuchi
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-11-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: equalizer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Module to define classes respresenting a set of flags.
+email:
+- v.takeuchi@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- flagset.gemspec
+- lib/flagset.rb
+- lib/flagset/version.rb
+homepage: https://github.com/YusukeTakeuchi/flagset
+licenses: []
+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: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Module to define classes respresenting a set of flags.
+test_files: []