universe_compiler 0.2.16 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5c53fdf41edd21c2f42d95cbe571ad2144e3024d
-  data.tar.gz: dd8f70ce2b215aa1210f8f57c59597979822e03d
+  metadata.gz: 74a3ec7f9f7eabc456f265d047bf92492039fd8f
+  data.tar.gz: af3c07e4b7be608ec614de02fa5200a8a305e236
 SHA512:
-  metadata.gz: 48bddacf5d26a8a0dda4d7763a2ca57f7d591131964bae3951a4ba1c9242028bae7d0907612040f7795122c6f5269f7cca685c9131d52b9a7a2d200c17b39670
-  data.tar.gz: 18552dc3147935c98001999f901e7c7e46ead0e9f00c1f5fc9e3e2f0fba02a1a87e3b363bc1de9f10e5dd186d2a27d3a5736d9be7198c0149bff5b9ac1d70a8c
+  metadata.gz: 551eb041d06b5fb15dac1a4ef75574e98a9315c1e27f75c1ea88843ebca171271b1a20a531b84a6fa54cb22e732be3aa94d4ec4f8a5879b06aa964a6cd9b2876
+  data.tar.gz: 06e25e42a45c83d3a7bca5f10b9c12c11ffe7e20de257f0b70b8b086fdef3e258d9a80780821555b3e052cc7a72aebcec2b16e1d90d70117b88d8c30c15526bd

data/README.md

