lib/ass_ole/snippets/shared.rb in ass_ole-snippets-shared-0.3.2 vs lib/ass_ole/snippets/shared.rb in ass_ole-snippets-shared-0.4.0

@@ -1,11 +1,39 @@
 require 'ass_ole/snippets/shared/version'
 require 'ass_ole'
 
 module AssOle
   module Snippets
-    # Shared Ole snippets
+    # Shared Ole snippets.
+    #
+    # Object included snippets must +respond_to? ole_connector+ and returns
+    # 1C OLE connector or includes +AssOle+ runtime using: +like_ole_runtime+
+    # method defined in +ass_ole+ gem.
+    # @example
+    #   require 'ass_ole'
+    #   require 'ass_ole/snippets/shared'
+    #   require 'ass_maintainer/info_base'
+    #
+    #   # External connection runtime
+    #   module ExternalRuntime
+    #     is_ole_runtime :external
+    #   end
+    #
+    #   class Worker
+    #     like_ole_runtime ExternalRuntime
+    #     include AssOle::Snippets::Shared::Query
+    #
+    #     def initialize(connection_string)
+    #       ole_runtime_get.run AssMaintainer::InfoBase.new('ib_name', connection_string)
+    #     end
+    #
+    #     def select(value)
+    #       query('select &arg as arg', arg: value).Execute.Unload.Get(0).arg
+    #     end
+    #   end
+    #
+    #   Worker.new('File="path"').select('Hello') #=> "Hello"
     module Shared
       # Snippet for serialize and deserilize 1C objects to xml
       # @note In external runtime it will be cause of a fail in +InfoBase#rm!+
       #  '... /1Cv8.1CD (Errno::EBUSY)'  because external connection
       #  realy keep alive
@@ -79,18 +107,41 @@
         def temp_tables_manager
           newObject 'TempTablesManager'
         end
       end
 
+      # @deprecated Use {InTransactionDo} instead
+      # @todo remove module in v1.0.0
       # Do in transaction wrapper
       module Transaction
         is_ole_snippet
 
+        def self.depricate
+          Kernel.warn '[DEPRICATION]'\
+            " '#{self.name}` is deprecated and will be"\
+            " removed soon. Please use "\
+            '\'AssOle::Snipptes::Shared::InTransactionDo` instead.'\
+        end
+
+        [method(:included), method(:extended)].each do |old_method|
+          name = old_method.name
+          old = "_depricate_#{name}"
+          singleton_class.class_eval {
+            alias_method old, name
+            define_method name do |*args, &block|
+              AssOle::Snippets::Shared::Transaction.depricate
+              send old, *args, &block
+            end
+          }
+        end
+
         # rubocop:disable Metrics/MethodLength
 
+        # @deprecated Use {InTransactionDo#in_transaction} instead
         # @raise [RuntimeError] if nested transaction
         def do_in_transaction(&block)
+          AssOle::Snippets::Shared::Transaction.depricate
           fail ArgumentError, 'Block require' unless block_given?
           fail 'Nested transaction is mindless in 1C runtime' if\
             transactionActive
           begin
             beginTransAction
@@ -108,8 +159,9 @@
 
       require 'ass_ole/snippets/shared/mapped'
       require 'ass_ole/snippets/shared/array'
       require 'ass_ole/snippets/shared/binary_data'
       require 'ass_ole/snippets/shared/value_table'
+      require 'ass_ole/snippets/shared/in_transaction_do'
     end
   end
 end