manacle

Manacle is a library for the creation of 'sticky' constraints.

What is a 'sticky' constraint?

Say you changing pricing a product, and always want the price to end with 99.

Typically, when you modify the price, you'll have to redo the calculation to make it end in 99.

A 'sticky' constraint means you have to declare your intent once, and the price enforces its own constraint as you make changes, even changes that would otherwise make it not end in 99.

Quick Start

A common situation is to want to constrain a Time object in some way or another.

For example, say you want a Time value to always snap to the beginning of the day.

Defining the manacle

require 'manacle/constraint/method'

module Manacle
  module Examples
    class BeginningOfDay
      include ::Manacle::Constraint::Method

      # Defines what types of values this manacle can constrain
      def self.constrainables
        [ActiveSupport::TimeWithZone, ::Time, ::Date] 
      end

      # Defines the constraint to call each time the underlying object is modified.
      def constraint
        :beginning_of_day
      end
    end
  end
end

Using the manacle

time = Time.now
puts "1. Time in your timezone is #{time.to_s}"

# Manacle is applied here
bod = Manacle::Examples::BeginningOfDay.new(time).proxy
puts "2. Manacled time at beginning of the day is #{bod.to_s}"

bod_plus_one_hour = bod + 60*60
puts "3. Manacled time at BOD + 1 hour is #{bod_plus_one_hour.to_s}"

bod_plus_one_day = bod + 24*60*60
puts "4. Manacled time in BOD + 1 day is #{bod_plus_one_day.to_s}"

bod_plus_25_hours = bod + 25*60*60
puts "5. Manacled time in BOD + 25 hours is #{bod_plus_25_hours.to_s}"

If the time was 2014-08-27 21:42:21 -0700, this would print:

1. Time in your timezone is 2014-08-27 21:42:21 -0700
2. Manacled time at beginning of the day is 2014-08-27 00:00:00 -0700
3. Manacled time at BOD + 1 hour is 2014-08-27 00:00:00 -0700
4. Manacled time in BOD + 1 day is 2014-08-28 00:00:00 -0700
5. Manacled time in BOD + 25 hours is 2014-08-28 00:00:00 -0700

Unconstraining

This time is now constrained forever to be beginning of the day. Unless you don't want it to be.

You can unmanacle any object, by calling #unconstrain. From the example above:

unproxy = bod.unconstrain
unproxy_plus_one_hour = unproxy + 60*60

puts "Unmanacled time + 1 hour is #{unproxy_plus_one_hour.to_s}"

This would print:

Unmanacled time + 1 hour is 2014-08-27 22:58:33 -0700

API Documentation

See RubyDoc

Contributors

See Contributing for details.

License

See License for details.

azanar/manacle