kanal 0.3.0

data/lib/kanal/core/core.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require_relative "./conditions/condition_storage"
+require_relative "./conditions/condition_pack_creator"
+require_relative "./router/router_storage"
+require_relative "./hooks/hook_storage"
+require_relative "./helpers/parameter_registrator"
+require_relative "./plugins/plugin"
+require_relative "./input/input"
+require_relative "./services/service_container"
+
+module Kanal
+  module Core
+    #
+    # Main class that end users of Kanal will be using for
+    # initialization, plugin registration, conditions registration, etc
+    #
+    # TODO: consider hiding properties used inside
+    # and provide those dependencies explicitly
+    # e.g.: output_parameter_registrator is needed for router
+    # to create output. It provides the parameters registration
+    # info for the Output object. Can it be explicitly passed into the router
+    # instead of exposing in in Core?
+    #
+    # @!attribute [r] hooks
+    #   @return [Kanal::Core::Hooks::HookStorage] storage which can be used to register hooks
+    # @!attribute [r] services
+    #   @return [Kanal::Core::Services::ServiceContainer] service container for registering and getting services
+    #
+    class Core
+      include Conditions
+      include Router
+      include Helpers
+      include Plugins
+      include Hooks
+      include Services
+
+      # @return [Kanal::Core::Conditions::ConditionStorage]
+      attr_reader :condition_storage
+      # @return [Kanal::Core::Router::RouterStorage]
+      attr_reader :router_storage
+      # @return [Kanal::Core::Helpers::ParameterRegistrator]
+      attr_reader :input_parameter_registrator
+      # @return [Kanal::Core::Helpers::ParameterRegistrator]
+      attr_reader :output_parameter_registrator
+      # @return [Kanal::Core::Hooks::HookStorage]
+      attr_reader :hooks
+      # @return [Kanal::Core::Services::ServiceContainer]
+      attr_reader :services
+
+      def initialize
+        @hooks = HookStorage.new
+        register_hooks
+
+        @condition_storage = ConditionStorage.new
+        @router_storage = RouterStorage.new self
+
+        @input_parameter_registrator = ParameterRegistrator.new
+        @output_parameter_registrator = ParameterRegistrator.new
+
+        @plugins = []
+
+        @services = ServiceContainer.new
+      end
+
+      #
+      # Method for registering plugins. Plugins should be of type
+      # Kanal::Core::Plugins::Plugin. Meaning that any dervied types
+      # would be accepted
+      #
+      # @param [Kanal::Core::Plugins::Plugin] plugin
+      #
+      # @return [void]
+      #
+      def register_plugin(plugin)
+        unless plugin.is_a? Plugin
+          raise "Plugin must be of type Kanal::Core::Plugin or be a class that inherits base Plugin class"
+        end
+
+        begin
+          # Checking if name was provided.
+          name = plugin.name
+
+          # TODO: _log that plugin already registered with such name
+          return if !name.nil? && plugin_registered?(name)
+
+          plugin.setup(self)
+
+          @plugins.append plugin
+          # NOTE: Catching here Exception because metho.name can raise ScriptError (derived from Exception)
+          # and method .setup can raise ANY type of error.
+          # Despite the warnings from linters about "please catch explicitly error or catch StandardError"
+          # - sorry, no can't do here
+        rescue Exception => e
+          name = nil
+
+          begin
+            name = plugin.name
+          rescue Exception
+            name = "CANT_GET_NAME_DUE_TO_ERROR"
+          end
+
+          # TODO: _log this info in critical error instead of raising exception
+          raise "There was a problem while registering plugin named: #{name}. Error: `#{e}`.
+          Remember, plugin errors are often due to .name method not overriden or
+          having faulty code inside .setup overriden method"
+        end
+      end
+
+      #
+      # Get registered plugin for modification of some sort
+      #
+      # @param [Symbol] name <description>
+      #
+      # @return [<Type>] <description>
+      #
+      def get_plugin(name)
+        @plugins.find { |p| p.name == name }
+      end
+
+      #
+      # <Description>
+      #
+      # @param [Symbol] name <description>
+      #
+      # @return [Boolean] <description>
+      #
+      def plugin_registered?(name)
+        !get_plugin(name).nil?
+      end
+
+      #
+      # Method creates instance of Kanal::Core::Input::Input
+      # Note that right before input returned, hook :input_just_created
+      # called
+      #
+      # @return [Kanal::Core::Input::Input] <description>
+      #
+      def create_input
+        input = Input::Input.new @input_parameter_registrator
+
+        @hooks.call :input_just_created, input
+
+        input
+      end
+
+      #
+      # Method registers parameters that can be set/get in Kanal::Core::Input::Input
+      #
+      # @param [Symbol] name <description>
+      # @param [Boolean] readonly <description>
+      #
+      # @return [void] <description>
+      #
+      def register_input_parameter(name, readonly: false)
+        @input_parameter_registrator.register_parameter name, readonly: readonly
+      end
+
+      #
+      # The same as registering input, but for Kanal::Core::Output::Output
+      #
+      # @param [Symbol] name <description>
+      # @param [Boolean] readonly <description>
+      #
+      # @return [void] <description>
+      #
+      def register_output_parameter(name, readonly: false)
+        @output_parameter_registrator.register_parameter name, readonly: readonly
+      end
+
+      #
+      # Handy method with DSL (Domain Specific Language) that allows
+      # condition makers to easily create condition packs and
+      # conditions.
+      #
+      # @param [Symbol] name <description>
+      # @yield block with inner DSL for adding conditions to condition pack
+      #
+      # @return [void] <description>
+      #
+      def add_condition_pack(name, &block)
+        creator = ConditionPackCreator.new name
+
+        pack = creator.create(&block)
+
+        @condition_storage.register_condition_pack pack
+      end
+
+      #
+      # Gets router by the name or if no argument
+      # provided, creates and gets :default router
+      # This method usually used without arguments,
+      # only in special cases you might need to create separate routers
+      # TODO: is creating different routers actually needed? Within the same core
+      # What cases are possible for such behaviour? Maybe we should remove the ability...
+      #
+      # @param [Symbol] name <description>
+      #
+      # @return [Kanal::Core::Router::Router] <description>
+      #
+      def router(name = :default)
+        @router_storage.get_or_create_router name
+      end
+
+      def register_hooks
+        @hooks.register :input_just_created # input
+        @hooks.register :input_before_router # input
+        @hooks.register :output_before_returned # input, output
+      end
+
+      private :register_hooks
+    end
+  end
+end

