sfplanner 0.0.1

data/.gitignore

@@ -0,0 +1,2 @@
+*.gem
+*.swp

data/LICENSE

@@ -0,0 +1,30 @@
+BSD LICENSE
+
+Copyright (c) 2013, Herry
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met: 
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer. 
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution. 
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation are those
+of the authors and should not be interpreted as representing official policies, 
+either expressed or implied, of the FreeBSD Project.
+
+The solver binaries are under GPL License from http://fast-downward.org.

data/README.md

@@ -0,0 +1,229 @@
+SFP Planner for Ruby
+====================
+- Author: Herry (herry13@gmail.com)
+- Version: 0.0.1
+- License: [BSD License](https://github.com/herry13/sfp-ruby/blob/master/LICENSE)
+
+A Ruby gem that provides a Ruby interface to a planner that generates a plan as the solution of a planning problem specified in [SFP language](https://github.com/herry13/nuri/wiki/SFP-language).
+
+Click [here](https://github.com/herry13/nuri/wiki/SFP-language), for more details about SFP language.
+
+This is a spin-out project from [Nuri](https://github.com/herry13/nuri).
+
+
+To install
+----------
+
+	$ gem install sfplanner
+
+
+Requirements
+------------
+- Ruby (>= 1.8.7)
+- Rubygems
+	- sfp (>= 0.3.0)
+	- antlr3
+	- json
+
+
+Supporting Platforms
+--------------------
+- Linux (x86)
+- MacOS X
+
+Tested on: MacOS X 10.8, Ubuntu 12.04, and Scientific Linux 6.
+
+
+To use as a command line to solve a planning task
+-------------------------------------------------
+- solve a planning task, and then print a sequential plan (if found) in JSON
+
+		$ sfplanner <sfp-file>
+
+The planning task must be written in [SFP language](https://github.com/herry13/nuri/wiki/SFP-language).
+
+
+To generate a parallel (partial-order) plan
+-------------------------------------------
+- use option **--parallel** to generate a partial order plan
+
+		$ sfplanner --parallel <sfp-file>
+
+
+To use as Ruby library
+----------------------
+- include file *sfplanner* library in your codes:
+
+		require 'sfplanner'
+
+- to parse an SFP file: create a Sfp::Parser object, and then pass the content of the file:
+
+		# Determine the home directory of your SFP file.
+		home_dir = File.expand_path(File.dirname("my_file.sfp"))
+
+		# Create Sfp::Parser object
+		parser = Sfp::Parser.new({:home_dir => "./"})
+
+		# Parse the file.
+		parser.parse(File.read("my_file.sfp"))
+
+		# Get the result in Hash data structure
+		result = parser.root
+
+- to solve a planning task: create a Sfp::Planner object, and then pass the file's path:
+
+		# Create Sfp::Planner object.
+		planner = Sfp::Planner.new
+
+		# Solve a planning task written in "my_file.sfp", then print
+		# the result in JSON.
+		puts planner.solve({:file => "my_file.sfp", :json => true})
+
+
+
+Example of Planning Problem
+---------------------------
+- Create file **types.sfp** to hold required schemas:
+
+		schema Service {
+			running is false
+			procedure start {
+				conditions {
+					this.running is false
+				}
+				effects {
+					this.running is true
+				}
+			}
+			procedure stop {
+				conditions {
+					this.running is true
+				}
+				effects {
+					this.running is false
+				}
+			}
+		}
+		schema Client {
+			refer isref Service
+			procedure redirect(s isref Service) {
+				conditions { }
+				effects {
+					this.refer is s
+				}
+			}
+		}
+
+  In this file, we have two schemas that model our domain. First, schema
+  **Service** with an attribute **running**, procedure **start** that
+  changes **running**'s value from **false** to **true**, and procedure
+  **stop** that changes **running**'s value from **true** to **false**.
+  
+  We also have schema **Client** with an attribute **refer**, which is
+  a reference to an instance of **Service**. There is a procedure
+  **redirect** that changes the value of **refer** with any instance if
+  **Service**.
+
+- Create file **task.sfp** to hold the task:
+
+		include "types.sfp"
+		
+		initial state {
+			a isa Service {
+				running is true
+			}
+
+			b isa Service // with "running" is false
+
+			pc isa Client {
+				refer is a
+			}
+		}
+
+		goal constraint {
+			pc.refer is b
+			a.running is false
+		}
+
+		global constraint {
+			pc.refer.running is true
+		}
+
+  In this file, we specify a task where in the initial state of our domain,
+  we have two services **a** and **b**, and a client **pc**. **a** is
+  running, **b** is stopped, and **pc** is referring to **a**. We want to
+  generate a workflow that achieves goal: **pc** is referring to **b**
+  and **a** is stopped, and preserves global constraint: **pc** is always
+  referring to a running service.
+
+- To generate the workflow, we invoke **sfp** command with argument
+  the path of the task file:
+
+		$ sfp task.sfp
+
+  Which will generate a workflow in JSON
+
+		{
+		  "type": "sequential",
+		  "workflow": [
+		    {
+		      "name": "$.b.start",
+		      "parameters": {
+		      },
+		      "condition": {
+		        "$.b.running": false
+		      },
+		      "effect": {
+		        "$.b.running": true
+		      }
+		    },
+		    {
+		      "name": "$.pc.redirect",
+		      "parameters": {
+		        "$.s": "$.b"
+		      },
+		      "condition": {
+		      },
+		      "effect": {
+		        "$.pc.refer": "$.b"
+		      }
+		    },
+		    {
+		      "name": "$.a.stop",
+		      "parameters": {
+		      },
+		      "condition": {
+		        "$.a.running": true
+		      },
+		      "effect": {
+		        "$.a.running": false
+		      }
+		    }
+		  ],
+		  "version": "1",
+		  "total": 3
+		}
+
+  This workflow is sequential that has 3 procedures. If you executes
+  the workflow in given order, it will achieves the goal state as well
+  as perserves the global constraints during the execution.
+
+- To generate and execute the plan using Bash framework, we invoke **sfp**
+  command with an option *--solve-execute* and with an argument the path of
+  the task file:
+
+		$ sfp --solve-execute task.sfp
+
+  It will generate and execute the plan by invoking the Bash scripts in
+  the current directory (or as specified in environment variable SFP_HOME)
+  in the following sequence:
+
+		./modules/b/start
+		./modules/pc/redirect "$.b"
+		./modules/a/stop
+
+- If you save the plan in a file e.g. **plan.json**, you could execute it
+  later using option *--execute*
+
+		$ sfp --execute plan.json
+

data/bin/sfplanner

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+
+libdir = File.expand_path(File.dirname(__FILE__))
+require "#{libdir}/../lib/sfplanner"
+
+opts = Trollop::options do
+	version "sfplanner 0.0.1 (c) 2013 Herry"
+	banner <<-EOS
+Solve a planning task specified in SFP language, and print the plan (if found) in JSON format.
+
+Usage:
+       sfplanner [options] <file>
+
+where [options] are:
+EOS
+
+	opt :parallel, "Generate a parallel (partial-order) plan, instead of sequential."
+end
+
+def parse(filepath)
+	home_dir = File.expand_path(File.dirname(filepath))
+	parser = Sfp::Parser.new({:home_dir => home_dir})
+	parser.parse(File.read(filepath))
+	parser
+end
+
+filepath = ARGV[0].to_s
+
+if filepath != ''
+	planner = Sfp::Planner.new
+	puts planner.solve({:file => ARGV[0], :pretty_json => true, :parallel => opts[:parallel]})
+else
+	Trollop::help
+end

data/bin/sfw2graph

@@ -0,0 +1,168 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'json'
+
+module Nuri
+	module Planner
+		module Graph
+			ActionColor = 'white'
+			ActionLabelWithParameters = false
+
+			def self.clean(value)
+				return value[2, value.length-2] if value[0,2] == '$.'
+				return value
+			end
+			
+			def self.get_label(action, withparameters=true)
+				label = clean(action["name"])
+				if withparameters and ActionLabelWithParameters
+					label += "("
+					if action["parameters"].length > 0
+						action["parameters"].each { |key,value|
+							label += "#{clean(key)}=#{clean(value.to_s)},"
+						}
+						label.chop!
+					end
+					label += ')'
+				end
+				return label
+			end
+			
+			def self.partial2dot(json)
+				dot = "digraph {\n"
+			
+				dot += "init_state [label=\"\", shape=doublecircle, fixedsize=true, width=0.35];\n"
+				dot += "final_state [label=\"\", shape=doublecircle, style=filled, fillcolor=black, fixedsize=true, width=0.35];\n"
+				last_actions = Hash.new
+				json["workflow"].each { |action|
+					dot += "#{action["id"]}[label=\"#{get_label(action)}\", shape=rect, style=filled, fillcolor=#{ActionColor}];\n"
+					last_actions[action["id"].to_s] = action
+				}
+			
+				json["workflow"].each { |action|
+					has_predecessor = false
+					action["predecessors"].each { |prevId|
+						dot += "#{prevId} -> #{action["id"]};\n"
+						has_predecessor = true
+						last_actions.delete(prevId.to_s)
+					}
+					if not has_predecessor
+						dot += "init_state -> #{action["id"]};\n"
+					end
+				}
+			
+				last_actions.each { |id,action|
+					dot += "#{id} -> final_state;\n"
+				}
+			
+				dot += "}"
+			
+				return dot
+			end
+			
+			def self.stage2dot(json)
+				dot = "digraph {\n"
+			
+				dot += "init_state [label=\"\", shape=doublecircle, fixedsize=true, width=0.35];\n"
+				dot += "final_state [label=\"\", shape=doublecircle, style=filled, fillcolor=black, fixedsize=true, width=0.35];\n"
+				index = 0
+				prevState = "init_state"
+				json["workflow"].each { |stage|
+					id = 0
+					stage.each { |action|
+						dot += "a" + index.to_s + "a" + id.to_s + '[label="' + get_label(action) + '", shape=rect]' + ";\n"
+						dot += prevState + " -> a" + index.to_s + "a" + id.to_s + ";\n"
+						id += 1
+					}
+					if index < json["workflow"].length-1
+						dot += "state" + index.to_s + ' [label="", shape=circle, fixedsize=true, width=0.35]' + ";\n"
+						prevState = "state" + index.to_s
+						id = 0
+						stage.each { |action|
+							dot += "a" + index.to_s + "a" + id.to_s + " -> " + prevState + ";\n"
+							id += 1
+						}
+					else
+						id = 0
+						stage.each { |action|
+							dot += "a" + index.to_s + "a" + id.to_s + " -> final_state;\n"
+							id += 1
+						}
+					end
+					index += 1
+				}
+				dot += "}"
+				return dot
+			end
+			
+			def self.sequential2dot(json)
+				dot = "digraph {\n"
+			
+				dot += "init_state [label=\"\", shape=doublecircle, fixedsize=true, width=0.35];\n"
+				dot += "final_state [label=\"\", shape=doublecircle, style=filled, fillcolor=black, fixedsize=true, width=0.35];\n"
+				id = 0
+				json["workflow"].each { |action|
+					dot += id.to_s + '[label="' + get_label(action) + '", shape=rect]' + ";\n"
+					id += 1
+				}
+			
+				id = 0
+				prevActionId = nil
+				json["workflow"].each { |action|
+					if id == 0
+						dot += "init_state -> " + id.to_s + ";\n"
+					elsif id == json["workflow"].length-1
+						dot += id.to_s + " -> final_state;\n"
+					end
+					if prevActionId != nil
+						dot += prevActionId.to_s + " -> " + id.to_s + ";\n"
+					end
+					prevActionId = id
+					id += 1
+				}
+				dot += "}"
+				return dot
+			end
+		end
+	end
+end
+
+def main
+	if ARGV.length < 1
+		puts "Usage: sfw2dot.rb <input-file> [output-file]\n\n"
+		exit
+	end
+	
+	fp = open(ARGV[0], "rb")
+	json = JSON.parse(fp.read)
+	fp.close
+	
+	dot = ""
+	case json["type"]
+	when 'partial-order', 'parallel'
+		dot = Nuri::Planner::Graph::partial2dot(json)
+	when 'sequential'
+		dot = Nuri::Planner::Graph::sequential2dot(json)
+	when 'stage'
+		dot = Nuri::Planner::Graph::stage2dot(json)
+	else
+		throw Exception, "Unrecognised type of workflow: #{json['type']}"
+	end
+	
+	outfile = "/tmp/#{ARGV[0]}.dot"
+	fp = open(outfile, "w");
+	fp.write(dot)
+	fp.close
+	
+	cmd = 'dot -Tpng -o';
+	if ARGV.length > 1
+		cmd += "#{ARGV[1]} #{outfile}"
+	else
+		cmd += ARGV[0].sub(/\.[a-zA-Z]*/,'') + ".png < #{outfile}"
+	end
+	system(cmd)
+	File.delete(outfile)
+end
+
+main if __FILE__ == $0