flagpole 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0d780ac84b47a9d2fdd5ee20b34bb7ebb5ef88b6
+  data.tar.gz: 6fb5247148b3bcf18d786037aa51f9750ed888ed
+SHA512:
+  metadata.gz: 7eebec9b05c2460a278f338723c45be41861827970c61da69f1fb6079b6754f629ddeb6ed2ae3b7470d60b49bed90cba87d8a8d938a866e63f9b5ef9144d27c6
+  data.tar.gz: 0cca77e4b8f07aa081144c52920cc2a2454f5b67d013d401bc3769bfe900a5f0d7710f23487669115262c11256dad127f8784807f813a78036b3d4d810741c12

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Nicolas Sanguinetti <hi@nicolassanguinetti.info>
+
+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,95 @@
+# Flagpole: Simple bitmap for storing flags
+
+![](https://upload.wikimedia.org/wikipedia/commons/thumb/8/8b/Expo_2010_Shanghai_flags_and_China_Pavilion.jpg/1024px-Expo_2010_Shanghai_flags_and_China_Pavilion.jpg)
+
+Flagpole allows bundling a bunch of flags into a single integer field, by
+storing each flag as a bit.
+
+``` ruby
+notifications_via = Flagpole.new([:email, :sms, :phone_push])
+notifications_via.to_h #=> { email: false, sms: false, phone_push: false }
+
+notifications_via[:email] = true
+notifications_via[:sms] = true
+
+notifications_via.to_h #=> { email: true, sms: true, phone_push: false }
+notifications_via.to_i #=> 3
+```
+
+Now you can just store that `3` in your database. In order to get that back,
+just pass it to the constructor:
+
+``` ruby
+notifications_via = Flagpole.new(3, [:email, :sms, :phone_push])
+notifications_via.to_h #=> { email: true, sms: true, phone_push: false }
+```
+
+## Install
+
+    gem install flagpole
+
+## What kind of sorcery is this?!
+
+If you consider each flag as a "bit" (1 when true, 0 when false), then the above
+example could be represented as `[1, 1, 0]`. If you reverse this, you get the
+binary representation of the number `3` (`11`).
+
+All Flagpole does is give you a nice API to treat sets of named binary settings
+("flags") as an integer, by doing the marshaling for you.
+
+[Read more about bitmaps on Wikipedia](https://en.wikipedia.org/wiki/Bit_field).
+
+## I want to add a new flag
+
+Easy! Just add a new name **at the end** of the array of flag names. So, In the
+example above, if you later add support for twitter notifications, just do this:
+
+``` ruby
+notifications_via = Flagpole.new(3, [:email, :sms, :phone_push, :twitter])
+notifications_via.to_h #=> { email: true, sms: true, phone_push: false, twitter: false }
+```
+
+As you see, the values are maintained.
+
+If you wanted the new flag to default to `true`, you just need to increment all
+the values. You do this by using `#value_of`:
+
+``` ruby
+flags = Flagpole([:email, :sms, :phone_push, :twitter])
+flags.value_of(:twitter) #=> 8
+```
+
+Now all you have to do is add `8` to all your stored values, and voila, everyone
+has twitter notifications enabled.
+
+## I want to remove an existing flag
+
+In order to remove a flag, you will need to modify the integer values from your
+storage. Assuming the example from above, let's say you no longer wish to
+support SMS notifications.
+
+In order to find out the value to substract, you can use `#value_of`:
+
+``` ruby
+flags = Flagpole([:email, :sms, :phone_push, :twitter])
+flags.value_of(:sms) #=> 2
+```
+
+Now you need to substract 2 from all the values that _have the SMS flag set_. In
+order to do this, you need to do a _bitwise and_ between the value and `2`.
+Those that are non-zero, are the ones that have it set. In SQL this would be:
+
+``` sql
+UPDATE users
+SET notification_settings = notification_settings - 2
+WHERE notification_settings & 2 <> 0
+```
+
+## License
+
+This project is shared under the MIT license. See the attached [LICENSE][] file
+for details.
+
+Photo credit: [_Cesarexpo via Wikimedia Commons_](https://commons.wikimedia.org/wiki/File%3AExpo_2010_Shanghai_flags_and_China_Pavilion.jpg).
+
+[LICENSE]: ./LICENSE

data/lib/flagpole.rb

@@ -0,0 +1,64 @@
+class Flagpole
+  # Public: Initialize the set of flags.
+  #
+  # value - An Integer with the initial value of the set.
+  # flags - The name of the flags you're using.
+  def initialize(value = 0, flags)
+    @flags = flags.zip(bitmap(value, flags.size)).to_h
+  end
+
+  # Public: Get a specific flag by name.
+  #
+  # key - One of the flag names passed to the initializer.
+  #
+  # Returns Boolean.
+  def [](key)
+    @flags.fetch(key)
+  end
+
+  # Public: Set a specific flag by name.
+  #
+  # flag  - One of the flag names passed to the initializer.
+  # value - A Boolean.
+  #
+  # Returns nothing.
+  # Raises ArgumentError if passed a flag that isn't in the set.
+  def []=(flag, val)
+    fail ArgumentError, "#{flag} isn't a valid flag" unless @flags.key?(flag)
+    @flags[flag] = val
+  end
+
+  # Public: Returns the current value of the flag set as an Integer.
+  def to_i
+    @flags.each_value.with_index.inject(0) do |flag, (bit, power)|
+      flag | (bit ? 1 : 0) * 2**power
+    end
+  end
+
+  # Public: Returns a Hash with all the flags and their current values.
+  def to_h
+    @flags
+  end
+
+  # Public: Find the integer value of a single flag, regardless of whether it is
+  # set or not. This value can then be added/substracted from the integer value
+  # of this set for low-level manipulation of the flag set.
+  #
+  # flag - The name of a flag.
+  #
+  # Returns an Integer.
+  # Raises ArgumentError if passed a flag that isn't in the set.
+  def value_of(flag)
+    fail ArgumentError, "#{flag} isn't a valid flag" unless @flags.key?(flag)
+    2 ** @flags.keys.index(flag)
+  end
+
+  # Internal: Generate the list of bits that make a given number. Each index of
+  # the array corresponds to the bit for 2**index.
+  #
+  # Returns an Array of Booleans.
+  def bitmap(num, size)
+    Array.new(size).map.with_index { |_, i| num[i] == 1 }
+  end
+  private :bitmap
+end

data/lib/flagpole/version.rb

@@ -0,0 +1,3 @@
+class Flagpole
+  VERSION = "0.1.0".freeze
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: flagpole
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nicolas Sanguinetti
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-06-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cutest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: Use a bitmap to represent multiple flags (e.g. user settings)
+email:
+- contacto@nicolassanguinetti.info
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/flagpole.rb
+- lib/flagpole/version.rb
+homepage: http://github.com/foca/flagpole
+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: []
+rubyforge_project: 
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: Handle multiple flags in a single integer
+test_files: []