data/lib/kanal/core/helpers/condition_finder.rb

@@ -0,0 +1,26 @@
+module Kanal
+  module Core
+    module Helpers
+      module ConditionFinder
+        class ConditionFindResult
+          attr_reader :found_condition_pack,
+                      :found_condition
+
+          def initialize(found_condition_pack: false, found_condition: false)
+            @found_condition_pack = found_condition_pack
+            @found_condition = found_condition
+          end
+
+          def found_anything?
+            @found_condition || @found_condition_pack
+          end
+        end
+
+        class ConditionFinder
+          def find_by_name(name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kanal/core/helpers/parameter_bag.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Kanal
+  module Core
+    module Helpers
+      # Generic parameter bag class that stores named parameters
+      class ParameterBag
+        def initialize
+          @parameters = {}
+        end
+
+        def get(name)
+          @parameters[name]
+        end
+
+        def set(name, value)
+          @parameters[name] = value
+        end
+      end
+    end
+  end
+end

data/lib/kanal/core/helpers/parameter_bag_with_registrator.rb

@@ -0,0 +1,46 @@
+require_relative "parameter_bag"
+
+module Kanal
+  module Core
+    module Helpers
+      # Parameter bag but it checks registrator for existence of parameters
+      # and if they are has needed by registrator allowances, types etc, whatever
+      # registrator rules are stored for property
+      class ParameterBagWithRegistrator < ParameterBag
+        def initialize(registrator)
+          super()
+          @registrator = registrator
+        end
+
+        def get(name)
+          validate_parameter_registration name
+
+          super name
+        end
+
+        def set(name, value)
+          validate_parameter_registration name
+
+          readonly = @registrator.get_parameter_registration_if_exists(name).readonly?
+
+          if readonly
+            value_exists = !get(name).nil?
+
+            if value_exists
+              raise "Parameter #{name} is marked readonly! You tried to set it's value, but
+              it already has value."
+            end
+          end
+
+          super name, value
+        end
+
+        def validate_parameter_registration(name)
+          unless @registrator.parameter_registered? name
+            raise "Parameter #{name} was not registered! Did you forget to register that parameter?"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kanal/core/helpers/parameter_finder_with_method_missing_mixin.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Kanal
+  module Core
+    module Helpers
+      # Module assumes that class where it was included has methods
+      # set(name, value)
+      # get(name)
+      # transforms unknown methods to setters/getters for parameters
+      module ParameterFinderWithMethodMissingMixin
+        def method_missing(symbol, *args)
+          parameter_name = symbol.to_s
+          parameter_name.sub! "=", ""
+
+          parameter_name = parameter_name.to_sym
+
+          # standard workflow with settings properties with
+          # input.prop = 123
+          if symbol.to_s.include? "="
+            @parameter_bag.set parameter_name, args.first
+          else
+            # this approach can be used also in dsl
+            # like that
+            # setters: prop value
+            # getters: prop
+            if !args.empty?
+              # means it is used as setter in dsl,
+              # method call with argument
+              @parameter_bag.set(parameter_name, *args)
+            else
+              @parameter_bag.get parameter_name
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kanal/core/helpers/parameter_registrator.rb

@@ -0,0 +1,48 @@
+module Kanal
+  module Core
+    module Helpers
+      # For registered property info,
+      # this class is used for future additions,
+      # maybe type validations or something
+      class ParameterRegistration
+        def initialize(readonly)
+          @readonly = readonly
+        end
+
+        def readonly?
+          @readonly
+        end
+      end
+
+      # Class holds parameter names that are allowed
+      # to be used.
+      class ParameterRegistrator
+        def initialize
+          @parameters_by_name = {}
+        end
+
+        # readonly paramaeter means that once it was initialized - it cannot
+        # be changed. handy for input parameters populated by interface or
+        # whatever
+        def register_parameter(name, readonly: false)
+          raise "Parameter named #{name} already registered!" if @parameters_by_name.key? name
+
+          registration = ParameterRegistration.new readonly
+
+          @parameters_by_name[name] = registration
+        end
+
+        # returns nil if no parameter registered
+        def get_parameter_registration_if_exists(name)
+          return nil unless @parameters_by_name.key? name
+
+          @parameters_by_name[name]
+        end
+
+        def parameter_registered?(name)
+          !get_parameter_registration_if_exists(name).nil?
+        end
+      end
+    end
+  end
+end

data/lib/kanal/core/helpers/router_proc_parser.rb

@@ -0,0 +1,47 @@
+require "method_source"
+
+module Kanal
+  module Core
+    module Helpers
+      # Class helps with parsing router procs for
+      # helping forming handy DSL without commas
+      class RouterProcParser
+        def get_conditions_method_names_from_block(&block)
+          source = block.source.to_s
+
+          method_names = []
+
+          lines = source.split "\n"
+
+          lines.each do |l|
+            names = get_method_names_from_line l
+
+            method_names.concat names
+          end
+
+          method_names.uniq
+        end
+
+        def get_method_names_from_line(line)
+          method_names = []
+
+          line = line.lstrip
+
+          return method_names unless line.start_with? "on"
+
+          words = line.split
+
+          condition_pack = words[1]
+          condition = words[2]
+
+          method_names.append condition_pack
+          method_names.append condition
+
+          method_names
+        end
+
+        private :get_method_names_from_line
+      end
+    end
+  end
+end

data/lib/kanal/core/hooks/hook_storage.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Kanal
+  module Core
+    module Hooks
+      #
+      # Allows hooks registration,
+      # attaching to hooks, calling hooks with arguments
+      #
+      class HookStorage
+        def initialize
+          @listeners = {}
+        end
+
+        #
+        # Registers hook in storage. All you need is name
+        #
+        # @example Registering a hook
+        #   hook_storage.register(:my_hook) # That is all
+        #
+        # @param [Symbol] name <description>
+        #
+        # @return [void] <description>
+        #
+        # TODO: think about requiring optional string about hook arguments?
+        # like register(:my_hook, "name, last_name")
+        # or is it too weird and unneeded? I mean besides the documentation
+        # there is no way to learn which arguments are used in specific hook.
+        # Wondrous world of dynamic languages 🌈🦄
+        #
+        def register(name)
+          return if hook_exists? name
+
+          @listeners[name] = []
+        end
+
+        #
+        # Calling hook with any arguments you want.
+        # Well, when you registered hooks you basically had in mind
+        # which arguments should be used when calling them
+        #
+        # @example Calling hook with arguments
+        #   # Considering names variables (old_name, new_name) are available when calling a hook
+        #   # This one will call the :name_changed hook with passed arguments.
+        #   # What does that mean? That possibly there is a listener attached to this hook
+        #   # @see #attach for next step of this example
+        #   hook_storage.call :name_changed, old_name, new_name
+        #
+        # @param [Symbol] name <description>
+        # @param [Array] args <description>
+        #
+        # @return [void] <description>
+        #
+        def call(name, *args)
+          raise "Cannot call hook that is not registered: #{name}" unless hook_exists? name
+
+          @listeners[name].each do |l|
+            l.method(:hook_block).call(*args)
+          end
+        rescue RuntimeError => e
+          raise "There was a problem with calling hooks #{name}. Args: #{args}. More info: #{e}"
+        end
+
+        #
+        # Attaches block to a specific hook.
+        # You can learn about available hooks by
+        # looking into documentation of the specific libraries,
+        # using this class.
+        #
+        # @example Attaching to name changing hook, the next step after @see #call example
+        #   hook_storage.attach :name_changed do |old_name, new_name|
+        #     # Here you do something with the provided arguments
+        #   end
+        #
+        # NOTE: about weird saving objects with methods instead of blocks
+        # see more info in Condition class, you will learn why (hint: LocalJumpError)
+        #
+        # @param [Symbol] name <description>
+        # @yield block that will be executed upon calling hook it was registered to
+        #
+        # @return [void] <description>
+        #
+        def attach(name, &block)
+          unless hook_exists? name
+            raise "You cannot listen to hook that does not exist! Hook in question: #{name}"
+          end
+
+          proc_to_lambda_object = Object.new
+          proc_to_lambda_object.define_singleton_method(:hook_block, &block)
+
+          @listeners[name].append proc_to_lambda_object
+        end
+
+        #
+        # Self explanatory name of method
+        #
+        # @param [Symbol] name <description>
+        #
+        # @return [Boolean] <description>
+        #
+        def hook_exists?(name)
+          !@listeners[name].nil?
+        end
+
+        private :hook_exists?
+      end
+    end
+  end
+end

data/lib/kanal/core/input/input.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "../helpers/parameter_finder_with_method_missing_mixin"
+require_relative "../helpers/parameter_bag_with_registrator"
+
+module Kanal
+  module Core
+    module Input
+      # This class contains all the needed input properties
+      class Input
+        include Helpers
+        include Helpers::ParameterFinderWithMethodMissingMixin
+
+        def initialize(parameter_registrator)
+          @parameter_bag = ParameterBagWithRegistrator.new parameter_registrator
+        end
+      end
+    end
+  end
+end

data/lib/kanal/core/interfaces/interface.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "../core"
+
+module Kanal
+  module Core
+    module Interfaces
+      # Basic class of interface - interface is basically
+      # what is creating inputs and consumes output from the routers
+      class Interface
+        attr_reader :core
+
+        #
+        # Interface makes all neded configuration, plugin registrations,
+        # properties registration in the constructor, which requires core.
+        # Originally, there was thoughts of interfaces as top level building
+        # blocks for ecosystem, this is why interfaces are doing stuff with core
+        # inside constructors. It was originally thought that main application
+        # file will host like multiple interfaces.
+        # This is also why interfaces had no argument core in constructor,
+        # because they created cores inside.
+        #
+        # @param [Kanal::Core::Core] core <description>
+        #
+        def initialize(core)
+          @core = core
+        end
+
+        #
+        # Returns default router from core
+        #
+        # @return [Kanal::Core::Router::Router] <description>
+        #
+        def router
+          @core.router
+        end
+
+        def modify_core(&block)
+          block.call @core
+        end
+
+        #
+        # Starting the interface, all the needed
+        # machinery for it to fire up goes here
+        #
+        # @return [void] <description>
+        #
+        def start
+          raise NotImplementedError
+        end
+
+        #
+        # Yet to be discovered how to use this.
+        # If method #start executes some synchronous code, how would
+        # we stop it from outside? I mean maybe with some kind of flag variable inside?
+        #
+        # @return [<Type>] <description>
+        #
+        def stop
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/kanal/core/logger/logger.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Kanal
+  module Core
+    module Logger
+      class Logger < ::Logger
+      end
+    end
+  end
+end

data/lib/kanal/core/output/output.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "../helpers/parameter_finder_with_method_missing_mixin"
+require_relative "../helpers/parameter_bag_with_registrator"
+
+module Kanal
+  module Core
+    module Output
+      # Base class for constructing output that will be given
+      # from router node
+      class Output
+        include Helpers
+        include Helpers::ParameterFinderWithMethodMissingMixin
+
+        attr_reader :input, :core
+
+        def initialize(parameter_registrator, input, core)
+          @input = input
+          @core = core
+          @parameter_bag = ParameterBagWithRegistrator.new parameter_registrator
+        end
+
+        def configure_dsl(&block)
+          instance_eval(&block)
+        end
+
+        private :core
+      end
+    end
+  end
+end