@@ -1,4 +1,27 @@
-# UniverseCompiler
+UniverseCompiler
+================
+
+<!-- TOC -->
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Core Concepts](#core-concepts)
+    - [Entities](#entities)
+        - [Overview](#overview-1)
+            - [Special directives](#special-directives)
+            - [Constraints and relationships directives](#constraints-and-relationships-directives)
+        - [Compilation](#compilation)
+    - [Inheritance](#inheritance)
+    - [Overrides](#overrides)
+- [Generate a graph of entities using `Graphviz`](#generate-a-graph-of-entities-using-graphviz)
+- [Development](#development)
+- [Contributing](#contributing)
+    - [License](#license)
+    - [Code of Conduct](#code-of-conduct)
+
+<!-- /TOC -->
+
+# Overview
 
 The goal of this gem is to provide a simple way to manage a consistent highly complex configuration.
 
@@ -15,7 +38,7 @@ a yaml persistence engine is available by default in the gem.
 A `universe` can be _compiled_ in order to produce a new `universe` where all constraints and relations defined
 by these entities have been resolved.
 
-## Installation
+# Installation
 
 Add this line to your application's Gemfile:
 
@@ -32,11 +55,11 @@ Or install it yourself as:
     $ gem install universe_compiler
 
 
-## Core Concepts
+# Core Concepts
 
-### Entities
+## Entities
 
-#### Overview
+### Overview
 
 Any `entity` you will create will basically inherit from `UniverseCompiler::Entity::Base`. This will allow
 the following kind of code:
@@ -229,7 +252,7 @@ end
 # => [{name: :a, compiled: true},{name: :b, compiled: true},{name: :c, compiled: true}]
 ```
 
-### Inheritance
+## Inheritance
 
 To be clear, here we talk about __entities (instances) inheritance, NOT classes !__
 
@@ -256,7 +279,7 @@ u2.a --extends--> u2.b --extends--> u2.c
 ```
 You can see an example of inheritance in previous paragraph.
 
-### Overrides
+## Overrides
 
 Overrides are actually a special type of entities. They have a special array called `overrides`
 which contains a list of entities you want to inject content into.
@@ -301,18 +324,54 @@ v.get_entities.map &:fields
 You can see there that the compiled version of `b` contains both data coming from the inheritance mechanism 
 as well as those coming from the override...
 
-## Development
+# Generate a graph of entities using `Graphviz`
+
+Provides a [Graphviz] graph of relations using the [ruby-graphviz] gem between a set of entities and allows callback mechanisms for the graph customization.
+
+All you need is to:
+
+```ruby
+include UniverseCompiler::Utils::Graphviz
+```
+In any class, and then simply call:
+```ruby
+graph_entities_to_file(an_array_of_entities, set_of_options, &customization_block)
+```
+
+Calls to the `graph_entities_to_file` method returns either the filename of the created file or the graphiz graph object depending on method parameters.
+
+A block can be passed to the method, it will yield the graph object, and optionnally a bi-directional structure of entities and graphwiz nodes, allowing for complete graph display customization (you may actually completely change the graph, but maybe in this case you may want to actually completely build the graph. It is normally intended to change/customize display attributes there...).
+
+# Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-## Contributing
-
-Bug reports and pull requests are welcome on Gitlab at https://gitlab.com/lbriais/universe_compiler. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+# Contributing
 
+Bug reports and pull requests are welcome on Gitlab at https://gitlab.com/tools4devops/power_stencil. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License].
+
+## Code of Conduct
+
+Everyone interacting in the PowerStencil project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct].
+
+
+<!-- End of Document -->
+
+<!-- Pages -->
+[code of conduct]: CODE_OF_CONDUCT.md
+
+<!-- Code links -->
+
+<!-- Illustrations -->
 
+<!-- External links -->
+[MIT License]: http://opensource.org/licenses/MIT "The MIT license"
+[Ruby]: https://www.ruby-lang.org "The powerful Ruby language"
+[Graphviz]: (https://www.graphviz.org/) "Graph Visualization Software"
+[ruby-graphviz]: (https://rubygems.org/gems/ruby-graphviz) "Ruby interface to graphviz"

data/lib/universe_compiler/utils/graphviz.rb

@@ -0,0 +1,83 @@
+require 'tempfile'
+
+module UniverseCompiler
+  module Utils
+
+    module Graphviz
+
+      def graph_entities_to_file(entities,
+                                 output_file_name: nil,
+                                 file_type: :svg,
+                                 generate_file: true,
+                                 &block)
+        g = GraphViz.new( :G, :type => :digraph )
+
+        cache = {by_node: {}, by_entity: {}}
+        # Building nodes 
+        entities.each do |entity|
+          node = g.add_node entity.as_path
+          if entity.respond_to? :graphviz_label
+            node[:label] = entity.graphviz_label
+          end
+          cache[:by_entity][entity] = node
+          cache[:by_node][node] = entity
+        end
+        
+        # Building relations
+        entities.each do |entity|
+          entity.class.fields_constraints.each do |field_name, field_constraints|
+            field_constraints.each do |constraint_name, _|
+              case constraint_name
+              when :has_one
+                target = entity[field_name]
+                g.add_edges cache[:by_entity][entity], cache[:by_entity][target] unless target.nil?
+              when :has_many
+                entity[field_name].each do |target|
+                  g.add_edges cache[:by_entity][entity], cache[:by_entity][target]
+                end
+              end
+            end
+          end
+        end
+
+        if block_given?
+          case block.arity
+          when 1
+            yield g
+          when 2
+            yield g, cache
+          else
+            raise UniverseCompiler::Error, 'Wrong arity when calling UniverseCompiler::Utils::Graphviz#graph_entities_to_file'
+          end
+        end
+
+        file_ext = file_type.to_s
+        file_ext = (file_ext.start_with? '.') ? file_ext : ".#{file_ext}"
+
+        output_file_name = case output_file_name
+                      when NilClass
+                        file = Tempfile.create ['entities_graph', file_ext]
+                        file.close
+                        file.path
+                      when String
+                        if output_file_name.end_with? file_ext
+                          output_file_name
+                        else
+                          "#{output_file_name}#{file_ext}"
+                        end
+                      end
+
+        if generate_file
+          g.output( file_type => output_file_name )
+          UniverseCompiler.logger.debug "Graph file: '#{output_file_name}'"
+          output_file_name
+        else
+          g
+        end
+      end
+
+
+    end
+
+  end
+end

data/lib/universe_compiler/version.rb

@@ -1,3 +1,3 @@
 module UniverseCompiler
-  VERSION = '0.2.16'.freeze
+  VERSION = '0.3.0'.freeze
 end

data/lib/universe_compiler.rb

@@ -1,4 +1,5 @@
 require 'super_stack'
+require 'graphviz'
 
 require 'universe_compiler/version'
 require 'universe_compiler/error'
@@ -7,6 +8,7 @@ require 'universe_compiler/utils/error_propagation'
 require 'universe_compiler/utils/array_utils'
 require 'universe_compiler/utils/deep_traverse'
 require 'universe_compiler/utils/with_unique_name'
+require 'universe_compiler/utils/graphviz'
 
 module UniverseCompiler
   extend UniverseCompiler::Utils::BasicLogger

data/universe_compiler.gemspec

@@ -28,5 +28,6 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency 'super_stack', '~> 1.0', '>= 1.0.6'
   spec.add_runtime_dependency 'activesupport', '~> 5.0'
+  spec.add_dependency 'ruby-graphviz'
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: universe_compiler
 version: !ruby/object:Gem::Version
-  version: 0.2.16
+  version: 0.3.0
 platform: ruby
 authors:
 - Laurent B.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-09-13 00:00:00.000000000 Z
+date: 2019-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -134,6 +134,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: ruby-graphviz
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Provide a way to create objects with complex relationships, inheritance
   and override mechanisms.
 email:
@@ -188,6 +202,7 @@ files:
 - lib/universe_compiler/utils/basic_logger.rb
 - lib/universe_compiler/utils/deep_traverse.rb
 - lib/universe_compiler/utils/error_propagation.rb
+- lib/universe_compiler/utils/graphviz.rb
 - lib/universe_compiler/utils/with_unique_name.rb
 - lib/universe_compiler/version.rb
 - universe_compiler.gemspec