flok 0.0.100 → 0.0.101

data/lib/flok.rb

@@ -9,6 +9,7 @@ require "flok/interactive"
 require "flok/user_compiler"
 require "flok/services_compiler"
 require "flok/transition_compiler"
+require "flok/hooks_compiler"
 
 module Flok
 end

data/lib/flok/hooks_compiler.rb

@@ -0,0 +1,174 @@
+require_relative './macro.rb'
+#The hooks compiler is a late-stage (see ./project.md) compiler that takes the almost-fully-compiled
+#javascript source (which includes the user's javascript controllers by now) and looks for special
+#comment markers for which it can inject code.
+module Flok
+  module HooksCompiler
+    #Returns a new copy of the source transformed as described by the manifest
+    def self.compile(src, manifest)
+      new_src = src.split("\n").map{|e| manifest.transform_line(e) }.join("\n")
+
+      #Re-process macros
+      new_src = Flok.macro_process new_src
+
+
+      return new_src
+    end
+  end
+
+  #A hooks manifest contains all the information needed so that the hooks compiler
+  #can find can change the code
+  class HooksManifest
+    def initialize
+      @manifest_entries = []
+    end
+
+    #Returns a copy of the line with transformations if needed. For example, if a line contains
+    #a hook entry point, like HOOK_ENTRY[my_event] and the manifest contains code that should
+    #be inserted there, this will return the inserted code (which may then be multiple lines)
+    #And will also remove the comment itself
+    def transform_line line
+      #Get all the matched HooksManifestEntry(s) 
+      injected_code = @manifest_entries.select{|e| e.does_match? line}.map{|e| e.code_for_line(line)}
+
+      #If there is a match of at least one hook, remove the original line and replace it
+      #with all the newly found code from the HooksManifestEntry(s)
+      return injected_code.join("\n") if injected_code.count > 0
+
+      #Else, nothing was found, keep moving along and don't transform the line
+      return line
+    end
+
+    #Accepts a HooksManifestEntry which can match a line and then return some text
+    #that should be apart of that line. Multiple matching manifest entries
+    #is possible
+    def <<(entry)
+      @manifest_entries << entry
+    end
+  end
+
+  #When HooksManifest goes line by line, a line is considered matching when this entry
+  #retruns true for its does_match? function. You pass it a name, optional parameter
+  #query and the block to call when the code should be generated for a match. The block
+  #receives a full copy of the parameters for the hook entry (the static ones). The 
+  #param query is a lambda that also receives the block and it should return (next) true/false
+  #when a match is considered true. If name is just "*" (string, not symbol), then it matches
+  #all names. Passing multiple param_queries in is allowed, you just pass in multiple arrays.
+  #All of the procs passed must be true for the result to be true
+  #
+  #E.g. - This would match //HOOK_ENTRY[my_event]
+  #>HooksManifestEntry.new("my_event", ->(p){p["actions"].include? "x"}) do |hook_info|
+  #  return "console.log(info = #{info["actions"]});"
+  #end
+  class HooksManifestEntry
+    def initialize name, param_queries=->(p){true}, &block
+      #If an array is not passed, make it an array with one element
+      param_queries = [param_queries] if param_queries.class != Array
+
+      @name = name.to_s
+      @param_queries = param_queries
+      @block = block
+    end
+
+    def does_match? line
+      #Unless the matching name is a *, check to see if the hook name matches
+      unless @name == "*"
+        return false unless line =~ /\/\/HOOK_ENTRY\[#{@name}\]/
+      end
+
+      #Now verify with the lambda
+      return @param_queries.reduce(true){|r, e| r &&= e.call(hook_entry_info_from_line(line))}
+    end
+
+    def code_for_line line
+      return @block.call(hook_entry_info_from_line(line))
+    end
+
+    #Each hook entry contains a JSON encoded set of static parameters
+    #for things like the controller name, etc. See docs for a list of 
+    #parameters as it depends on the hook entry
+    def hook_entry_info_from_line line
+      json_info = line.split(/\/\/HOOK_ENTRY\[.*?\]/).last.strip 
+      begin
+        return JSON.parse(json_info)
+      rescue => e
+        raise "Couldn't parse the hooks entry JSON information, got #{json_info.inspect}: #{e.inspect}"
+      end
+    end
+  end
+
+  #This converts all the user hooks into a manifest
+  module UserHooksToManifestOrchestrator
+    $generators = {}
+
+    #Register a user hook generator to be available to the user in their `./config/hooks.rb`
+    #The name is what is used to find the correct generator when a user uses the 
+    #hook :name DSL syntax
+    def self.register_hook_gen name, &gen_block
+      $generators[name] = gen_block
+    end
+
+    #Converts the `./config/hooks.rb` of the user into a HooksManifestEntry
+    def self.convert_hooks_to_manifest hooks_rb
+      #Create a new manifest, this will be passed to each generator instance
+      #along with a set of parameters. Each generator will update the 
+      #hooks manifest
+      manifest = HooksManifest.new
+
+      #Evaluate the user hooks DSL which will create a listing of all the
+      #user's requests in the accessible :hooks_requests member of the dsl environment
+      hooks_dsl_env = UserHooksDSL.new
+      hooks_dsl_env.instance_eval hooks_rb
+
+      #For each user request, lookup the appropriate generator handler and then
+      #call the generator
+      hook_requests = hooks_dsl_env.hook_requests
+      hook_requests.each do |gen_name, requests|
+        generator = $generators[gen_name]
+        raise "A hook request requested the generator by the name #{gen_name.inspect} but this was not a generator..." unless generator
+
+        requests.each do |r|
+          generator.call(manifest, r)
+        end
+      end
+
+      return manifest
+    end
+
+    #Interpret `./config/hooks.rb` to call the associated registered hook gen block
+    class UserHooksDSL
+      attr_accessor :hook_requests
+      def initialize
+        #Each user hook call adds a request to this hash
+        #which is then processed by each matching hook generator 
+        @hook_requests = {}
+      end
+
+      #Install a hook.  Leads to eventually calling the relavent hook generator. The anmes argument
+      #takes one key-value pair e.g. {:goto => :settings_changed}, this would mean the hook generator
+      #named 'goto' and it should create a hook event called 'settings_changed'. The block
+      #is then passed on to each hook generator. See the docs on hooks.md for information on what
+      #each block function takes
+      def hook names, &block
+
+        #The names parameter 
+        key = names.keys.first
+        hook_event_name = names.values.first
+        raise "You didn't supply a hook generator name or the event name... Got #{key.inspect} and #{hook_event_name.inspect}.  e.g. hook :goto => :changed, {...}" unless key and hook_event_name
+
+        @hook_requests[key] ||= []
+        @hook_requests[key] << {
+          :hook_event_name => hook_event_name,
+          :block => block
+        }
+      end
+    end
+  end
+end
+
+#Load all the user hook generators
+Dir.chdir File.join(File.dirname(__FILE__), "../../") do
+  Dir["./lib/flok/user_hook_generators/*"].each do |f|
+    load f
+  end
+end

data/lib/flok/project_template/config/hooks.rb

@@ -0,0 +1 @@
+#Hooks stub

data/lib/flok/user_compiler.rb

@@ -22,7 +22,7 @@ module Flok
   end
 end
 
-#Compiler executes all rb code inside this context
+#Compiler executes all rb code (ERB) inside this context
 module Flok
   class UserCompilerContext
     attr_accessor :controllers, :actions, :ons
@@ -31,6 +31,21 @@ module Flok
       @controllers = []
       @actions = []
       @ons = []
+
+      @debug = ENV["FLOK_ENV"] ? true : false
+    end
+
+    #Returns a list of events that this controller 'might' respond to
+    #Used for things like hook event handlers to provide queryable 
+    #information.
+    def might_respond_to
+      @actions.map{|e| e.ons}.flatten.map{|e| e[:name]}
+    end
+
+    #actions_responds_to looks like {"action1" => ["event_a", ..."], "action2" => }...
+    #where each action list contains all the events this action responds to
+    def actions_respond_to
+      @actions.map{|e| [e.name.to_s, e.ons.map{|e| e[:name].to_s}]}.to_h
     end
 
     def get_binding
@@ -85,8 +100,18 @@ module Flok
 
           #Calculate spot index as an offset from the base address using the index of the spot in the spots
           #address offset
-          res = %{
-            
+          res = ""
+
+          if @debug
+            res += %{
+            }
+          end
+
+          res += %{
+            <% if @debug %>
+              if (__base__.constructor !== Number) { throw "Embed for the controller: #{@controller.name} was not given a number for it's __base__ pointer, but of type: " + __base__.constructor + "with the value: " + __base__};
+            <% end %>
+
             var ptr = _embed("#{vc_name}", __base__+#{spot_index}+1, #{context}, __base__);
             __info__.embeds[#{spot_index-1}].push(ptr);
           }
@@ -158,6 +183,8 @@ module Flok
             var old_action = __info__.action;
             __info__.action = "#{action_name}";
 
+            //HOOK_ENTRY[controller_will_goto] #{{"controller_name" => @controller.name, "might_respond_to" => @ctx.might_respond_to, "actions_responds_to" => @ctx.actions_respond_to, "from_action" => @name, "to_action" => action_name}.to_json}
+
             //Remove all views, we don't have to recurse because removal of a view
             //is supposed to remove *all* view controllers of that tree as well.
             var embeds = __info__.embeds;
@@ -494,7 +521,7 @@ module Flok
   end
 
   class UserCompilerAction
-    attr_accessor :controller, :name, :ons, :every_handlers
+    attr_accessor :controller, :name, :every_handlers
     include UserCompilerMacro
 
     def initialize controller, name, ctx, &block
@@ -502,7 +529,7 @@ module Flok
       @name = name
       @ctx = ctx
       @_on_entry_src = ""
-      @ons = [] #Event handlers
+      @_ons = [] #Event handlers
       @every_handlers = []
 
       self.instance_eval(&block)
@@ -518,7 +545,30 @@ module Flok
     end
 
     def on name, js_src
-      @ons << {:name => name, :src => _macro(js_src)}
+      #We need this guard because we run a two pass compile on the ons. When 'ons' is accessed, it is assumed that we are now
+      #in the compilation phase and we build all the entries. This is because some macros in the ons source code requires
+      #prior-knowledge of controller-level information like all possible events in all actions for hooks
+      raise "Uh oh, you tried to add an event handler but we already assumed that compilation took place so we cached everything..." if @__ons_did_build or @__ons_is_building
+
+      @_ons << {:name => name, :src => js_src}
+    end
+
+    def ons 
+      #Return the un-compiled version as some macros access this data and the real ons
+      #would cause infinite recursion
+      return @_ons if @__ons_is_building
+      @__ons_is_building = true
+
+      #We need this guard because we run a two pass compile on the ons. When 'ons' is accessed, it is assumed that we are now
+      #in the compilation phase and we build all the entries. This is because some macros in the ons source code requires
+      #prior-knowledge of controller-level information like all possible events in all actions for hooks
+      unless @__ons_did_build
+        @__ons_did_build = true
+        @__ons = @_ons.map{|e| {:name => e[:name], :src => _macro(e[:src])}}
+      end
+
+      @__ons_is_building = false
+      return @__ons
     end
 
     def every seconds, str

data/lib/flok/user_compiler_templates/ctable.js.erb

@@ -69,6 +69,10 @@ ctable = {
                 handlers: {
                   <% a.ons.each do |e| %>
                     <%= e[:name] %>: function(__base__, params) {
+                        <% if @debug %>
+                          if (__base__.constructor !== Number) { throw "on('<%= e[:name] %>') for the controller: <%= c.name %>:<%= a.name %> was not given a number for it's __base__ pointer, but of type: " + __base__.constructor + "with the value: " + __base__};
+                        <% end %>
+
                       var __info__ = tel_deref(__base__);
                       var context = __info__.context;
                       var current_action = __info__.action;

data/lib/flok/user_hook_generators/goto.rb

@@ -0,0 +1,74 @@
+require_relative 'helpers'
+
+module Flok
+  class GotoHooksDSLEnv
+    attr_accessor :selectors
+
+    def initialize
+      @selectors = []
+    end
+
+    def controller name
+      @selectors << ->(p) { p["controller_name"] and p["controller_name"] == name.to_s }
+    end
+
+    #The previous / next action contains an event handler for...
+    #################################################################################
+    def from_action_responds_to? responds
+      @selectors << lambda do |params|
+        from_action = params["from_action"]
+        actions_respond_to = params["actions_responds_to"] #This is a hash that maps all actions to sensetivity lists
+
+        #Get the sensetivity list if possible for this action (this is the list of events this action responds to)
+        if actions_respond_to[from_action]
+          sensetivity_list = actions_respond_to[from_action]
+
+          #Does the sensetivity list include the event we are interested in?
+          next sensetivity_list.include? responds
+        end
+
+        #The action wasn't even listed on the list, i.e. it has no sensetivity list
+        next false
+      end
+    end
+
+    def to_action_responds_to? responds
+      @selectors << lambda do |params|
+        to_action = params["to_action"]
+        actions_respond_to = params["actions_responds_to"] #This is a hash that maps all actions to sensetivity lists
+
+        #Get the sensetivity list if possible for this action (this is the list of events this action responds to)
+        if actions_respond_to[to_action]
+          sensetivity_list = actions_respond_to[to_action]
+
+          #Does the sensetivity list include the event we are interested in?
+          next sensetivity_list.include? responds
+        end
+
+        #The action wasn't even listed on the list, i.e. it has no sensetivity list
+        next false
+      end
+    end
+    #################################################################################
+  end
+
+  UserHooksToManifestOrchestrator.register_hook_gen :goto do |manifest, params|
+    hook_event_name = params[:hook_event_name]
+
+    #Evaluate User given DSL (params[:block]) which comes from `./confg/hooks.rb`
+    #to retrieve a set of selectors which we will pass the hooks compiler
+    block = params[:block]
+    dsl_env = GotoHooksDSLEnv.new
+    dsl_env.instance_eval(&block)
+
+    #Inject into HOOK_ENTRY[controller_will_goto] that match the given selectors from the DSL
+    #based on the hook entry static parameters
+    entry = HooksManifestEntry.new("controller_will_goto", dsl_env.selectors) do |entry_hook_params|
+      next %{
+        SEND("main", "if_hook_event", "#{hook_event_name}", {});
+      }
+    end
+
+    manifest << entry
+  end
+end

data/lib/flok/user_hook_generators/helpers.rb

@@ -0,0 +1,46 @@
+module Flok
+  #This class helps construct javascript expressions like ((a == 3 || b == 4) && (a == 5 || c == 6))
+  #Usually you have an outer-level JSTermGroup that represents all the things being anded togeather
+  #and then you have multiple inner groups that each represent ored terms. Search POS form on wikipedia
+  #e.g.
+  # #Convert ((a == 3 || b == 4) && (a == 5 || c == 6)) 
+  #
+  # This will hold the entire result
+  # ands = JSTermGroup.new
+  # 
+  # Compute a small section of the result, the group (a == 3 || b == 4) and
+  # then add it as a group of the entire result in || form
+  # ors1 = JSTermGroup.new
+  # ors1 << "a == 3"
+  # ors1 << "b == 4"
+  # ands << ors1.to_or_js
+  #
+  # Same thing but now we compute the second part which is (a == 5 || c == 5)
+  # ors2 = JSTermGroup.new
+  # ors2 << "a == 5"
+  # ors2 << "c == 6"
+  # ands << ors2.to_or_js
+  #
+  # Finally get the result by &&ing all the ||s groups togeather
+  # result = ands.to_and_js
+  class JSTermGroup
+    def initialize
+      @terms = []
+    end
+
+    #Add a javascript expression that evaluates to either true or false. May or may not contain parantheses
+    def << expr
+      @terms << "(#{expr})"
+    end
+
+    #Join expressions via || statements and yield an expression that contains parantheses
+    def to_or_js
+      "(#{[*@terms, "false"].join(" || ")})"
+    end
+
+    #Join expressions via && statements and yield an expression that contains parantheses
+    def to_and_js
+      "(#{[*@terms, "true"].join(" && ")})"
+    end
+  end
+end

data/lib/flok/version.rb

@@ -1,3 +1,3 @@
 module Flok
-  VERSION = "0.0.100"
+  VERSION = "0.0.101"
 end

data/spec/env/kern.rb

@@ -69,7 +69,32 @@ shared_context "kern" do
 
   #Create a new flok project, add the given user_file (an .rb file containing controllers, etc.)
   #and then retrieve a V8 instance from this project's application_user.js
-  def flok_new_user user_controllers_src, service_config=nil, service_src=nil
+  def flok_new_user user_controllers_src, service_config=nil, service_src=nil, hooks_src=nil
+    return flok_new_user_with_src(user_controllers_src, service_config, service_src, hooks_src)[:ctx]
+  end
+
+  #Returns a v8 instance with modifications like handling dispatch of flok
+  #And sets some members (not the greatest)
+  def v8_flok
+    #Execute
+    @driver = FakeDriverContext.new
+    v8 = V8::Context.new(:with => @driver)
+    @ctx = v8
+    @driver.ctx = v8
+    v8.eval %{
+      //We must convert this to JSON because the fake driver will receive
+      //a raw v8 object otherwise
+      function if_dispatch(q) {
+        if_dispatch_json(JSON.stringify(q));
+      }
+    }
+
+    return v8
+  end
+
+  #Create a new flok project, add the given user_file (an .rb file containing controllers, etc.)
+  #and then retrieve a V8 instance from this project's application_user.js
+  def flok_new_user_with_src user_controllers_src, service_config=nil, service_src=nil, hooks_src=nil
     temp_dir = new_temp_dir
     Dir.chdir temp_dir do
       flok "new test"
@@ -78,31 +103,22 @@ shared_context "kern" do
         File.write './app/controllers/user_controller.rb', user_controllers_src
         File.write './config/services.rb', service_config if service_config
         File.write './app/services/service0.rb', service_src if service_src
+        File.write './config/hooks.rb', hooks_src if hooks_src
 
         #Build
         unless flok "build" #Will generate drivers/ but we will ignore that
           raise "Build failed"
         end
 
-        #Execute
-        @driver = FakeDriverContext.new
-        v8 = V8::Context.new(:with => @driver)
-        @ctx = v8
-        @driver.ctx = v8
-        v8.eval %{
-          //We must convert this to JSON because the fake driver will receive
-          //a raw v8 object otherwise
-          function if_dispatch(q) {
-            if_dispatch_json(JSON.stringify(q));
-          }
-        }
-
-        v8.eval File.read('./products/chrome/application_user.js')
-        return v8
+        v8 = v8_flok
+        src = File.read('./products/chrome/application_user.js') 
+        v8.eval src
+        return {:ctx => v8, :src => src}
       end
     end
   end
 
+
   #This supports if_dispatch interface and allows for sending information back via 
   #int_dispatch to the kernel. It is embededd into the v8 context environment
   class FakeDriverContext