DSL Options

background.txt

A wrapper contains "elements" (think of an XML element).
A wrapper has "slides" (variations on the elements within it).

An element might exist on every slide of the wrapper (on the 'master slide'),
or it might exist only on one of the slides.

An element has attributes.

* When an element exists only on a particular slide, the attributes also exist
  only on that slide. There is only one value for each attribute.
  
* When an element exists on the master slide, each attribute may either be
  "linked"—sharing the same value on every slide—or "unlinked", with a distinct
  value per slide.

Given a reference to an element, how should I write my DSL to provide access
to the attribute values, per slide (for master) and simply (for non-master)?

option1-convenience.rb

p cube.master?          #=> true     # this element lives on every slide
p bell.master?          #=> false    # this element lives on only one slide

p cube.slides.count     #=> 3        # the master, and two others
p cube.opacity.linked?  #=> false    # the 'opacity' attribute is unlinked
p cube.opacity          #=> ...      # a <ValuesPerSlide> proxy instance
p cube.opacity[0]       #=> 100      # 100% opacity on master slide
p cube.opacity[1]       #=> 75       # 75% opacity on slide 1
p cube.opacity[2]       #=> 0        # 0% opacity on slide 2
p cube.opacity.values   #=> [100,75,0]

p cube[0]               #=> ...      # A <SlideValues> proxy
p cube[0].opacity       #=> 100
p cube[1].opacity       #=> 75

p bell.opacity          #=> 80       # 1 slide, so no need for proxy

all_opacities = [cube,bell].flat_map do |el|
  el.master? ? el.opacity.values : [el.opacity] # OUCH
end

option2-explicitslide.rb

p cube.main_slide     #=> 0             # this element lives on the master slide
p bell.main_slide     #=> 2             # this element lives only on slide 2
                     
p cube['opacity']     #=> [100,75,0]    # an Array
p cube['opacity',0]   #=> 100           # 100% opacity on master slide
p bell['opacity']     #=> [nil,nil,80]  # doesn't exist on other slides
p bell['opacity',bell.main_slide]       #=> 80

all_opacities = [cube,bell].flat_map{ |el| el['opacity'] }.compact

# Or, if bell['opacity'] returned [80], unrelated to slide index:
all_opacities = [cube,bell].flat_map{ |el| el['opacity'] }

option3-metamagic.rb

p cube.opacity        #=> 100         ...pick the main slide value by default
p cube.opacity.class  #=> Fixnum      ...but with per-instance mixins
p cube.opacity[1]     #=> 75          ...letting me do things like this
p cube.opacity.values #=> [100,75,0]

p bell.opacity        #=> 80          ...yay, so simple
p bell.opacity.values #=> [80]        ...duck-type with elements on master

all_opacities = [cube,bell].flat_map{ |el| el.opacity.values }