spectifly 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.ruby-version

@@ -0,0 +1 @@
+1.9.3-p392

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specified in spectifly.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Ravi Gadad
+
+MIT License
+
+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.

data/README.md

@@ -0,0 +1,128 @@
+# Spectifly
+
+Say you've been tasked with building a web service that accepts a purchase
+order in XML format, adds some additional fields, sends the modified purchase
+order to another web service via JSON, receives a JSON response with fulfillment
+details, and finally sends back the same order with all this additional data
+back to the original client, via XML.  You've been given specifications for
+what fields the purchase order needs to have at every step of the process, and
+you need to validate the object differently for each transaction.
+
+Spectifly is here to help.  It's a library with a highly opinionated markup language (based on YAML) for specifying entities and their presentations (using
+`*.entity` files), and uses these entity specifications to generate XSDs, JSON
+validators, and fixture data for testing.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'spectifly'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install spectifly
+
+## Usage
+
+The Spectifly markup language is a subset of YAML. Only one root node is allowed
+per file (since a single `.entity` file represents a single business entity),
+and there are other restrictions, as well as additional features, which we'll
+discuss here.
+
+Here's an example entity:
+
+```YAML
+Widget:
+  Description: A widget produced by WidgetCo
+  Fields:
+    Name*:
+      Description: Display name of widget
+
+    Created At:
+      Description: When the widget was built
+      Type: DateTime
+
+    Awesome?:
+      Description: Whether or not the widget is awesome
+  Related Entities:
+    Belongs To:
+      Manufacturing Plant*:
+        Description: The WidgetCo location that constructed the widget
+        Type: Manufacturing Location
+    Has Many:
+      Accessories:
+        Description: Widget Add-ons that augment the widget's
+functionality
+        Type: Add On
+```
+
+The root node, `Widget:` above, is required, and there can be only one node at
+this level.
+
+Directly below the root node, the only valid nodes are `Description` and
+`Fields`.  The `Description` is a plain language description of the entity.  The `Related Entities` node includes associations to other entities, grouped by how the entity is related.
+
+### Fields
+
+`Fields` is a YAML tree with one or more field entries, which have their own
+specification.  The key of a field node is the field's name, and the value can
+either be null, or another tree with several possible keys, all of which are
+optional themselves:
+
+* `Description` (string): A plain-language description of the variable
+* `Multiple` (Boolean): Whether or not this variable can occur multiple times
+* `Type` (string): Type of data contained in this field (defaults to String)
+* `Validations` (string or list of strings): Restrictions on the values allowed
+  in this field
+* `Valid Values` (list of strings): List of possible literal values for this
+  field
+* `Minimum Value` (numeric): Minimum value allowed for this field (numeric
+  fields only)
+* `Maximum Value` (numeric): Maximum value allowed for this field (numeric
+  fields only)
+
+#### Special Tokens
+
+The key of the field node (the name of the field) can also end with one or two
+special "tokens":
+
+* The `*` token, as in the `Name*` field in the above example, makes the field
+  required, which means it must occur once (or at least once, for Multiple
+  fields).
+* The `?` token, as in the example's `Awesome?` field, sets `Type` to Boolean.
+
+These tokens can be combined, if you have a required Boolean field.
+
+If the `?` shortcut conflicts with the explicit key (e.g. a `Rad?` field with
+`Type: String`), an exception will be thrown during parsing.
+
+### Related Entities
+
+`Related Entities`, is a YAML tree that enumerates the entities with which the defined entity are associated.  They are grouped by type of relationship and include the name of the association and which type of entity that association links to.  Like `Fields`, the `*` special token can be used to mark an entity as required.
+
+* `Belongs To` is fairly straight-forward, i.e. a kitten belongs to a
+  litter of kittens
+
+* `Has One` also self-explanatory, i.e. a website user has one (and only
+  one) profile -- an inverse of `Belongs To`
+
+* `Has Many` also an inverse of `Belongs To`, but 1 or more
+
+* `Has and Belongs To Many` is a many-to-many relationship between two
+  entities, such as a dish being made up of many ingredients and an
+ingredient being part of many dishes
+
+Under each of these Association nodes the YAML tree lists entities that relate to
+the described entity in that way.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require 'spectifly/tasks'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+task :default => :spec

data/lib/entities/association.entity

@@ -0,0 +1,11 @@
+Association:
+  Description: The way in which an entity relates to another entity
+  Related Entities:
+    Has Many:
+      Entities:
+        Type: Entity
+        Description: The entity to which the given entity relates
+
+    Belongs To:
+      Related Entity*:
+        Description: The list of associations to entities that a given entity has

data/lib/entities/entity.entity

@@ -0,0 +1,16 @@
+Entity:
+  Description: A Spectifly entity definition
+  Fields:
+    Description:
+      Description: A plain-language description of the entity
+
+  Related Entities:
+    Has Many:
+      Fields*:
+        Description: Data variables associated with the given entity
+        Type: Field
+
+    Has One:
+      Related Entities:
+        Description: Entities associated with the given entity
+        Type: Related Entity

data/lib/entities/field.entity

