gexp 0.0.3 → 0.0.4

data/docs/commands_handling.mdoc

@@ -0,0 +1,72 @@
+# Обработка команд
+
+С примером обработки команд можно ознакомиться
+в спецификации
+
+```
+spec/gexp/item_spec.rb
+```
+
+Данный документ содержит описание взаимодействия объектов при получении запроса от сервера.
+
+### Описание внешнего API
+
+Основным классом по внешниму взаимодействию
+является абстрактный класс Gexp::Receiver.
+
+Его конечная реализация должна обеспечивать транзакционность выполнения пачки (batch) комманд (пример находится в lib/gexp/receiver/example.rb).
+
+Интерфейс состоит из нескольких операций
+
+1) Создание объекта Receiver
+
+```ruby
+  Gexp::Receiver::Example.new user, request
+```
+
+В конструктор объекта передается объект пользователя (над которым может осуществляться транзакция) а также объект запроса вида
+
+{
+  params: {
+    sended_at: <>,
+    created_at: <>,
+    commands: [...]
+  }
+}
+
+В параметре commands находится содержимое пачки команд (batch), в виде хешей вида
+
+{
+  event: :<event_name>,
+  stage: { x: <0>, y: <0> },
+  rewards: { <resource_name>: <value> },
+  timestamp: <0.0>,
+  objects: { '<class_name>': '<hash_id>' },
+  transition: { <from_state>: <to_state> },
+  seed: <random_seed>
+}
+
+```
+TODO: Сделать objects и transition массивами хешей, чтобы задавать переходы для каждого объекта
+```
+
+2) Создание комманд
+
+При создании объекта Receiver создается объект
+Gexp::Command::Stack, который выражает пачку команд.
+
+При создании этого объекта создаются объекты под каждую команду.
+
+Команда имет 4 состояния
+
+1. new - создана
+2. active - начала исполнение
+3. done - выполнена успешно
+4. failed - проваленна
+
+У команды есть поля
+
+* errors - массив ошибок
+* context - хеш контекста
+* params - первоначальные параметры
+* event - событие

data/docs/notes.mdoc

@@ -0,0 +1,19 @@
+# FAQ
+
+* Как передается окружение в обработчик?
+  
+  - Через команду. Объект команды передается вместе с событием
+    и передается в калбеки обработки в качетве актора.
+
+    В калбеках из него извлекаются обработчики и исполняются
+
+* Как выполняются действия над пользователем?
+  - Он фигурирует в команде в качетве объекта, те
+    события над пользователем также вызываются
+    через FSM. Так проще контролировать доступ 
+    к функционалу
+
+* Как передаются другие контексты?
+  - У команды есть объект context
+* Как передаются контекст друга?
+* Как извлекаются обработчики?

data/gexp.gemspec

@@ -24,6 +24,7 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency "rr"
   gem.add_development_dependency "rake"
   gem.add_development_dependency "pry"
+  gem.add_development_dependency "configuration"
   gem.add_development_dependency "state_machine"
   gem.add_development_dependency "activesupport"
   gem.add_development_dependency 'bson', '= 1.8.0'

data/lib/examples/item_example.rb

@@ -1,33 +1,38 @@
-class ItemExample
-  class << self
-    def inherited(sub)
-      sub.instance_eval do
-        include Gexp::Object
-      end
-    end
-
-    def register
-      @register ||= {}
-
-      if @register.empty?
-        register = Configuration.for 'register'
-        register.keys.each do |key|
-          @register[key] = Configuration.for(key).to_hash
-        end
-      end
-
-      @register
-    end
-
-    def reload_register!
-      @register = {}
-    end
-
-  end
+require 'configuration'
+
+Configuration.for(:item_example) do
+  states {
+    initial :created
+    states { # TODO!: Переименовать в transitions
+             # для этого нужны изменения в Gexp::Handler::Transition::Builder
+      created {
+        prebuilded {
+          modify [
+            [ :resources, :subject, { wood: -5, energy: -1 } ],
+          ]
+        }
+      }
+      prebuilded {}
+      postbuild {}
+      builded {}
+    }
+
+    events {
+      pick [
+        { from: :created, to: :prebuilded },
+        { from: :prebuilded, to: :postbuilded },
+        { from: :postbuilded, to: :builded },
+        { from: :builded, to: :builded },
+      ]
+    }
+  }
+end
 
