universe_compiler 0.3.12 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 70b8ec67002e1f93718039b8b235496d77950b82
-  data.tar.gz: 683e846c95e2a3f631d7c3a530d6d24c5b7fee67
+  metadata.gz: d32cb08d065dc49ae220b4f681c37719f8cad091
+  data.tar.gz: 97af0f860e453d852d9a77ff69d52e350dd2ec88
 SHA512:
-  metadata.gz: 5c5708b1d764c28ada1c2ef1e9b0b33855ef86ecfdfd61272a316f1562cc8401499fe5b3d2e53a5436151899d34098a7fa6f47d631e013734a624819393cc15b
-  data.tar.gz: b56bf36861ccbfac2e7f6102d22765b9db7c20243a4ed23a7d2d752c3723deb48e470ce15e602fe02a83b44ab1689b9e98a9cd1b31835e4428e68280edb5f01e
+  metadata.gz: 700546bad667dedb998bb527ac6fd19c815cb870ccf82d77fb3c42c8927c7ffe915b122a3ef592bd805ca3358fee054ff3c0bfb4dde4c2a5f4740b6f09b4b977
+  data.tar.gz: 9a5fce641199557bb8e9fdfbbaa483554d4e2e28ba38078b2757417977b079ab9ba160f83b0f4d52302f430c0276804c51770e47ad150acdb88d6e33bb49ba62

data/README.md

