Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Restored the most recent README in rdoc format

* We prefer rdoc to markdown to allow rendering via `rake rdoc`
  • Loading branch information...
commit 45f248a8d5241d901f0b32e70181c1678862e0e5 1 parent 109aa42
@boosty boosty authored
Showing with 230 additions and 219 deletions.
  1. +0 −219 README.markdown
  2. +230 −0 README.rdoc
View
219 README.markdown
@@ -1,219 +0,0 @@
-# FlagShihTzu
-
-A rails plugin to store a collection of boolean attributes in a single
-ActiveRecord column as a bit field.
-
-This plugin 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 main benefit:
-**No migrations needed for new boolean attributes, which means no downtime!**
-
-This is very useful for large tables where adding new columns can take
-a long time or if you just want to avoid adding new columns for every
-boolean attribute.
-
-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.
-
-
-## Prerequisites
-
-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).
-
-The plugin has been tested with Rails versions from 2.1 to 2.3 and MySQL.
-
-
-## Installation
-
- cd path/to/your/rails-project
- ./script/plugin install git://github.com/xing/flag_shih_tzu.git
-
-
-## Usage
-
-### 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 should not
-be changed once in use, as they represent the position of the bit being used
-to enable or disable a flag. 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 flags in the bit field are arranged by their given key (bit position),
-starting at 1.
-
-This way, we can use bit operators on the stored integer value to set, unset
-and check the flags.
-
- +---+---+---+ +---+---+---+
- | 3 | 2 | 1 | | 3 | 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 | | |
- +---+---+---+ +---+---+---+
- | 0 | 0 | 0 | = 0 | 1 | 0 | 1 | = 4
- +---+---+---+ +---+---+---+
-
-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 `:column` option:
-
- has_flags(1 => :warpdrive , :column => 'bits')
-
-
-### Generated instance methods
-
-Calling `has_flags` as shown above creates the following instance methods
-on Spaceship:
-
- Spaceship#warpdrive
- Spaceship#warpdrive?
- Spaceship#warpdrive=
- Spaceship#shields
- Spaceship#shields?
- Spaceship#shields=
- Spaceship#electrolytes
- Spaceship#electrolytes?
- Spaceship#electrolytes=
-
-
-### Generated named scopes
-
-The following named scopes become available:
-
- Spaceship.warpdrive # :conditions => "(spaceships.flags & 1 = 1)"
- Spaceship.not_warpdrive # :conditions => "(spaceships.flags & 1 = 0)"
- Spaceship.shields # :conditions => "(spaceships.flags & 2 = 1)"
- Spaceship.not_shields # :conditions => "(spaceships.flags & 2 = 0)"
- Spaceship.electrolytes # :conditions => "(spaceships.flags & 4 = 1)"
- Spaceship.not_electrolytes # :conditions => "(spaceships.flags & 4 = 0)"
-
-If you do not want the named scopes to be defined, set the
-`:named_scopes` option to false when calling has_flags:
-
- has_flags(1 => :warpdrive, 2 => :shields, 3 => :electrolytes, :named_scopes => false)
-
-
-### Support for manually building conditions
-
-The following class methods may support you when manually building
-ActiveRecord conditions:
-
- Spaceship.warpdrive_condition # "(spaceships.flags & 1 = 1)"
- Spaceship.not_warpdrive_condition # "(spaceships.flags & 1 = 0)"
- Spaceship.shields_condition # "(spaceships.flags & 2 = 1)"
- Spaceship.not_shields_condition # "(spaceships.flags & 2 = 0)"
- Spaceship.electrolytes_condition # "(spaceships.flags & 4 = 1)"
- Spaceship.not_electrolytes_condition # "(spaceships.flags & 4 = 0)"
-
-
-### Example code
-
- enterprise = Spaceship.new
- enterprise.warpdrive = true
- enterprise.shields = true
- enterprise.electrolytes = false
- enterprise.save
-
- if spaceship.shields?
- ...
- end
-
- Spaceship.warpdrive.find(:all)
- Spaceship.not_electrolytes.count
- ...
-
-
-## Running the plugin tests
-
-1. Modify `test/database.yml` to fit your test environment.
-2. If needed, create the test database you configured in `test/database.yml`.
-
-Then you can run
-
- DB=mysql|postgres|sqlite|sqlite3 rake test:plugins PLUGIN=flag_shih_tzu
-
-from your Rails project root *or*
-
- DB=mysql|postgres|sqlite|sqlite3 rake
-
-from `vendor/plugins/flag_shih_tzu`.
-
-
-## Authors
-
-[Patryk Peszko](http://github.com/ppeszko),
-[Sebastian Roebke](http://github.com/boosty),
-[David Anderson](http://github.com/alpinegizmo)
-and [Tim Payton](http://github.com/dizzy42)
-
-Please find out more about our work in our
-[tech blog](http://blog.xing.com/category/english/tech-blog).
-
-
-## Contributors
-
-[TobiTobes](http://github.com/rngtng),
-[Martin Stannard](http://github.com/martinstannard),
-[Ladislav Martincik](http://github.com/lacomartincik),
-[Peter Boling](http://github.com/pboling),
-[Thorsten Böttger](http://github.com/alto)
-
-
-## License
-
-The MIT License
-
-Copyright (c) 2009 [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.
View
230 README.rdoc
@@ -0,0 +1,230 @@
+=FlagShihTzu
+
+A rails plugin to store a collection of boolean attributes in a single
+ActiveRecord column as a bit field.
+
+http://github.com/xing/flag_shih_tzu
+
+This plugin 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 where 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 "Shih Tzu" means:
+http://en.wikipedia.org/wiki/Shih_Tzu
+
+
+==Prerequisites
+
+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).
+
+The plugin has been tested with Rails versions from 2.1 to 2.3 and MySQL,
+PostgreSQL and SQLite3 databases.
+
+
+==Installation
+
+ cd path/to/your/rails-project
+ ./script/plugin install git://github.com/xing/flag_shih_tzu.git
+
+
+==Usage
+
+===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:
+
+ has_flags(1 => :warpdrive, :column => 'bits')
+
+
+===Generated instance methods
+
+Calling +has_flags+ as shown above creates the following instance methods
+on Spaceship:
+
+ Spaceship#warpdrive
+ Spaceship#warpdrive?
+ Spaceship#warpdrive=
+ Spaceship#shields
+ Spaceship#shields?
+ Spaceship#shields=
+ Spaceship#electrolytes
+ Spaceship#electrolytes?
+ Spaceship#electrolytes=
+
+
+===Generated named scopes
+
+The following named scopes become available:
+
+ 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)"
+ Spaceship.electrolytes # :conditions => "(spaceships.flags & 4 = 4)"
+ Spaceship.not_electrolytes # :conditions => "(spaceships.flags & 4 = 0)"
+
+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)
+
+
+===Support for manually building conditions
+
+The following class methods may support you when manually building
+ActiveRecord conditions:
+
+ 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.electrolytes_condition # "(spaceships.flags & 4 = 4)"
+ Spaceship.not_electrolytes_condition # "(spaceships.flags & 4 = 0)"
+
+
+===Example code
+
+ 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
+ ...
+
+
+==Running the plugin tests
+
+1. Modify <tt>test/database.yml</tt> to fit your test environment.
+2. If needed, create the test database you configured in <tt>test/database.yml</tt>.
+
+Then you can run
+
+ DB=mysql|postgres|sqlite3 rake test:plugins PLUGIN=flag_shih_tzu
+
+from your Rails project root or
+
+ DB=mysql|postgres|sqlite3 rake
+
+from <tt>vendor/plugins/flag_shih_tzu</tt>.
+
+
+==Authors
+
+{Patryk Peszko}[http://github.com/ppeszko],
+{Sebastian Roebke}[http://github.com/boosty],
+{David Anderson}[http://github.com/alpinegizmo]
+and {Tim Payton}[http://github.com/dizzy42]
+
+Please find out more about our work in our
+{tech blog}[http://blog.xing.com/category/english/tech-blog].
+
+
+==Contributors
+
+{TobiTobes}[http://github.com/rngtng],
+{Martin Stannard}[http://github.com/martinstannard],
+{Ladislav Martincik}[http://github.com/lacomartincik],
+{Peter Boling}[http://github.com/pboling],
+{Thorsten Boettger}[http://github.com/alto]
+
+
+==License
+
+The MIT License
+
+Copyright (c) 2009 {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.
Please sign in to comment.
Something went wrong with that request. Please try again.