-  attr_accessor :current_command
+class ItemExample
 
   include Mongoid::Document
+  include Gexp::Item
+  include Gexp::Object
 
   field :state, type: String, default: 'created'
   field :uid, type: String
@@ -40,29 +45,4 @@ class ItemExample
     where(_type: klass, uid: uid, social_type_id: social_type_id) 
   }
 
-  # TODO: по возможности переделать на Mongoid::Observer или скрыть из конфига
-  def around_handlers(transition, &block)
-    self.check_handlers(transition)
-    self.before_event(transition)
-    #require 'pry'
-    #binding.pry
-    block.call
-    self.after_event(transition)
-    self.modify_handlers(transition)
-  rescue => e
-    raise
-  end
-
-  def before_event(transition)
-  end
-
-  def after_event(transition)
-  end
-
-  def check_handlers(transition)
-  end
-
-  def modify_handlers(transition)
-  end
-
 end

data/lib/examples/user_example.rb

@@ -1,9 +1,12 @@
 class UserExample
+
   include Mongoid::Document
+  include Gexp::User
 
-  field :energy, type: Integer
-  field :exp, type: Integer
-  field :exp_level, type: Integer
+  field :energy, type: Integer, default: 0
+  field :exp, type: Integer, default: 0
+  field :exp_level, type: Integer, default: 0
+  field :wood, type: Integer, default: 0
 
   def max_energy
     [ 10, 40, 50, 60, 80, 90, 100][self.exp_level || 0]
@@ -11,4 +14,5 @@ class UserExample
 
   def after_change!(param)
   end
+
 end

data/lib/gexp/command.rb

@@ -2,6 +2,8 @@
 require 'state_machine/core'
 
 module Gexp
+
+  # ,Базовый класс комманд
   class Command
 
     extend StateMachine::MacroMethods
@@ -10,6 +12,12 @@ module Gexp
     attr_accessor :context
     attr_accessor :params
 
+    attr_accessor :event # TODO: only getter
+
+    attr_accessor :object
+    attr_accessor :subject
+    attr_accessor :provider
+
     state_machine :initial => :new do
       state :active
       state :done
@@ -35,6 +43,9 @@ module Gexp
       super() # Инициализация StateMachine
     end
 
+    # индетификатор комманды
+    #
+    # @return [String]
     def hash
       # TODO: Заменить на BSON:ObjectId
       [
@@ -44,10 +55,15 @@ module Gexp
       ].join('_')
     end
 
+    # Заглушка для исполнения команды
+    #
+    # @raise NotImplementedError
     def perform
       self.activate!
       self.failure!
-      raise 'Not defined perform method'
+
+      raise NotImplementedError.new \
+        'Not defined perform method'
     end
 
   end

data/lib/gexp/command/object.rb

@@ -1,9 +1,14 @@
 module Gexp
   class Command
-    class Object < self
 
-      attr_accessor :event # TODO: only getter
-      attr_accessor :object
+    # Объектная команда
+    #
+    # Команда выполняющаяся над объектами
+    # игрового мира.
+    #
+    # Выполняет событие FSM у объекта описанное
+    # в параметрах.
+    class Object < self
 
       def initialize(params = {})
         super
@@ -11,15 +16,25 @@ module Gexp
         self.load_object
       end
 
+      # Выполнение команды
       def perform
         self.activate!
-        @object.send(self.event)
+        @object.send(self.event, self)
         self.complete!
       rescue => e
-        self.errors << e
         self.failure!
+        self.errors << e
+        raise e
       end
 
+      def subject
+        self.context.user
+      end
+
+      #def provider
+      #  self.context.friend
+      #end
+
       protected
 
         def load_object

data/lib/gexp/command/stack.rb

@@ -1,5 +1,10 @@
 module Gexp
   class Command
+
+    # Стек комманд.
+    #
+    # Принимает реквест и разбивает его
+    # батч на команды
     class Stack
 
       include Enumerable
@@ -9,14 +14,20 @@ module Gexp
       def initialize(user, request)
         @user     = user
         @request  = request