@@ -0,0 +1,35 @@
+Field:
+  Description: A single data variable associated with an entity
+  Fields:
+    Description:
+      Description: A plain-language description of the variable
+
+    Multiple?:
+      Description: Whether or not this variable can occur multiple times
+
+    Type:
+      Description: Type of data contained in this field (defaults to String)
+
+    Validations:
+      Description: Restrictions on the values allowed in this field
+      Multiple: True
+      Valid Values:
+        - Must be positive
+        - Must be non-negative
+
+    Valid Values:
+      Description: List of possible literal values for this field
+      Multiple: True
+
+    Minimum Value:
+      Description: Minimum value allowed for this field (numeric fields only)
+      Type: Numeric
+
+    Maximum Value:
+      Description: Maximum value allowed for this field (numeric fields only)
+      Type: Numeric
+
+  Related Entities:
+    Belongs To:
+      Entity*:
+        Type: Entity

data/lib/entities/related_entity.entity

@@ -0,0 +1,28 @@
+Related Entity:
+  Description: Entities associated with the base entity
+  Related Entities:
+    Has One:
+      Belongs To:
+        Description: Entities that own one of the given entity.
+        Type: Association
+        Example: A comment belongs to a blog post
+
+      Has One:
+        Description: Entities that are owned by the given entity.  Given entity has one of these entities.
+        Type: Association
+        Example: A building has one address
+
+      Has Many:
+        Description: Entities that are owned by the given entity.  Given entity can have multiple of these entities.
+        Type: Association
+        Example: A book has many pages
+
+      Belongs To Many:
+        Description: Entities that own multiple of a given entitiy.
+        Type: Association
+        Example: a Street belongs to many addresses
+
+      Has and Belongs To Many:
+        Description: Entities that are associated with other entities.  Each given entity can have multiple of this entity and can also  belong to many of this entity.
+        Type: Association
+        Example: a Library user can borrow many books and a book can be borrowed by many library users

data/lib/spectifly.rb

@@ -0,0 +1,7 @@
+require_relative 'spectifly/support'
+require_relative 'spectifly/entity'
+require_relative 'spectifly/base'
+require_relative 'spectifly/configuration'
+
+module Spectifly
+end

data/lib/spectifly/base.rb

@@ -0,0 +1,8 @@
+require_relative 'base/builder'
+require_relative 'base/field'
+require_relative 'base/types'
+
+module Spectifly
+  module Base
+  end
+end

data/lib/spectifly/base/association.rb

@@ -0,0 +1,18 @@
+require_relative 'entity_node'
+
+module Spectifly
+  module Base
+    class Association < EntityNode
+      attr_reader :relationship
+
+      def initialize(field_name, options = {})
+        super
+        @relationship = options.delete(:relationship)
+      end
+
+      def multiple?
+        ['has_many', 'has_many_and_belongs_to'].include? relationship
+      end
+    end
+  end
+end

data/lib/spectifly/base/builder.rb

@@ -0,0 +1,102 @@
+require 'yaml'
+require_relative 'field'
+require_relative 'association'
+require_relative 'types'
+
+module Spectifly
+  module Base
+    class Builder
+      class << self
+        def from_path(path, options = {})
+          new(Spectifly::Entity.parse(path), options)
+        end
+
+        def module_name
+          Spectifly::Support.get_module(self)
+        end
+      end
+
+      def initialize(entity, options = {})
+        @options = options
+        @entity = entity
+      end
+
+      def present_as(presenter_entity)
+        @entity = @entity.present_as(presenter_entity)
+        self
+      end
+
+      def types
+        [fields.map(&:type) + associations.map(&:type)].flatten.compact.uniq
+      end
+
+      def native_types
+        @native_types ||= begin
+          eval("#{self.class.module_name}::Types::Native")
+        end
+      end
+
+      def utilized_extended_types
+        @utilized_extended_types ||= begin
+          extended_types = eval("#{self.class.module_name}::Types::Extended")
+          extended_types.select { |k, v| types.include?(k) }
+        end
+      end
+
+      def custom_types
+        types - native_types - utilized_extended_types.keys
+      end
+
+      def fields
+        @fields ||= begin
+          fields = []
+          @entity.fields.each do |name, attributes|
+            fields << field_class.new(name.dup, attributes.dup)
+          end
+          fields
+        end
+      end
+
+      def associations
+        @associations ||= begin
+          associations = []
+          @entity.relationships.each do |relationship_type, type_associations|
+            relationship_type = Spectifly::Support.tokenize(relationship_type)
+            type_associations.each do |name, attributes|
+              associations << association_class.new(
+                name.dup, attributes.dup.merge(:relationship => relationship_type)
+              )
+            end
+          end
+          associations
+        end
+      end
+
+      def utilized_extended_type_fields
+        @utilized_extended_type_fields ||= begin
+          fields = []
+          utilized_extended_types.each do |name, attributes|
+            fields << field_class.new(name.dup, attributes.dup)
+          end
+          fields
+        end
+      end
+
+      def root
+        @entity.root
+      end
+
+      def field_class
+        eval("#{self.class.module_name}::Field")
+      end
+
+      def association_class
+        eval("#{self.class.module_name}::Association")
+      end
+
+      def build
+        raise 'Subclass Responsibility'
+      end
+    end
+  end
+end

data/lib/spectifly/base/configuration.rb

@@ -0,0 +1,19 @@
+module Spectifly
+  module Base
+    class Configuration
+      def initialize(config = {})
+        @entity_path = config.fetch(:entity_path)
+        @presenter_path = config[:presenter_path]
+      end
+
+      def presenter_path
+        @presenter_path ||= begin
+          proposed_path = File.join(@entity_path, 'presenters')
+          if Dir.exists?(proposed_path)
+            @presenter_path = proposed_path
+          end
+        end
+      end
+    end
+  end
+end