Permalink
Browse files

Update README.rdoc

  • Loading branch information...
1 parent 28d6454 commit 9e7ba3af407dac64a392a8d28c222b29d7621a24 @boosty boosty committed Sep 2, 2012
Showing with 2 additions and 326 deletions.
  1. +2 −326 README.rdoc
View
@@ -1,327 +1,3 @@
-=FlagShihTzu
+XING is no longer maintaining this library. Thankfully, Peter Boling is now maintaining it.
-Bit fields for ActiveRecord
-
-An extension for {ActiveRecord}[https://rubygems.org/gems/activerecord]
-to store a collection of boolean attributes in a single integer column
-as a bit field.
-
-http://github.com/xing/flag_shih_tzu
-
-This gem lets you use a single integer column in an ActiveRecord model
-to store a collection of boolean attributes (flags). Each flag can be used
-almost in the same way you would use any boolean attribute on an
-ActiveRecord object.
-
-The benefits:
-* No migrations needed for new boolean attributes. This helps a lot
- if you have very large db-tables, on which you want to avoid ALTER TABLE
- whenever possible.
-* Only the one integer column needs to be indexed.
-
-Using FlagShihTzu, you can add new boolean attributes whenever you want,
-without needing any migration. Just add a new flag to the +has_flags+ call.
-
-And just in case you are wondering what a "Shih Tzu" is:
-http://en.wikipedia.org/wiki/Shih_Tzu
-
-
-==Build status
-
-{<img src="https://secure.travis-ci.org/xing/flag_shih_tzu.png" />}[http://travis-ci.org/xing/flag_shih_tzu]
-
-
-==Prerequisites
-
-The gem is actively being tested with:
-
-* ActiveRecord versions 2.3.x, 3.0.x, 3.1.x, 3.2.x
-* MySQL, PostgreSQL and SQLite3 databases
-* Ruby 1.8.7, 1.9.2 and 1.9.3
-
-
-==Installation
-
-===Rails 2.x
-
-In environment.rb:
-
- config.gem 'flag_shih_tzu'
-
-Then:
-
- $ rake gems:install # use sudo if necessary
-
-===Rails 3
-
-In Gemfile:
-
- gem 'flag_shih_tzu'
-
-Then:
-
- $ bundle install
-
-
-==Usage
-
-FlagShihTzu assumes that your ActiveRecord model already has an integer field
-to store the flags, which should be defined to not allow NULL values and
-should have a default value of 0 (which means all flags are initially set to
-false).
-
-
-===Defining the flags
-
- class Spaceship < ActiveRecord::Base
- include FlagShihTzu
-
- has_flags 1 => :warpdrive,
- 2 => :shields,
- 3 => :electrolytes
- end
-
-+has_flags+ takes a hash. The keys must be positive integers and represent
-the position of the bit being used to enable or disable the flag.
-<b>The keys must not be changed once in use, or you will get wrong results.</b>
-That is why the plugin forces you to set them explicitly.
-The values are symbols for the flags being created.
-
-
-===How it stores the values
-
-As said, FlagShihTzu uses a single integer column to store the values for all
-the defined flags as a bit field.
-
-The bit position of a flag corresponds to the given key.
-
-This way, we can use bit operators on the stored integer value to set, unset
-and check individual flags.
-
- +---+---+---+ +---+---+---+
- | | | | | | | |
- Bit position | 3 | 2 | 1 | | 3 | 2 | 1 |
- (flag key) | | | | | | | |
- +---+---+---+ +---+---+---+
- | | | | | | | |
- Bit value | 4 | 2 | 1 | | 4 | 2 | 1 |
- | | | | | | | |
- +---+---+---+ +---+---+---+
- | e | s | w | | e | s | w |
- | l | h | a | | l | h | a |
- | e | i | r | | e | i | r |
- | c | e | p | | c | e | p |
- | t | l | d | | t | l | d |
- | r | d | r | | r | d | r |
- | o | s | i | | o | s | i |
- | l | | v | | l | | v |
- | y | | e | | y | | e |
- | t | | | | t | | |
- | e | | | | e | | |
- | s | | | | s | | |
- +---+---+---+ +---+---+---+
- | 1 | 1 | 0 | = 4 + 2 = 6 | 1 | 0 | 1 | = 4 + 1 = 5
- +---+---+---+ +---+---+---+
-
-Read more about bit fields here: http://en.wikipedia.org/wiki/Bit_field
-
-
-===Using a custom column name
-
-The default column name to store the flags is 'flags', but you can provide a
-custom column name using the <tt>:column</tt> option. This allows you to use
-different columns for separate flags:
-
- has_flags 1 => :warpdrive,
- 2 => :shields,
- 3 => :electrolytes,
- :column => 'features'
-
- has_flags 1 => :spock,
- 2 => :scott,
- 3 => :kirk,
- :column => 'crew'
-
-
-===Generated instance methods
-
-Calling +has_flags+ as shown above creates the following instance methods
-on Spaceship:
-
- Spaceship#warpdrive
- Spaceship#warpdrive?
- Spaceship#warpdrive=
- Spaceship#warpdrive_changed?
-
- Spaceship#shields
- Spaceship#shields?
- Spaceship#shields=
- Spaceship#shields_changed?
-
- Spaceship#electrolytes
- Spaceship#electrolytes?
- Spaceship#electrolytes=
- Spaceship#electrolytes_changed?
-
-Opionally, you can set the <tt>:bang_methods</tt> option to true to enable the bang methods:
-
- Spaceship#electrolytes!
- Spaceship#not_electrolytes!
-
-which respectively enables or disables the electrolytes flag.
-
-
-===Generated named scopes
-
-The following named scopes become available:
-
- Spaceship.warpdrive # :conditions => "(spaceships.flags in (1,3,5,7))"
- Spaceship.not_warpdrive # :conditions => "(spaceships.flags not in (1,3,5,7))"
- Spaceship.shields # :conditions => "(spaceships.flags in (2,3,6,7))"
- Spaceship.not_shields # :conditions => "(spaceships.flags not in (2,3,6,7))"
- Spaceship.electrolytes # :conditions => "(spaceships.flags in (4,5,6,7))"
- Spaceship.not_electrolytes # :conditions => "(spaceships.flags not in (4,5,6,7))"
-
-If you do not want the named scopes to be defined, set the
-<tt>:named_scopes</tt> option to false when calling +has_flags+:
-
- has_flags 1 => :warpdrive, 2 => :shields, 3 => :electrolytes, :named_scopes => false
-
-In a Rails 3 application, FlagShihTzu will use <tt>scope</tt> internally to generate
-the scopes. The option on has_flags is still named <tt>:named_scopes</tt> however.
-
-
-===Examples for using the generated methods
-
- enterprise = Spaceship.new
- enterprise.warpdrive = true
- enterprise.shields = true
- enterprise.electrolytes = false
- enterprise.save
-
- if enterprise.shields?
- ...
- end
-
- Spaceship.warpdrive.find(:all)
- Spaceship.not_electrolytes.count
- ...
-
-
-===Support for manually building conditions
-
-The following class methods may support you when manually building
-ActiveRecord conditions:
-
- Spaceship.warpdrive_condition # "(spaceships.flags in (1,3,5,7))"
- Spaceship.not_warpdrive_condition # "(spaceships.flags not in (1,3,5,7))"
- Spaceship.shields_condition # "(spaceships.flags in (2,3,6,7))"
- Spaceship.not_shields_condition # "(spaceships.flags not in (2,3,6,7))"
- Spaceship.electrolytes_condition # "(spaceships.flags in (4,5,6,7))"
- Spaceship.not_electrolytes_condition # "(spaceships.flags not in (4,5,6,7))"
-
-These methods also accept a :table_alias option that can be used when
-generating SQL that references the same table more than once:
-
- Spaceship.shields_condition(:table_alias => 'evil_spaceships') # "(evil_spaceships.flags in (2,3,6,7))"
-
-
-===Choosing a query mode
-
-While the default way of building the SQL conditions uses an IN() list
-(as shown above), this approach will not work well for a high number of flags,
-as the value list for IN() grows.
-
-For MySQL, depending on your MySQL settings, this can even hit the
-'max_allowed_packet' limit with the generated query.
-
-In this case, consider changing the flag query mode to <tt>:bit_operator</tt>
-instead of <tt>:in_list</tt>, like so:
-
- has_flags 1 => :warpdrive,
- 2 => :shields,
- :flag_query_mode => :bit_operator
-
-This will modify the generated condition and named_scope methods to use bit
-operators in the SQL instead of an IN() list:
-
- Spaceship.warpdrive_condition # "(spaceships.flags & 1 = 1)",
- Spaceship.not_warpdrive_condition # "(spaceships.flags & 1 = 0)",
- Spaceship.shields_condition # "(spaceships.flags & 2 = 2)",
- Spaceship.not_shields_condition # "(spaceships.flags & 2 = 0)",
-
- Spaceship.warpdrive # :conditions => "(spaceships.flags & 1 = 1)"
- Spaceship.not_warpdrive # :conditions => "(spaceships.flags & 1 = 0)"
- Spaceship.shields # :conditions => "(spaceships.flags & 2 = 2)"
- Spaceship.not_shields # :conditions => "(spaceships.flags & 2 = 0)"
-
-The drawback is that due to the bit operator, this query can not use an index
-on the flags column.
-
-
-==Running the gem tests
-
-First, make sure all required gems are installed:
-
- $ bundle install
-
-The default rake test task will run the tests against the currently locked
-ActiveRecord version (see +Gemfile.lock+):
-
- $ bundle exec rake test
-
-If you want to run the tests against all supported ActiveRecord versions:
-
- $ bundle exec rake test:all
-
-This will internally use bundler to load specific ActiveRecord versions
-before executing the tests (see +gemfiles/+), e.g.:
-
- $ BUNDLE_GEMFILE='gemfiles/Gemfile.activerecord-3.1.x' bundle exec rake test
-
-
-All tests will use an in-memory sqlite database by default.
-If you want to use a different database, see <tt>test/database.yml</tt>,
-install the required adapter gem and use the DB environment variable to
-specify which config from <tt>test/database.yml</tt> to use, e.g.:
-
- $ DB=mysql bundle exec rake
-
-
-==Authors
-
-{Patryk Peszko}[http://github.com/ppeszko],
-{Sebastian Roebke}[http://github.com/boosty],
-{David Anderson}[http://github.com/alpinegizmo],
-{Tim Payton}[http://github.com/dizzy42]
-and a helpful group of
-{contributors}[https://github.com/xing/flag_shih_tzu/contributors].
-Thanks!
-
-Please find out more about our work in our
-{Devblog}[http://devblog.xing.com/].
-
-
-==License
-
-The MIT License
-
-Copyright (c) 2011 {XING AG}[http://www.xing.com/]
-
-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.
+The repo has been moved to: https://github.com/pboling/flag_shih_tzu

0 comments on commit 9e7ba3a

Please sign in to comment.