-        @commands = {} # for ruby 1.9.x
+        @commands = {} # для ruby 1.9.x иначе OrderedHash
         self.fill()
       end
 
+      # Фабрика команд по их параметрам
       def build_command(command_param = {})
+        # XXX: пока один поддерживаемый тип комманд
+        # TODO: Расширять типы команд отсюда,
+        # возможно нужен конфиг соотвествия
+        # Тип События - Тип команды
         Gexp::Command::Object.new(command_param)
       end
 
+      # Заполняет хеш команд по реквесту
       def fill(request = nil)
         request ||= @request
         @commands = {}
@@ -31,12 +42,15 @@ module Gexp
         @commands.size
       end
 
+      # Просто перебор команд для Enumerable
       def each(&block)
         @commands.each(&block)
       end
 
       protected
 
+        # Добавляет команду в общий хеш
+        # и задает контекст
         def add(command)
           command.context = self
           if @commands[command.hash].present?

data/lib/gexp/handler.rb

@@ -2,23 +2,23 @@ module Gexp
   class Handler
     # Базовый класс обработчиков
 
-    attr_accessor :user, :object
+    attr_accessor :user, :object, :params, :objects
 
-    #
-    #
-    # object - объект над котым производится обработка
-    #
-    #
+    # @params [Object] object - объект над котым производится обработка
+    # @params [Hash] params
+    # @params [Array] objects
+    # @params [] 
     def initialize(object = nil, params = {}, objects = nil, full_params = nil)
       @object      = object
       @params      = params
       @objects     = objects
-      @user        = (@objects || {})[:self]
+      @user        = (@objects || {})[:subject]
       @full_params = full_params
     end
 
     def process(params = nil)
-      raise 'Override process handler method'
+      raise NotImplementedError.new \
+        'Override process handler method'
     end
 
   end

data/lib/gexp/handler/modify/resources.rb

@@ -49,6 +49,7 @@ module Gexp
         def process(params = {}, &block)
           @changes = {}
           @params = params if @params.empty?
+          @params = @params.first if @params.is_a?(Array)
           @params.each do |resource, value|
             if @user.respond_to?(resource.to_sym)
 

data/lib/gexp/handler/producer.rb

@@ -7,18 +7,21 @@ module Gexp
     # из конфигурационного файл объекта
     class Producer
 
-      def self.namespaces
-        {
-          chekers: Gexp::Handler::Check,
-          modifiers: Gexp::Handler::Modify,
-        }
+      class << self
+
+        # @return [Hash] - хеш классов обработчиков 
+        def namespaces
+          {
+            chekers:   Gexp::Handler::Check,
+            modifiers: Gexp::Handler::Modify,
+          }
+        end
+
       end
 
-      #
-      #
-      # params - handler params { klass, object, args }
-      # type - chekers|modifiers # TODO: избавиться от этого параметра
-      # objects - { object: <...>, subject: <...>, provider: <...>  }
+      # @params [Hash] params  - handler params { klass, object, args }
+      # @params [String] type  - chekers|modifiers # TODO: избавиться от этого параметра
+      # @params [Hash] objects - { object: <...>, subject: <...>, provider: <...>  }
       def initialize(params, type = nil, objects = {})
         @params  = params
         @type    = type
@@ -29,12 +32,17 @@ module Gexp
         end
       end
 
+      # Создает и возвращает класс обработчика
+      #
+      # @return [Gexp::Handler]
       def emit
         args = @params.clone
 
         if for_klass?
           superclass = self.class.namespaces[@type]
-          subclass   = args.shift.to_s.classify
+          subclass   = args.shift.to_s.humanize
+
+          # TODO: Сделать проверку существования класса
           klass      = superclass.const_get(subclass)
         else
           klass  = Gexp::Handler::Caller
@@ -48,13 +56,19 @@ module Gexp
 
       protected
 
-      def for_klass?
-        @params.size == 3
-      end
+        # Параметры под класс
+        #
+        # @return [Boolean]
+        def for_klass?
+          @params.size == 3
+        end
 
-      def for_caller?
-        @params.size == 2
-      end
+        # Параметры под коллер
+        #
+        # @return [Boolean]
+        def for_caller?
+          @params.size == 2
+        end
 
     end
   end