@@ -8,9 +8,13 @@ UniverseCompiler
 - [Core Concepts](#core-concepts)
     - [Entities](#entities)
         - [Overview](#overview-1)
-            - [Special directives](#special-directives)
-            - [Constraints and relationships directives](#constraints-and-relationships-directives)
-        - [Compilation](#compilation)
+        - [Special directives](#special-directives)
+        - [Constraints directives](#constraints-directives)
+        - [Relational directives](#relational-directives)
+            - [Basic relations](#basic-relations)
+            - [Advanced relations](#advanced-relations)
+        - [Validations](#validations)
+    - [Compilation](#compilation)
     - [Inheritance](#inheritance)
     - [Overrides](#overrides)
 - [Generate a graph of entities using `Graphviz`](#generate-a-graph-of-entities-using-graphviz)
@@ -135,7 +139,7 @@ a.valid? # => false, not compliant with regexp specified
 a.bar = 'Yo man'
 a.valid? # => true
 ```
-#### Special directives
+### Special directives
 
 By default every entity has a `type`. It is available using the `#type` instance method or the
 `::entity_type` class method. The default value for the entity type is coming
@@ -166,7 +170,7 @@ EntityD.new # => #<EntityD:46943375641700 composite_key=["entity_d", "my_seed_2"
 ```
 
 
-#### Constraints and relationships directives
+### Constraints directives
 
 The generic form to declare a field is the `field` statement. Any constraint can be declared using the `field`
 method. Here is the signature:
@@ -187,11 +191,6 @@ Then some methods taking parameter:
 * should_match 
 * class_name
 
-You have as well relationship methods:
-
-* has_one
-* has_many
-
 So for each of these methods can be used either as "real" methods or as `field` parameter. For example:
 ```ruby
 class MyEntity < UniverseCompiler::Entity::Base
@@ -206,9 +205,159 @@ class MyEntity < UniverseCompiler::Entity::Base
 end
 ```
 Notice the fact that in the latter form `my_field` is "declared" more than once.  
+
+### Relational directives
+
+#### Basic relations
+
+`universe_compiler` provides two relational directives
+
+* has_one
+* has_many
+
+They specify relations to other entities and work both mainly the same way.
+
+In it's simplest form you can define:
+
+```ruby
+class MyEntity < UniverseCompiler::Entity::Base
+  has_one :another_entity_type
+  not_null :another_entity_type
+  has_one AnotherEntityClass
+  has_many :bar
+end
+```
+
+:information_source: You can notice that you can specify either an entity type or an entity class.
+
+:information_source: You can use `not_null` and `not_empty` with `has_one` directives, **but on a separated declaration**. With `has_many` you can use `not_empty` (you could use `not_null` but it would always be satisfied as by default a `has_many` relation returns an empty array).
+
+For `has_one`, the accessors generated are like for `field`. With the previous class, for `has_many` the accessors are _pluralized_ (like in activerecord).
+
+```ruby
+e = MyEntity.new fields: {name: :foo}
+# You can then issue
+e.another_entity_type # =>nil
+e.another_entity_type = ...
+e.another_entity_class # =>nil
+e.bars # =>[]
+```
+
+You can notice the `has_one` accessors defined using a class rather than an entity type, has been _camelized_.
+:warning: Notice the `has_many` directive generated _pluralized_ accessors !
+
+This is the default behaviour, but you can override this using the `name` option (for both `has_one` and `has_many`):
+
+```ruby
+class MyEntity < UniverseCompiler::Entity::Base
+  has_one :another_entity_type, name: :better_name
+  has_many :foo, name: :bars
+end
+```
+:warning: with the `has_many` directive if you specify a `name`, the accessors name is **not pluralized** (hence there, we specify the name as being `bars` and not `bar`).
+
+```ruby
+# You can then issue
+e.bettername # =>nil
+e.bars # =>[]
+```
+
+:information_source: Of course like any other field, you can still use the internal `fields`:
+
+```ruby
+e.bettername == e.fields[:bettername]
+e.bettername == e.[:bettername]
+e.bars == e[:bars]
+```
+
+#### Advanced relations
+
+Sometimes you may want entities _targeted_ by `has_one` or `has_many` relations to _be aware_ of this fact. **You can then implement complex relations without duplicating information**.
+
+This is called **reverse methods**.
+
+**:warning: This can only work within a universe !**
+
+```ruby
+class EntityA < UniverseCompiler::Entity::Base
+  auto_named_entity_type
+  entity_type :leaf
+end
+
+class EntityB < UniverseCompiler::Entity::Base
+  entity_type :root
+end
+
+class EntityC < UniverseCompiler::Entity::Base
+  entity_type :tree
+
+  has_one :root, with_reverse_method: :tree, unique: true
+  has_many :leaf, name: :leaves, with_reverse_method: :trunk, unique: true
+end
+```
+
+:warning: When you declare a reverse method using the `with_reverse_method` option, **an extra method is created on the target entity class**, not the one containing the has_one/many directive !
+
+It allows the following kind of code:
+
+```ruby
+u = UniverseCompiler::Universe::Base.new
+t = EntityC.new fields: {name: :my_tree}
+u << t
+(1..10).each {|_| l = EntityA.new ; t.leaves << l ; u << l }
+
+t.leaves
+#=> [#<EntityA:47410094357440 composite_key=[:leaf, #"2aad17a4-096c-4de5-9be0-ee80ef522b2b"], @universe='Unnamed #Universe'>,
+# #<EntityA:47410094356680 composite_key=[:leaf, #"56500c9f-0e64-4a48-9894-0e4e485ab001"], @universe='Unnamed #Universe'>,
+# #<EntityA:47410094355880 composite_key=[:leaf, #"2d5eeabb-e237-4741-8c44-0e2e9636b811"], @universe='Unnamed #Universe'>,
+# #<EntityA:47410094355100 composite_key=[:leaf, #"f17d7aa1-c505-4594-889a-e3d4f8813246"], @universe='Unnamed #Universe'>,
+# #<EntityA:47410094354340 composite_key=[:leaf, #"268d8a0c-cb28-42a0-85ab-2dd6217e6e6f"], @universe='Unnamed #Universe'>,
+# #<EntityA:47410094353560 composite_key=[:leaf, #"8d822cde-30d4-4841-bd0a-a1570583c355"], @universe='Unnamed #Universe'>,
+# #<EntityA:47410094352740 composite_key=[:leaf, #"dfffe2c2-b283-47ec-b799-3ef79c8584b4"], @universe='Unnamed #Universe'>,
+# #<EntityA:47410094351940 composite_key=[:leaf, #"c8c111da-ad70-412e-9f2c-7af11894641c"], @universe='Unnamed #Universe'>,
+# #<EntityA:47410094351140 composite_key=[:leaf, #"e1158988-6659-426e-912c-73f827e7429f"], @universe='Unnamed #Universe'>,
+# #<EntityA:47410094350360 composite_key=[:leaf, #"64b0e4c6-a718-43b9-ae8f-beeea5145c20"], @universe='Unnamed #Universe'>]
+t.leaves.last.trunk
+# => #<EntityC:47410094828200 composite_key=[:tree, :my_tree], @universe='Unnamed Universe'>
+t.leaves.last.fields
+# => {:name=>"c881f93d-7216-49a0-a7d4-b5a2a4a314d4"}
+t.leaves.last.respond_to? :trunk
+# => true
+```
+
+You can then notice that any _leaf_ has a new `trunk` method which returns the entity it is referenced from (in this case the _tree_ entity). **The fields themselves are not modified !**
  
 
-### Compilation
+What happens if multiple entities reference the same entity ?
+
+```ruby
+t2 = EntityC.new fields: {name: :oak}
+u << t2
+# And let's insert on entity A already added to t
+t2.leaves << t.leaves.last
+t.leaves.last.trunk
+# UniverseCompiler::Error: 'leaf/18693021-c0a3-4e47-be89-291850d7a0ff#trunk' should return only one 'tree' !
+```
+
+An exception is returned. the `unique` option actually specifies that only one entity should reference it !
+If you don't specify this option, an array is returned instead and this check is not performed.
+
+### Validations
+
+Every constraint defined on a field or a relation is enforced when an entity is validated (which is as well true when saving it). Continuing on previous example:
+
+```ruby
+t.leaves.last.valid?
+# => false
+t.leaves.last.valid? raise_error: true
+# UniverseCompiler::Error: Invalid entity '[:leaf, "0ecd1283-e98e-43ec-943b-b92e2e8ffa2b"]' for fields trunk !
+
+```
+
+:information_source: Here above is just an example regarding the reverse methods but any constraint added to an entity is enforced at validation time (`not_null`, `is_hash`... all of them).
+
+
+## Compilation
 
 The compilation mechanism is related to universes.
 When compiling a universe it actually:

data/lib/universe_compiler/entity.rb

@@ -26,6 +26,7 @@ module UniverseCompiler
       def initialize(fields: {}, universe: nil)
         @fields = fields
         define_known_fields_accessors
+        define_reverse_methods
         self.universe = universe
         self.fully_resolved = true
         if universe.nil?

data/lib/universe_compiler/entity/field_constraint_management.rb

@@ -75,8 +75,6 @@ module UniverseCompiler
 
       end
 
-      private
-
       def define_constraint(field_name, constraint_name = nil, value = nil)
         fields_constraints[field_name] ||= {}
         check_constraints_incompatibilities(field_name, constraint_name)
@@ -85,6 +83,14 @@ module UniverseCompiler
         end
       end
 
+      private
+
+      def define_constraints_on_target_entity_type(target_entity_type, source_field, reverse_method = nil)
+        target_class = UniverseCompiler::Entity::TypeManagement.types_classes_mapping[target_entity_type]
+        raise 'NOT IMPLEMENTED'
+      end
+
+
       def check_constraints_incompatibilities(field_name, constraint_name)
         unless INCOMPATIBLE_CONSTRAINTS[constraint_name].nil?
           INCOMPATIBLE_CONSTRAINTS[constraint_name].each do |incompatible_constraint|

data/lib/universe_compiler/entity/field_management.rb

@@ -3,11 +3,67 @@ module UniverseCompiler
 
     module FieldManagement
 
-
       private
 
+      def define_reverse_methods
+        self.class.fields_constraints.each do |method_name, constraints|
+          next unless constraints[:reverse_method]
+
+          define_reverse_method method_name, constraints[:reverse_method]
+        end
+      end
+
+      def define_reverse_method(default_method_name, method_definition_constraints)
+        metaclass = class << self; self ; end
+        method_name = normalize_method_name(default_method_name, method_definition_constraints)
+        UniverseCompiler.logger.debug 'Defining reverse method "%s" on class %s (%s)' % [method_name, metaclass, self.type]
+        raise UniverseCompiler::Error, "'#{method_name}' already exists on class '#{metaclass}'. Skipped !" if self.respond_to? method_name
+        method_definition_constraints[:actual_method] = method_name
+
+        check_operation = case method_definition_constraints[:relation_type]
+                          when :has_one
+                            '=='.to_sym
+                          when :has_many
+                            'include?'.to_sym
+                          end
+
+        metaclass.instance_eval do
+          define_method method_name do
+            raise UniverseCompiler::Error, "Entity '#{as_path}' is not in a universe. Reverse methods can't work !" if universe.nil?
+
+            res = universe.get_entities(criterion: :by_type, value: method_definition_constraints[:source_entity]).select do |entity|
+              entity[method_definition_constraints[:source_field]].send check_operation, self
+            end
+            return res if res.nil? || res.empty?
+
+            if method_definition_constraints[:unique_result]
+              if res.size == 1
+                return res.first
+              else
+                UniverseCompiler.logger.warn 'Too many results. Must be one or none !'
+                UniverseCompiler.logger.debug res.inspect
+                raise UniverseCompiler::Error, "'#{self.as_path}##{method_name}' should return maximum one '#{method_definition_constraints[:source_entity]}' !"
+              end
+            end
+
+            res
+          end
+        end
+      end
+
+
+
+      def normalize_method_name(default_method_name, method_definition_constraints)
+        if default_method_name == method_definition_constraints[:source_entity]
+          "referenced_from_#{method_definition_constraints[:source_entity]}_entities"
+        else
+          default_method_name
+        end
+      end
+
       def define_known_fields_accessors
         self.class.fields_constraints.each do |field_name, constraints|
+          next if constraints[:reverse_method]
           define_field_accessor field_name
           if fields[field_name].nil?
             fields[field_name] = [] if constraints[:has_many] || constraints[:is_array]

data/lib/universe_compiler/entity/relations_management.rb

@@ -5,40 +5,62 @@ module UniverseCompiler
 
     module RelationsManagement
 
-      def has_one(entity_type, name: nil)
-        case entity_type
-        when Class
-          name = name.nil? ? entity_type.entity_type : name.to_sym
-          define_constraint name, :has_one, entity_type.entity_type
-        when Symbol, String
-          name = name.nil? ? entity_type.to_sym : name.to_sym
-          define_constraint name, :has_one, entity_type.to_sym
-        end
+      def has_one(target_entity_type_or_class, name: nil, with_reverse_method: nil, unique: false)
+        target_entity_type = normalize_entity_type target_entity_type_or_class
+        field_name = relation_field_name name, target_entity_type
+        define_constraint field_name, :has_one, target_entity_type
+        return unless with_reverse_method
+
+        define_constraint_for_reverse_method :has_one,
+                                             target_entity_type,
+                                             field_name,
+                                             with_reverse_method,
+                                             unique
       end
 
-      def has_many(entity_type, name: nil)
-        name = case entity_type
-               when Class
-                 name.nil? ? entity_type.entity_type : name.to_sym
-               when Symbol, String
-                 name.nil? ? entity_type.to_sym : name.to_sym
-               end
-        field_name = name.to_s.pluralize.to_sym
-
-        case entity_type
-        when Class
-          define_constraint field_name, :has_many, entity_type.entity_type
-        when Symbol, String
-          define_constraint field_name, :has_many, entity_type.to_sym
-        end
+      def has_many(target_entity_type_or_class, name: nil, with_reverse_method: nil, unique: false)
+        target_entity_type = normalize_entity_type target_entity_type_or_class
+        field_name = relation_field_name name, target_entity_type
+        field_name = field_name.to_s.pluralize.to_sym if name.nil?
+        define_constraint field_name, :has_many, target_entity_type
+        return unless with_reverse_method
+
+        define_constraint_for_reverse_method :has_many,
+                                             target_entity_type,
+                                             field_name,
+                                             with_reverse_method,
+                                             unique
       end
 
-      def entity_type_relations
-        fields_constraints.select do |_, constraints|
-          constraints.keys.include? :has_one or constraints.keys.include? :has_many
+      private
+
+      def relation_field_name(name, target_entity_type)
+        case name
+        when NilClass
+          target_entity_type
+        when String, Symbol
+          name.to_sym
         end
       end
 
+      def define_constraint_for_reverse_method(relation_type, target_entity_type, source_field_name, with_reverse_method, unique)
+        reverse_method_name = case with_reverse_method
+                              when TrueClass
+                                self.entity_type
+                              when String, Symbol
+                                with_reverse_method.to_sym
+                              end
+        target_class = UniverseCompiler::Entity::TypeManagement.type_class_mapping(target_entity_type)
+        method_creation_data = {
+            source_entity: self.entity_type,
+            source_field: source_field_name,
+            relation_type: relation_type,
+            unique_result: unique
+        }
+        target_class.define_constraint reverse_method_name, :reverse_method, method_creation_data
+        true
+      end
+
     end
 
   end

data/lib/universe_compiler/entity/type_management.rb

@@ -3,6 +3,8 @@ module UniverseCompiler
 
     module TypeManagement
 
+      # **
+      # Methods to be added into the class the UniverseCompiler::Entity::TypeManagement is included in.
       module ClassMethods
 
         def entity_type(value = nil)
@@ -16,17 +18,45 @@ module UniverseCompiler
         def entity_type=(value)
           raise UniverseCompiler::Error, "You cannot change an entity type for class '#{self.name}'" unless @entity_type.nil?
           raise UniverseCompiler::Error, 'Only Symbol is supported for entity_type !' unless value.is_a? Symbol
+          mapping = UniverseCompiler::Entity::TypeManagement.types_classes_mapping
+          if mapping.keys.include? value
+            raise UniverseCompiler::Error, "Type '#{value}' already registered for another class (#{mapping[value]})" unless self == mapping[value]
+          end
+          mapping[value] = self
           @entity_type = value
         end
 
+        private
+
+        def normalize_entity_type(entity_type_or_class)
+          case entity_type_or_class
+          when Class
+            entity_type_or_class.entity_type
+          when Symbol, String
+            entity_type_or_class.to_sym
+          end
+        end
+
       end
 
-      def self.valid_for_type?(entity)
-        entity.respond_to? :type and entity.class.respond_to? :entity_type
+      # **
+      # Module methods to be directly used
+
+      def self.type_class_mapping(type_or_class)
+        case type_or_class
+        when Symbol, String
+          types_classes_mapping[type_or_class.to_sym]
+        when Class
+          type_or_class
+        end
       end
 
-      def type
-        self.class.entity_type
+      def self.types_classes_mapping
+        @types_classes_mapping ||= {}
+      end
+
+      def self.valid_for_type?(entity)
+        entity.respond_to? :type and entity.class.respond_to? :entity_type
       end
 
       def self.included(base)
@@ -37,6 +67,13 @@ module UniverseCompiler
         included base.class
       end
 
+      # **
+      # The only instance method
+
+      def type
+        self.class.entity_type
+      end
+
     end
 
   end

data/lib/universe_compiler/entity/validation.rb

@@ -53,6 +53,12 @@ module UniverseCompiler
                   end
                 end
               end
+            when :reverse_method
+              begin
+                send value[:actual_method] if value[:unique_result]
+              rescue UniverseCompiler::Error => uce
+                invalid_for_constraint invalid, value[:actual_method], constraint_name, value
+              end
             else
               UniverseCompiler.logger.warn "Cannot handle unknown constraint '#{constraint_name}'! Skipping..."
             end

data/lib/universe_compiler/version.rb

@@ -1,3 +1,3 @@
 module UniverseCompiler
-  VERSION = '0.3.12'.freeze
+  VERSION = '0.4.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: universe_compiler
 version: !ruby/object:Gem::Version
-  version: 0.3.12
+  version: 0.4.0
 platform: ruby
 authors:
 - Laurent B.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-09-16 00:00:00.000000000 Z
+date: 2019-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler