gorillib 0.4.2pre → 0.4.2

data/notes/model-overlay.md

@@ -1,209 +0,0 @@
-# gorillib/record/overlay (WIP -- NOT READY YET) -- Progressively overlayed configuration
-
-`Record::Overlay` lets you specify an ordered stack of attributes, each overriding the following. For example, you may wih to load your program's configuration using
-
-     (wins) value set directly on self
-            commandline parameters
-            environment variables
-            per-user config file
-            machine-wide config file
-    (loses) application defaults
-
-In the Ironfan toolset, servers are organized into hierarchical groups -- 'provider', then 'cluster', then 'facet'. Its configuration builder lets you describe a cloud server as follows:
-
-     (wins) server-specific
-            facet
-            cluster
-            provider
-    (loses) default
-
-### Higher layers override lower layers
-
-In the following example, we set a value for the `environment` attribute on the cluster, then override it in the facet:
-
-    cluster :gibbon do |c|
-      c.environment  :prod
-
-      c.facet :worker do |f|
-        # since no value has been set on the facet, a read pokes through to the cluster's value
-        f.environment                 #=> :prod
-        # setting a value on the facet overrides the value from the cluster:
-        f.environment :dev
-        f.environment                 #=> :dev
-      end
-    end
-
-This diagram might help, for a hypothetical 'owner' setting in confilgiere:
-
-     Settings:
-                                   +-- reads come in from the top
-     _______________________       |
-     | .owner               |     \|/
-     +----------------------+------------------+
-     | self                 |                  |
-     | overlay(:commandline)  |                  |
-     | overlay(:env_vars)     |    'bob'         | <-- writes go in from the side
-     | overlay(:user_conf)    |                  |
-     | overlay(:system_conf)  |    'alice'       | <--
-     | default, if any      |                  |
-     +----------------------+------------------+
-
-In this diagram, values have been set on the objects at the 'env_vars' and 'system_conf' layers, so when you read the final settings value with `Settings.owner` it returns `"bob"`. If the user had specified `--owner="charlie"` on the commandline, it would have set a value in the 'commandline' row and taken precedence; `Settings.owner` would return `"charlie"` instead.
-
-### Late Resolution means overlays are dynamic
-
-Overlay layers are late-resolved -- they return whatever value is appropriate at time of read:
-
-    cluster(:gibbon) do |c|
-      c.environment(:prod)
-      # since no value has been set on the facet, a read pokes through to the cluster's value
-      c.facet(:worker).environment      #=> :prod
-
-      # changing the cluster's value changes the facet's effective value as well:
-      c.environment(:test)
-      c.facet(:worker).environment      #=> :test
-    end
-
-## Defining an Overlay
-
-You can apply overlay behavior to any `Gorillib::Record`: the `Builder`, `Model` and `Bucket` classes, or any diabolical little variant you've cooked up.
-
-An Overlay'ed object's `read_unset_attribute` calls `super`, so if there is a default value but neither the object nor any overlay have a value set,
-
-## Cascading attributes
-
-I want to be able to define what's uniform across a collection at one layer, and customize only what's special at another. In this example, our overlay stack is `cluster > facet`; each has a `volumes` collection field. The `:master` facet overrides the size and tags applied to the volume; in the latter case this means modifying the value read from the cluster layer and applying it to the facet layer:
-
-    ```ruby
-    cluster :gibbon do
-      volumes(:hadoop_data) do
-        size            300
-        mount_point     '/hadoop_data'
-        tags( :hadoop_data => true, :persistent => true, :bulk => true)
-      end
-      # the master uses a smaller volume and only stores data for the namenode
-      facet :master do
-        volumes(:hadoop_data) do
-          size            50
-          tags            tags.except(:hadoop_data).merge(:hadoop_namenode_data => true)
-        end
-      end
-      # workers use the volume just as described
-      facet :worker
-        # ...
-      end
-    end
-    ```
-
-_note_: This does not feel elegant at all.
-
-    class Facet
-      attr_accessor  :cluster
-      overlays       :cluster
-      collection     :volumes, Volume, :members_overlay => :cluster
-    end
-
-When a collection element is built on the
-
-
-## Deep Merge
-
-
-
-## Dynamic Resolution Rules
-
-As you've seen, the core resolution rule is 'first encountered wins'. Simple and predictable, but sometimes insufficient.
-
-Define your field with a `:combine_with` block (or anything that responds to `#call`) to specify a custom resolution rule:
-
-    Settings.option :flavors, Array, :of => String, :combine_with => ->(obj,attr,layer_vals){ ... }
-
-Whenever there's a conflict, the block will be called with these arguments:
-
-* the host object,
-* the field name in question,
-* a list of the layer values in this order:
-  - field default (if set)
-  - lowest layer's value (if set)
-  - ...
-  - highest layer's value (if set)
-  - object's own value (if set)
-
-If you pass a symbol to `:combine_with`, the corresponding method will be invoked on each layer, starting with the lowest-priority:
-
-    Settings.option :flavors, Array, :of => String, :combine_with => :concat
-    # effectively performs
-    # layer(:charlie).flavors.
-    #   concat( layer(:bob).flavors ).
-    #   concat( layer(:alice).flavors )
-
-    Settings.option :flavors, Hash,  :of => String, :combine_with => :merge
-    # effectively performs
-    # layer(:charlie).flavors.
-    #   merge( layer(:bob).flavors ).
-    #   merge( layer(:alice).flavors )
-
-Notes:
-* a field's default counts as a layer: the combiner is invoked even if just the default and a value are present.
-* normal (first-encountered-wins) resolution uses `read_unset_attribute`
-* dynamic (explicit-block) resolution uses `read_attribute`
-* there's not a lot of sugar here, because my guess is that concat'ing arrays and merging or deep-merging hashes covers all the repeatable cases.
-
-__________________________________________________________________________
-__________________________________________________________________________
-__________________________________________________________________________
-
-
-## Decisions
-
-* Layer *does not* catch `Gorillib::UnknownFieldError` exceptions -- a layered field must be defined on each part of the layer stack.
-* a field's default counts as a layer: the combiner is invoked even if just the default and a value are present
-
-__________________________________________________________________________
-
-**Provisional**:
-
-## LayeredObject -- push some properties through to parent; earn predictable deep merge characteristics
-
-* holds a stack of objects
-* properties 'poke through' to get value with well-defined resultion rules
-* you can define a custom resolution rule if you define a property, or when you set its value
-
-* Properties are resolved in a first-one-wins
-* Defined properties can have resolution rules attached
-* You can put yourself in an explicit scope; higher properties are set, lower ones appear unset
-
-Server overlays facet
-Facet overlays cluster
-Cluster overlays provider
-
-don't prescribe *any* resolution semantics except the following:
-
-* layers are evaluated in order to create a composite, `dup`ing as you go.
-* while building a composite, when a later layer and the current layer collide:
-  - if layer has merge logic, hand it off.
-  - simple + any:      clobber
-  - array + array:     layer value appended to composite value
-  - hash  + hash:      recurse
-  - otherwise:         error
-
-###  no complicated resolution rules allowed
-
-This is the key to the whole thing.
-
-* You can very easily
-* You can adorn an object with merge logic if it's more complicated than that
-
-(?mystery - duping: I'm not certain of the always-`dup` rule. We'll find out).
-
-How do volumes overlay?
-
-Which direction is overlay declared?
-
-Configliere:
-
-* Default
-* File
-* Env var
-* Cmdline
-* Setting it directly

