file_transactions 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c00351141cff6a4cbbe25c582306665eb384d2f8491345c25e13683cb8d464c
-  data.tar.gz: 175b7c985bff046e4410f344b2fcd8c7c809af194b47c59c8602a203b08b9d26
+  metadata.gz: 877914f1551238a6f03b03e24f4670b247a3df7339303d2b174db0ba2a60b2ff
+  data.tar.gz: 06b545de3377911e4502f35788fe10e2034daf51a319c9d80830aa11c28588d7
 SHA512:
-  metadata.gz: c5b8cd9c28f375321294ae2a90a7afade3343d3366e4a86af2be3d78cc9719962012b2a1a6c39a2d19d6f1f565f7d8df91230ba4f477f38d2e95a5b57c4d9816
-  data.tar.gz: '097de30c6a7554dfe73264399e138f99812e317232090a47c7d979234dfbb9b1f545b877e5024be7c90111e997a4c62cb2dae45993bbcf62bd262a62e27a98bf'
+  metadata.gz: 96b18e2d349cbcde39e6c2b870d88a156ff7de0a9a0f7dc458418ef68a0610487090a8611d9068ef2e85abfc89a5f3dd1de2fd3311ccf2eba461a593b41f54f1
+  data.tar.gz: 41ab3cf26cfbc1f908ed1064f3503fd9e6a0d83b87b76d9a6a26c475d8a3991529c0297fe1940f4972b19e0057af2bf8f14bb30af8f1e5e6a1a86f59c2eeba69

data/lib/file_transactions.rb

@@ -11,6 +11,37 @@ require 'file_transactions/move_file_command'
 require 'file_transactions/transaction'
 
 module FileTransactions
+  # This method runs the block inside a transaction
+  #
+  # ==== Examples
+  #
+  #   FileTransactions.transaction do
+  #     CreateFileCommand.execute('new_file') { 'hello' }
+  #     ChangeFileCommand.execute('new_file') { 'world' }
+  #   end
+  #  
+  #   FileTransactions.transaction do
+  #     CreateFileCommand.execute('new_file') { 'hello' }
+  #     DeleteFileCommand.execute('some_file')
+  #  
+  #     # An exception will make the transaction be rolled back. E.g
+  #     # 'new_file' will be removed again and 'some_file' will be restored
+  #     raise "foobar"
+  #   end
+  #  
+  #   # Create an alias for FileTransactions
+  #   FT = FileTransactions
+  #
+  #   FT.transaction do
+  #     CreateFileCommand.execute('new_file') { 'hello' }
+  #  
+  #     FT.transaction do
+  #       ChangeFileCommand.execute('new_file') { 'world' }
+  #  
+  #       # This rolls back the current transaction but not the outer transaction
+  #       raise FT::Rollback
+  #     end
+  #   end
   def self.transaction(&block)
     Transaction.run(&block)
   end

data/lib/file_transactions/change_file_command.rb

@@ -4,9 +4,35 @@ require 'fileutils'
 require 'tmpdir'
 
 module FileTransactions
+  # This command supports making changes to files.
+  # The block passed to +::new+ must either return a +String+, in which case
+  # the file content will be replace with that string.
+  # Or the block must itself modify the file with desired changes (and return anything but a String).
+  #
+  # When this command has been executed, the file can be restored to the
+  # previous state again by calling #undo.
+  #
+  # ==== Examples
+  #
+  #  # Pass in the filename  name to ::new
+  #  cmd1 = ChangeFileCommand.new('some_existing_file') do
+  #    <<~EOF
+  #      Some content to that should
+  #      replace the current file content.
+  #    EOF
+  #  end
+  #
+  #  # Files can also be modified manually.
+  #  # Note: the block gets name as argument.
+  #  cmd2 = ChangeFileCommand.new('another_existing_file') do |name|
+  #    File.open(name, 'a') do |f|
+  #      f.write("Add some more stuff at the end\n")
+  #    end
+  #  end
   class ChangeFileCommand < BaseCommand
     attr_reader :name, :block
 
+    # @param name [String] The name of the file to be changed. May be just a name or an absolut or relative path
     def initialize(name, &block)
       @name = name
       @block = block

data/lib/file_transactions/create_directory_command.rb

@@ -3,24 +3,23 @@
 require 'fileutils'
 
 module FileTransactions
+  # This command creates a new directory. It will also create parent
+  # directories if the given path contains directories that doesn't exist.
+  #
+  # When this command has been executed, the created directories can be removed
+  # again by calling #undo.
+  #
+  # ==== Examples
+  #
+  #  # Pass in the new directory name to ::new
+  #  cmd1 = CreateDirectoryCommand.new('directory_name')
+  #
+  #  # The new directory name may be a path of multiple non exsting directories (like `mkdir -p`)
+  #  cmd2 = CreateDirectoryCommand.new('non_existing_dir1/non_existing_dir2/new_dir')
   class CreateDirectoryCommand < BaseCommand
     attr_reader :name
 
