Casino
Casino is a DSL which helps you interact with and explore your Mongoid::Document
collections, and helps you more easily use MongoDB's aggregation framework.
Casino works like this:
Build a class and include Casino::Collection
- This gives the class the following macros:
dimension
,focus
, andquestion
- The class also gains the following instance methods:
answer
,intersection
,projection
, andquery
- This gives the class the following macros:
Declare the parameters of your Casino class by defining it using the class-level macros. You must define at least one
focus
,dimension
, andquestion
- A
focus
is a class name or a list of class names where Casino can expect to find a Mongoid document API (in other words, a class which includesMongoid::Document
) - A
dimension
defines an area of interest for the focus by name, then points to a specificMongoid::Document
field with a symbol or string. This is usually something defined in the document model itself, but it can actually be anything, due to the schemaless nature of MongoDB. The third argument to a dimension is a symbol which points to anattr_accessor
or instance method on the class which provides an array ofquery
method invocations. This list represents the different facets of the dimension. - Finally, a
question
is a specific action you want to use once you've produced the documents that yourdimension
andfocus
combinations have resulted in. In order to tap into the current intersection being queried, Casino provides theintersection
helper, which is a combination of all the current dimension facets currently being questioned.
- A
Once defined, Casino will handle generation and querying of your generated collection from here on out.
The Casino API
Class (macro) methods
Dimension
- Arguments:
- Label: A "pretty name" for the dimension for easy display.
- Field: This is a string or symbol which indicates the dimension's target field.
- Queries: This is a symbol which references an instance method or accessor that produces an array of
Casino::Query
objects (built with thequery
instance method). - Approach: (optional) This is a hash which contains an
:operator
key, in case the dimension should query a field differently than the default (where
) query plan, for example,gt
, orand
, etc.
- Returns: A
Casino::Dimension
object. - What it does: The
dimension
class method creates aCasino::Dimension
object and registers it with theCasino::Collection
the parent class is a part of. From that point on, the dimension will be used as a factor in building out the following:- A generated collection key (
_id
). - The generated collection name.
- The intersections for the aggregation, where Casino will ask any questions it is given.
- A generated collection key (
Focus
- Arguments:
- Models: A class which includes the
Mongoid::Document
module.
- Models: A class which includes the
- Returns: A
Casino::Focus
object. - What it does: Creates a
Casino::Focus
object and registers it with theCasino::Collection
of the parent class. From that point on, the focus object is used in the following way:- The generated collection name.
- The targets for dimensional intersection questions.
- The subject material for aggregate data.
Question
- Arguments:
- Name: The name of the question, this is what the question will be registered under.
- Answer: This is a
:method_name
.
- Returns: A
Casino::Question
object What it does: Creates a
Casino::Question
object for the given arguments, and registers it with theCasino::Collection
of the parent class.A
Casino::Question
represents the actual operation which will be performed on a focus at a given dimensional intersection.When methods marked with the
question
macro are run, the following instance variables become available:answer
: An answer to another question at the current intersection.intersection
: The current intersection criteria.projection
: A MongoDB aggregation framework wrapper scoped to the current intersection.
Instance methods
Answer
- Arguments:
- Method name: A
:symbol
pointing to another question. This method returns the results of that question.
- Method name: A
- Returns: An answered question key/value pair:
{ question_name: question_answer }
Insert
- Arguments:
- Documents: Any argument passed in will be evaluated as though it were a
Mongoid::Document
of the collection's focus.
- Documents: Any argument passed in will be evaluated as though it were a
- Returns: Any results which were updated with the given documents.
- What it does:
insert
is a trickle-in mechanism, which updates any intersections which match a document.
Intersection
- Arguments: None
- Returns:
Mongoid::Criteria
- A window into the currently active criteria being questioned.
Projection
- Arguments: None
- Returns: A
Casino::Projection
object preloaded with the current intersection selector, which wraps around MongoDB's aggregation framework.
Query
- Arguments:
- Label: A string or symbol that indicates a field to store the query's results in
- Criterion: A list of items to use to search within the
question
field
- Returns: A
Casino::Query
instance for use to build outputs as well as to buildCasino::Intersection
objects with.
Results
- Arguments: None
- Returns: A list of answer hashes for every intersection. Casino persists intersection results to a generated MongoDB collection the first time it is used, and afterward will just combine already produced results with new results (in essence, it only queries for new information and remembers the rest).
Update
- Arguments: None
- Returns: Re-generates the entire generated collection.