data/notes/model.md

@@ -1,135 +0,0 @@
-# gorillib/record -- construct lightweight structured data classes
-
-## Goals
-
-* light, predictable magic; you can define records without requiring everything & the kitchen sink.
-* No magic in normal operation: you are left with regular instance-variable attrs, control over your initializer, and in almost every respect can do anything you'd like to do with a regular ruby class.
-* Compatible with the [Avro schema format](http://avro.apache.org/)'s terminology & conceptual model
-* Upwards compatible with ActiveSupport / ActiveModel
-* All four obey the basic contract of a Gorillib::Record
-* Encourages assertive code -- no `method_missing` or complex proxy soup.
-
-___________________________________________________________________________
-
-## Gorillib::Record
-
-### Defining a record
-
-To make a class a record, simply `include Gorillib::Record`.
-
-      ```ruby
-      class Place
-        include Gorillib::Record
-        field :name, String
-        field :geo, GeoCoordinates, :doc => 'geographic location of the place'
-      end
-      ```
-
-### Field
-
-A record has `field`s that describe its attributes. The simplest definition just requires a field name and a type: `field :name, String`. (Use `Object` as the type to accept any value as-is). Specify optional attributes using keyword arguments -- for example, `doc` describes the field:
-
-      ```ruby
-        field :geo, GeoCoordinates, :doc => 'geographic location of the place'
-      ```
-
-You can list the fields, the field names (in the order they were defined), and ask if a field has been defined:
-
-      ```ruby
-      Place.fields             #=> {:name=>field(:name, Integer), :geo=>field(:geo, Geocoordinates)}
-      Place.field_names        #=> [:name, :geo]
-      Place.has_field?(:name)  #=> true
-      ```
-
-Subclasses inherit their parent's fields, just as you'd expect:
-
-      ```ruby
-      class Stadium < Place
-        field :capacity, Integer, :doc => 'quantity of seats'
-      end
-      Stadium.field_names #=> [:name, :geo, :capacity]
-
-      # Add a field to the parent and it shows up on the children, no sweat:
-      Place.field :country_id, String
-      Place.field_names   #=> [:name, :geo, :country_id]
-      Stadium.field_names #=> [:name, :geo, :capacity, :country_id]
-      ```
-
-### Reading, writing and unsetting values
-
-Defining a field defines accessor methods:
-
-      ```ruby
-      lunch_spot = Place.receive({ :name => "Torchy's Tacos", :country_id => "us",
-        :geo => { :latitude => "30.295", :longitude => "-97.745" }})
-
-### Attributes
-
-(A class defines `fields`; instances receive `value`s for those fields; the collection of an instance's `values` form its `attributes`)
-
-## Contract
-
-Every record responds to and guarantees uniform behavior for these methods:
-
-* Class methods from `Gorillib::Record`     -- `field`, `fields`, `field_names`, `has_field?`, `metamodel`
-* Instance methods from `Gorillib::Record`  -- `read_attribute`, `write_attribute`, `unset_attribute`, `attribute_set?`, `read_unset_attribute`, `attributes`
-
-Records generally respond to the following, but are allowed to get fancy as long as they fulfill your basic expectations (and can mark accessors private/protected or omit them):
-
-* Class methods from `Gorillib::Record`     -- `receive`, `inspect`
-* Instance methods from `Gorillib::Record`  -- `receive!`, `update`, `inspect`, `to_s`, `==`
-* Metamodel methods (eg, field named 'foo') -- `receive_foo`, `foo=`, `foo`
-
-These are the only
-
-* `Object#blank?`, `Hash#symbolize_keys`, `Object#try`
-
-### `read_attribute`, `write_attribute` and friends
-
-All normal access to attributes goes through `read_attribute`, `write_attribute`, `unset_attribute` and `attribute_set?`. All 'fixup' access goes through each field's `receive_XXX` method, which calls `write_attribute` in turn. This provides a consistent attachment point for advanced magic.
-
-     external methods             fixup gate          accessor gate
-
-     Klass.receive           => receive_foo(val) => write_attribute(:foo, val)
-     receive!(:foo => val)   => receive_foo(val) => write_attribute(:foo, val)
-                                receive_foo(val) => write_attribute(:foo, val)
-     update_attributes(:foo => val)              => write_attribute(:foo, val)
-     foo=(val)                                   => write_attribute(:foo, val)
-
-     attributes                                  => read_attribute(:foo)
-     foo                                         => read_attribute(:foo)
-
-                                                    attribute_set?(:foo)
-                                                    unset_attribute(:foo)
-
-If you are writing library code to extend `Gorillib::Record`, you *must* call the `xx_attribute` methods -- do not assume any behavior from (or even the existence of) accessors or anything else. By default, the core `xx_attribute` methods get/set/remove instance variables, but we've deliberately left them open to be implemented as hash values, by delegation, as a passthrough to database access, or things as-yet undreamt of. That's just for library code, though -- your class knows how it's built and can naturally leverage all its amenities.
-
-If you call `read_attribute` on an unset value, it in turn calls `read_unset_attribute`; the mixins that provide defaults, lazy access, or layered configuration hook in here.
-
-
-### method visibility
-
-You can mark a field's methods (`:reader`, `:writer`, `:receiver`) as public, private or protected, or even prevent its creation in the first place:
-
-    field :monogram, String, :writer => false, :receiver => :protected # a read-only field
-
-Visibility can be `:public`, `:protected`, `:private`, `true` (meaning `:public`) or `false` (in which case no method is manufactured at all).
-
-### extra_attributes
-
-Extra attributes passed to `receive!` are collected in `@extra_attributes`, but nothing is done with them.
-
-
-## Record::Default
-
-
-* default values
-  - nil by default
-  - simple value is returned directly
-  - Proc is `call`ed: `->{ Time.now }`
-    - to return a block as default, just wrap it in a dummy block: `->{ ->(obj,fn){  } }`
-    - The block may store an attribute value if desired, but must do so explicitly; otherwise, the block will be invoked on every access while the value is unset.
-  - how to invoke?
-    - foo_default
-    - attribute_default(:foo)
-    - field(:foo).default(self)

data/notes/structured-data-classes.md

@@ -1,127 +0,0 @@
-# gorillib's structured data classes -- Record, Model, Builder and Bucket
-
-## Overview
-
-Gorillib provides these general flavors of model:
-
-* `Gorillib::Record`: **lightweight structured records**. Easily assemble a dynamic data structure that enables both rich behavior and generic manipulation, serialization and transformation. Especially useful when you just need to pull something from JSON, attach some functionality, and get it back on the wire.
-
-      ```ruby
-      class Place
-        include Gorillib::Record
-        # fields can be simple...
-        field :name, String
-        field :country_id, String, :doc => 'Country code (2-letter alpha) containing the place'
-        # ... or complext
-        field :geo, GeoCoordinates, :doc => 'geographic location of the place'
-      end
-      
-      class GeoCoordinates
-        include Gorillib::Record
-        field :latitude,  Float, :doc => 'latitude in decimal degrees; negative numbers are south of the equator'
-        field :longitude, Float, :doc => 'longitude in decimal degrees; negative numbers are west of Greenwich'
-      end
-
-      # It's simple to instantiate complex nested data structures
-      lunch_spot = Place.receive({ :name => "Torchy's Tacos", :country_id => "us",
-        :geo => { :latitude => "30.295", :longitude => "-97.745" }})
-      ```
-
-* `Gorillib::Model`: **rich structured models** offering predictable magic with a disciplined footprint. Comparable to ActiveRecord or Datamapper, but for a world dominated by JSON+HTTP, not relational databases
-
-      ```ruby
-      class GeoCoordinates
-        include Gorillib::Model
-        field :latitude,  Float, :doc => 'latitude in decimal degrees; negative numbers are south of the equator', :validates => { :numericality => { :>= =>  -90, :<= =>  90  } }
-        field :longitude, Float, :doc => 'longitude in decimal degrees; negative numbers are west of Greenwich', :validates => { :numericality => { :>= => -180, :<= => 180  } }
-      end
-      position = GeoCoordinates.from_tuple(30.295, -97.745)
-      # A Gorillib::Model obeys the ActiveModel contract
-      GeoCoordinates.model_name.human # => 'Geo coordinates'
-      ```
-
-* `Gorillib::Builder`: **foundation models for elegant ruby DSLs** (Domain-Specific Languages). Relaxes ruby syntax to enable highly-readable specification of complex behavior.
-
-      ```ruby
-      workflow(:bake_pie) do
-        step   :make_crust
-        step   :add_filling
-        step   :bake
-        step   :cool
-      end
-      ```
-
-* `Gorillib::Bucket` (?name?): **record-style access to freeform hashes**. Provide a disciplined interface on top of arbitrarily-structured data. Used by [[Configliere]] and others.
-
-       ```ruby
-       # pre-defining a field gives you special powers...
-       Settings.define :port,   Integer, :doc => 'API server port number', :default => 80
-       # but you can still store or read anything you'd like...
-       Settings[:shout] = "SAN DIMAS HIGH SCHOOL FOOTBALL RULES"
-       # and treat the object as a hash when you'd like to
-       conn = Connections.open(Settings.merge(user_overrides))
-       ```
-
-## Decisions
-
-* **initializer** - *does not* inject an initializer; if you want one, do `alias_method :initialize, :receive!`
-* **frills** --
-  - *does inject*: `inspect` on the class, `inspect`, `to_s` on the instance
-  - *does inject*: accessors (`foo`, `foo=`) for each field.
-  - *does inject*: `==` on the instance
-  - *does not define*: `schema`, `initialize`
-* **field defaults** - evaluated on first read, at which point its value is fixed on the record.
-
-* **define_metamodel_record** -- visibility=false does not remove an existing method from the metamodel
-
-* ?? **hash vs mash** -- does `attributes` return a mash or hash?
-* are these basic functionality:
-  - **extra_attributes** -- ??
-  - **default**          -- ??
-
-* Record:
-  - class methods -- `field`, `fields`, `field_names`, `has_field?`, `metamodel`, `receive`, `inspect`
-  - instance methods  -- `read_attribute`, `write_attribute`, `unset_attribute`, `attribute_set?`, `attributes`, `receive!`, `update`, `inspect`, `to_s`, `==`
-  - with each attribute  -- `receive_foo`, `foo=`, `foo`
-
-* Builder:
-  - defining classes before they're used
-
-
-## Features
-
-### `Record`
-
-* `Record::Ordered`       -- sort order on fields (and thus record)
-* `Record::FieldAliasing` -- aliases for fields and receivers
-* `Record::Defaults`      -- default values
-* `Record::Schema`        -- icss schema
-* `Record::HashAccessors` -- adds `[]`, `[]=`, `delete`, `keys`, `#has_key?`, `to_hash`, and `update`. This allows it to be `hashlike`, but you must include that explicitly.
-* `Record::Hashlike`      -- mixes in `Record::HashAccessors` and `Gorillib::Hashlike`, making it behave in almost every respect like a hash. Use this when you want something that will *behave* like a hash but *be* a record. If you want something to *be* a hash but *behave* like a record, use the `Gorillib::MashRecord`
-
-### `Builder`
-
-* `Builder::GetsetField`  --
-
-### `HashRecord`
-
-### `Model`
-
-* `Model::Naming`
-* `Model::Conversion`     --
-
-### active_model / active_model_lite
-
-From `active_model` or `active_model_lite`:
-
-* `Model::Callbacks`      --
-* `Model::Dirty`          --
-* `Model::Serialization`  --
-* `Model::Validations`    -- implies `Model::Errors`, `Model::Callbacks`
-
-
-## Why, in a world with ActiveRecord, Datamapper, Hashie, Struct, ..., do we need yet another damn model framework?
-
-ActiveRecord and Datamapper excel in a world where data (and truth) live in the database. ActiveRecord sets the standard for elegant magic, but is fairly heavyweight (I don't want to include a full XML serialization suite just so I can validate records). This often means it's overkill for the myriad flyweight scripts, Goliath apps, and such that we deploy. Datamapper does a remarkable job of delivering power while still being light on its toes, but ultimately is too tightly bound to an ORM view of the world. Hashie, Structs and OStructs behave as both hashes and records. In my experience, this interface is too generous -- their use leads to mealymouthed code.
-
-More importantly, our data spends most of its time on the wire or being handled as an opaque blob of data; a good amount of time being handled as a generic bundle of properties; and (though most important) a relatively small amount of time as an active, assertive object. So type conversion and validation are fundamental actions, but shouldn't crud up my critical path or be required. Models should offer predictable and disciplined features, but be accessable as generic bags of facts.