-    # Create new command for creating directories. N
-    #
-    # @param name [String]
-    #
-    # ==== Attributes
-    #
-    # * +name+ - The name of the directory to be created
-    #
-    # ==== Examples
-    #
-    #  # Pass in the new directory name to ::new
-    #  cmd1 = CreateDirectoryCommand.new('directory_name')
-    #
-    #  # The new directory may be a path of multiple non exsting directories (like `mkdir -p`)
-    #  cmd2 = CreateDirectoryCommand.new('non_existing_dir1/non_existing_dir2/new_dir')
+    # @param name [String] The name of the new directory. May be just a name or an absolut or relative path
     def initialize(name)
       @name = name
     end

data/lib/file_transactions/create_file_command.rb

@@ -1,9 +1,35 @@
 # frozen_string_literal: true
 
 module FileTransactions
+  # This command creates a new file. It will also create parent
+  # directories if the given path contains directories that doesn't exist.
+  # The block passed to +::new+ must either return a +String+ with the content
+  # that will be written to the new file. Or the block must itself create the file
+  # with the filname +name+ (and return anything but a String).
+  #
+  # When this command has been executed, the created file (and any directories)
+  # can be removed again by calling #undo.
+  #
+  # ==== Examples
+  #
+  #  # Pass in the new directory name to ::new
+  #  cmd1 = CreateFileCommand.new('new_name') do
+  #    <<~EOF
+  #      Some content to be
+  #      written to the file.
+  #    EOF
+  #  end
+  #
+  #  # Files can also be created manually.
+  #  # Note: the block gets name as argument.
+  #  cmd2 = CreateFileCommand.new('another_file') do |name|
+  #    GenerateAwesomeReport.call(filename: name)
+  #    true
+  #  end
   class CreateFileCommand < BaseCommand
     attr_reader :name, :block
 
+    # @param name [String] The name of the new directory. May be just a name or an absolut or relative path
     def initialize(name, &block)
       @name = name
       @block = block

data/lib/file_transactions/delete_file_command.rb

@@ -4,9 +4,19 @@ require 'fileutils'
 require 'tmpdir'
 
 module FileTransactions
+  # This command supports deleting a file.
+  #
+  # When this command has been executed, the file can be restored by calling
+  # #undo
+  #
+  # ==== Examples
+  #
+  #  # Pass in the filename  name to ::new
+  #  cmd1 = DeleteFileCommand.new('some_existing_file')
   class DeleteFileCommand < BaseCommand
     attr_reader :name, :block
 
+    # @param name [String] The name of the file to be deleted. May be just a name or an absolut or relative path
     def initialize(name)
       @name = name
     end

data/lib/file_transactions/move_file_command.rb

@@ -1,9 +1,21 @@
 # frozen_string_literal: true
 
 module FileTransactions
+  # This command supports moveing (renaming) a file. It will also create parent
+  # directories if the given path contains directories that doesn't exist.
+  #
+  # When this command has been executed, the file can be moved back to the
+  # original location again by calling #undo. Any directories created during
+  # #execute will be deleted.
+  #
+  # ==== Examples
+  #
+  #  cmd1 = MoveFileCommand.new('some_existing_file', 'some_new_dir/a_new_name')
   class MoveFileCommand < BaseCommand
     attr_reader :from, :to
 
+    # @param from [String] The name of the source file to be renamed. May be just a name or an absolut or relative path
+    # @param to [String] The target name of the file. May be just a name or an absolut or relative path
     def initialize(from:, to:)
       @from = from
       @to = to

data/lib/file_transactions/transaction.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module FileTransactions
+  # A class that keeps track of commands and nested transactions. If an
+  # exception is raised inside the transaction, then all commands and nested
+  # transactions get undone.
   class Transaction
     class << self
       def run(&block)

data/lib/file_transactions/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FileTransactions
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: file_transactions
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Sammy Henningsson
@@ -30,12 +30,16 @@ cert_chain:
   ZMhjYR7sRczGJx+GxGU2EaR0bjRsPVlC4ywtFxoOfRG3WaJcpWGEoAoMJX6Z0bRv
   M40=
   -----END CERTIFICATE-----
-date: 2020-06-18 00:00:00.000000000 Z
+date: 2020-06-20 00:00:00.000000000 Z
 dependencies: []
 description: |
-  A set of file operation that can be undone or wrapped in a
-  transaction. If the transaction is rolled back then all file
-  operations will be undone.
+  A library for creating commands can be done and
+  undone. Multiple commands can be grouped together
+  in a transaction making sure all commands succeed
+  or gets rolled back. This gem includes a few
+  commands for file operations but it makes it easy
+  to create custom commands and use them for more
+  than just file operations.
 email:
 - sammy.henningsson@gmail.com
 executables: []

metadata.gz.sig

@@ -1 +1 @@
-p�7#�<�!y�|̭�]��J���W��YV�y2�U�:b����q�TE
�;����8����˱۩ߵ�-�.dǛ�1�R䚠ď��Xp��s׹�J�+�� ���Nr���L�h
a��ڕq!��k���E�Mj;�i"�hI����0'i~��p��/�፜�?���M��q���`�|� ��1��
!�Q����X���c���b�
+5���0���t�.a1R5!�	y�4���ǧ�J ��u���ҷ��y31�#��
Pݒ��T���A��ŮsjO�\-�T���1��C�9��C���w�$�Yu��������WɁb'A�b�Y�n�$Q���ƈc%��ӶE�SH*6q�}�]���~gR�����{Z ���O����pWS]�~�CL��5�kS�
�O�~W�K{��jJ&h#����+�����?Y����SX�4I�8: