rachinations 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f121ae6b88636bb8f2d61ce349052e5eaaab765a
-  data.tar.gz: 80b8154cb68f75059ed98c866043b052c1271ac0
+  metadata.gz: 7d453a7d9164b1dd29813252604b256fc8219f3c
+  data.tar.gz: 4ac7305c010e2b43d2488bceaab5aecf30f2db72
 SHA512:
-  metadata.gz: 555791bf758a0458b7cfc3b1c71287c33b54ce296d957878f4c4d236fb0186a8b1aaf036529119b5a85bd40eeeeacf152e7bf2df87590040f75a89330c52e067
-  data.tar.gz: 1443bdad6609c32eb441b22e686c46b04c531808f190301ed0de56d309730ff2b94cd7b47dc4244e252594188fe9b2939caad027c72168a3f9512cd0a9a2fd9b
+  metadata.gz: 79580ad9cd32113ee03fb3ca7dbe6d6a64cd3de6f40eb98823a8a4337931c34634046f7515071b67c38c82fc66cdbd7cbf29d2e1ed4a66f7c5ffef13ec719354
+  data.tar.gz: e565c119969a4c534adf4b7c6843d9cea5e5e5ef5548438e58152c40c6418f1118cb862b128ec6924fa19e39d05ed4da1186a3fdbc9fa0c3aa17a38750e7f97b

data/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    rachinations (0.0.6)
+    rachinations (0.0.7)
       activesupport (= 3.0.0)
+      fraction (= 0.3.2)
       i18n (= 0.6.11)
       weighted_distribution (= 1.0.0)
 
@@ -22,6 +23,7 @@ GEM
     docile (1.1.5)
     ffi (1.9.3-x64-mingw32)
     ffi (1.9.3-x86-mingw32)
+    fraction (0.3.2)
     i18n (0.6.11)
     mime-types (2.3)
     minitest (5.4.0)

data/README.md

@@ -1,18 +1,197 @@
-rachinations
+Rachinations
 ====================
 [![Build Status](https://travis-ci.org/queirozfcom/rachinations.svg?branch=master)](https://travis-ci.org/queirozfcom/rachinations?branch=master)
 [![Code Climate](https://codeclimate.com/github/queirozfcom/rachinations.png)](https://codeclimate.com/github/queirozfcom/rachinations)
 [![Coverage Status](https://coveralls.io/repos/queirozfcom/rachinations/badge.png?branch=master)](https://coveralls.io/r/queirozfcom/rachinations?branch=master)
 [![Gem Version](https://badge.fury.io/rb/rachinations.svg)](http://badge.fury.io/rb/rachinations)
 
-### Introduction
-
 This is a port of Dr. J. Dormans' [Machinations framework](http://www.jorisdormans.nl/machinations/) into Ruby.
 
 It provides a Ruby-based DSL to enable game designers to create and also test tentative game designs and/or prototypes.
 
-### Contents
+## Contents
 
 - Classes to model the domain
 - Tests
-- A simple DSL (Domain-specific language) whose objective is to enable anyone to write Machinations diagrams, run them, obtain metrics, compose subdiagrams and so on.
+- A simple DSL (Domain-specific language) whose objective is to enable anyone to write Machinations diagrams, run them, obtain metrics, compose subdiagrams and so on.
+
+## Installation Guide
+
+Rachinations is written in Ruby so you need to have Ruby installed on your system. You only need 5 minutes to get it to work:
+
+**Linux**
+
+  The best way to install Ruby on a Linux-based machine is probably RVM. [Instructions on how to install RVM on Linux here](http://queirozf.com/entries/tutorial-and-examples-on-how-to-use-rvm-on-linux)
+
+  Once Ruby is installed, you just need to install the rachinations **gem**. The process is straightforward:
+
+  ```
+  $ gem install rachinations
+  ```
+
+**Windows**
+
+  - **Installation**
+
+  On Windows, the best way to get up and running with Ruby is probably using the [RubyInstaller for Windows](http://rubyinstaller.org/)
+
+  Please note that Rachinations requires at least Ruby **version 2.1** to work.
+
+  If you have never used Ruby before, I recommend you tick the following two boxes, as per the following image:
+
+  ![installing_ruby_on_windows](http://i.imgur.com/Y0u1ZzN.png)
+
+  - **Veryfing that the installation worked**
+
+  Once Ruby is installed, open a **command prompt** and type `ruby -v` just to see if everything worked.
+
+  You should see something like this (details may vary slightly)
+
+  ```
+  > ruby -v
+  ruby 2.1.5p273 (2014-11-13 revision 48405) [x64-mingw32]
+  ```
+
+  - **Configuring rubygems and installing the library**
+
+  Once that's done, we'll configure `gem` (Ruby's package manager) to address a well known problem that has to do with certificates on Windows. More info [here](http://stackoverflow.com/questions/9962051/could-not-find-a-valid-gem-in-any-repository-rubygame-and-others) and [here](http://help.rubygems.org/discussions/problems/19761-could-not-find-a-valid-gem).
+
+  On the command prompt, do this:
+
+  ```
+  > gem sources -r https://rubygems.org
+  ```
+  and
+
+  ```
+  > gem sources -a http://rubygems.org
+  https://rubygems.org is recommended for security
+
+  Do you want to add this insecure source? [yn] y
+  http://rubygems.org added to sources
+  ```
+
+  After you've done the last step (which adds a new source for gems to be fetched from), then you can install the gem proper:
+
+  ```
+  > gem install rachinations
+  ```
+  (you might see a few error messages, but don't worry)
+
+## Usage
+
+All you need to do is write your diagram in a file whose name ends in `.rb` and run it using the `ruby` command.
+
+### Examples
+
+- **Simplest possible example**
+
+ ```ruby
+ require 'rachinations'
+
+ # this is a simple diagram with a single pool with
+ # 5 resources
+ d=diagram 'simplest_diagram' do
+     pool initial_value: 5
+ end
+
+ # and execute it for 10 rounds
+ d.run 10
+ ```
+
+ Save this code into a file (say, `static_diagram.rb`) and run it like this:
+
+ ```
+ $ ruby static_diagram.rb
+ ```
+
+- **Example 1**
+
+ ```ruby
+ require 'rachinations'
+
+ diagram 'example_1' do
+     source 's1', :automatic
+     pool 'p1'
+     pool 'p2', :automatic
+     edge from: 's1', to: 'p1'
+     edge from: 'p1', to: 'p2'
+ end
+ ```
+
+- **Example 2**
+
+ ```ruby
+ require 'rachinations'
+
+ diagram 'example_2' do
+     source 's1'
+     pool 'p1'
+     converter 'c1', :automatic
+     pool 'p2'
+     pool 'p3'
+     edge from: 's1', to: 'p1'
+     edge from: 'p1', to: 'c1'
+     edge from: 'c1', to: 'p2'
+     edge from: 'c1', to: 'p3'
+ end
+ ```
+
+- **Example 3**
+
+ ```ruby
+ require 'rachinations'
+
+ diagram 'example_3' do
+     source 's1'
+     gate 'g1', :probabilistic
+     pool 'p1'
+     pool 'p2'
+     pool 'p3'
+     sink 's2', :automatic, condition: expr{ p2.resource_count > 30 }
+     edge from: 's1', to: 'g1'
+     edge from: 'g1', to: 'p1'
+     edge 2, from: 'g1', to: 'p2'
+     edge from: 'g1', to: 'p3'
+     edge from: 'p3', to: 's2'
+ end
+ ```
+
+- **Example 4**
+
+ ```ruby
+ require 'rachinations'
+
+ diagram 'example_4' do
+     source 's1'
+     pool 'p1', triggers: 's2'
+     source 's2', :passive
+     pool 'p2'
+     edge from: 's1', to: 'p1'
+     edge from: 's2', to: 'p2'
+ end
+ ```
+
+- **Example 4, alternative version**
+
+ This amounts to the same diagram as the one defined in Example 4, but uses a different mechanism for defining triggers between nodes.
+
+ ```ruby
+ require 'rachinations'
+
+ diagram 'example_4_alternative' do
+     source 's1'
+     pool 'p1'
+     source 's2', :passive, triggered_by: 'p1'
+     pool 'p2'
+     edge from: 's1', to: 'p1'
+     edge from: 's2', to: 'p2'
+ end
+ ```
+
+### Full DSL specification
+ **TODO**
+
+
+
+

data/lib/rachinations.rb

@@ -2,15 +2,18 @@ lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'rachinations/version'
 
+require 'rachinations/utils/math_utils'
+require 'rachinations/utils/string_utils'
+
 require 'rachinations/domain/modules/common/refiners/proc_convenience_methods'
 require 'rachinations/domain/modules/common/refiners/number_modifiers'
 require 'rachinations/domain/modules/common/schedulable_tasks'
 
-
 require 'rachinations/extras/fifo'
 
 require 'rachinations/domain/diagrams/diagram'
 require 'rachinations/domain/diagrams/verbose_diagram'
+require 'rachinations/domain/diagrams/non_deterministic_diagram'
 require 'rachinations/dsl/diagram_shorthand_methods'
 require 'rachinations/dsl/bootstrap'
 require 'rachinations/domain/strategies/strategy'
@@ -19,10 +22,9 @@ require 'rachinations/domain/edges/edge'
 
 require 'rachinations/domain/exceptions/no_elements_of_given_type'
 require 'rachinations/domain/exceptions/unsupported_type_error'
-require 'rachinations/domain/exceptions/bad_options'
-require 'rachinations/domain/exceptions/bad_config'
 require 'rachinations/domain/exceptions/no_elements_matching_condition_error'
 require 'rachinations/domain/exceptions/no_elements_found'
+require 'rachinations/domain/exceptions/bad_config'
 require 'rachinations/dsl/bad_dsl'
 
 require 'rachinations/domain/nodes/node'
@@ -38,7 +40,6 @@ require 'rachinations/domain/edge_collection'
 require 'rachinations/domain/node_collection'
 require 'rachinations/domain/resource_bag'
 
-
 # users can use the dsl to create diagrams
 include DSL::Bootstrap
 

data/lib/rachinations/domain/diagrams/diagram.rb

@@ -15,9 +15,9 @@ class Diagram
     @edges = EdgeCollection.new
     @name = name
     @max_iterations = 999
+    @stop_conditions = []
   end
 
-
   def get_node(name)
 
     nodes.each do |node|
@@ -96,10 +96,23 @@ class Diagram
     self
   end
 
-  def run!(rounds=5)
+  def add_stop_condition!(message: nil, condition:)
+    raise ArgumentError, 'Expression required for stop condition' unless condition.is_a? Proc
+    raise ArgumentError, 'Message can be omitted only if there is no other condition' if message.nil? && !(@stop_conditions.empty?)
+
+    hsh = {
+        message: message,
+        condition: condition
+    }
+
+    @stop_conditions << hsh
+
+  end
+
+  def run!(rounds = max_iterations)
 
     run_while! do |i|
-      i<=rounds
+      i <= rounds && no_stop_conditions_met?
     end
 
   end
@@ -115,10 +128,9 @@ class Diagram
 
     i=1
 
-    # if given condition block turned false, it's time to stop
     while yield i do
 
-      break unless sanity_check? i
+      break if maximum_round? i
 
       before_round i
 
@@ -139,7 +151,6 @@ class Diagram
 
   end
 
-
   def resource_count(klass=nil)
     total=0
     @nodes.each do |n|
@@ -154,40 +165,40 @@ class Diagram
     nodes.reduce('') { |carry, n| carry+n.to_s }
   end
 
-  def sanity_check?(round_no)
-    if round_no > @max_iterations
-      sanity_check_message
-      false
-    else
-      true
-    end
+  def no_stop_conditions_met?
+    @stop_conditions
+    .all? { |el| ! el[:condition].call }
   end
 
-  def run_first_round!
+  def maximum_round?(round_no)
+    round_no > @max_iterations
+  end
 
-    enabled_nodes.select { |node| node.automatic? || node.start? }.shuffle.each { |node| node.trigger! }
+  def run_first_round!
+    enabled_nodes
+    .select { |node| node.automatic? || node.start? }
+    .shuffle
+    .each { |node| node.trigger! }
 
     commit_nodes!
-
   end
 
   def run_round!
-
-    enabled_nodes.select { |node| node.automatic? }.shuffle.each { |node| node.trigger! }
+    enabled_nodes
+    .select { |node| node.automatic? }
+    .shuffle
+    .each { |node| node.trigger! }
 
     commit_nodes!
-
   end
 
   def commit_nodes!
     #only after all nodes have run do we update the actual resources and changes, to be used in the next round.
     nodes.shuffle.each { |node| node.commit! }
-
   end
 
   def enabled_nodes
     nodes.select { |node| node.enabled? }
-
   end
 
   #template method
@@ -199,15 +210,15 @@ class Diagram
   end
 
   #template method
-  def before_run;
+  def before_run
   end
 
   #template method
-  def after_run;
+  def after_run
   end
 
   #template method
-  def sanity_check_message;
+  def sanity_check_message
   end
 
 end

data/lib/rachinations/domain/exceptions/bad_config.rb

@@ -1,4 +1,4 @@
 # this exception should be used to signal that an inconsistent state
-# was found, but due to bad initialization, not bad changes in state
+# was found due to bad initialization, not bad changes in state
 class BadConfig < RuntimeError
 end

data/lib/rachinations/domain/modules/common/hash_init.rb

@@ -1,3 +1,4 @@
+require_relative 'bad_options'
 #use this for classes you want to be able to instantiate
 #using a hashful of parameters
 module HashInit

data/lib/rachinations/domain/modules/common/refiners/number_modifiers.rb

@@ -1,5 +1,6 @@
-module NumberModifiers
+# require 'fraction'
 
+module NumberModifiers
 
   # allow user to modify Numbers in order to express
   # percentages ( 12.percent ) and also fractions, for

data/lib/rachinations/domain/modules/diagrams/verbose.rb

@@ -2,7 +2,7 @@ module Verbose
 
 
   def before_run
-    print "\033[1;32m===== INITIAL STATE =====\e[00m\n\n"
+    print "\n\033[1;32m===== INITIAL STATE =====\e[00m\n\n"
 
     puts self
   end

data/lib/rachinations/domain/nodes/gate.rb

@@ -2,9 +2,13 @@ require_relative '../../domain/nodes/node'
 require_relative '../../domain/nodes/resourceless_node'
 
 require 'weighted_distribution'
+require 'fraction'
 
 class Gate < ResourcelessNode
 
+  EdgeHelper = Helpers::EdgeHelper
+
+  attr_reader :mode, :activation
 
   def initialize(hsh={})
     check_options!(hsh)
@@ -13,55 +17,47 @@ class Gate < ResourcelessNode
     @diagram = params[:diagram]
     @name = params[:name]
     @activation = params[:activation]
+    # for gates, :mode has different semantics
     @mode = params[:mode]
     @types = get_types(given_types: params[:types])
 
     super(hsh)
   end
 
-  def put_resource!(res,edge)
+  def put_resource!(res, from_edge)
 
-    inv("Edges must be either all defaults or all probabilities") { outgoing_edges.all?{|e| e.label == 1 } || outgoing_edges.all?{|e| e.label.class == Float} }
-    inv("If probabilities given, their sum must not exceed 1"){ outgoing_edges.reduce(0){|acc,el| acc + el.label } <= 1 || !outgoing_edges.all?{|e| e.label.class == Float}  }
+    raise BadConfig.new('All outgoing Edges must be of the same kind') unless EdgeHelper.all_labels_of_same_kind?(outgoing_edges)
+    raise BadConfig.new('If probabilities are given, they must add up to 1') unless EdgeHelper.labels_valid?(outgoing_edges)
 
-    maybe_edge = pick_one(outgoing_edges)
+    maybe_edge = EdgeHelper.pick_one(edges: outgoing_edges, mode: mode, index: next_edge_index)
 
-    if(maybe_edge.nil?)
-      # do nothing - resource has 'vanished' - happens every other day
+    if (maybe_edge.nil?)
+      # no outgoing edges. resource disappears
     else
       maybe_edge.push!(res)
     end
 
   end
 
+  def take_resource!(res, edge)
+    # no action
+  end
+
   def to_s
     "Gate '#{@name}'\n\n"
   end
 
   private
 
-  def pick_one(edges)
-
-    if(edges.all?{|e| e.label == 1})
-      #edges is probably an enumerable but only arrays can be sample()'d
-      edges.to_a.sample
-    elsif(edges.all?{|e| e.label.class == Float})
-      #{edge=>weight} is the shape required by WeightedRandomizer
-      weights = edges.reduce(Hash.new){|acc,el| acc[el] = el.label; acc }
-
-      sum = edges.reduce(0){|acc,el|acc + el.label }
+  # used to indicate what edge index
+  # when in :deterministic mode
+  def next_edge_index
+    # starting at zero
+    @next_edge_index ||= 0
 
-      remaining = 1.0 - sum
-
-      #resource 'vanishes'
-      weights[nil] = remaining
-
-      edge_distribution = WeightedDistribution.new(weights)
-      edge_distribution.sample
-    else
-      raise RuntimeError.new('Invalid setup')
-    end
+    @next_edge_index += 1
 
+    (@next_edge_index - 1)
   end
 
   def options
@@ -75,7 +71,7 @@ class Gate < ResourcelessNode
   def defaults
     {
         activation: :passive,
-        mode: :push_any,
+        mode: :deterministic,
         types: []
     }
   end