Add simple examples of gem usage

README.md

@@ -52,7 +52,7 @@ parent function.
 ```ruby
 def create_build_and_test
   UberTask.run(
-    name: "Build and Test"
+    "Build and Test"
     default_retry_count: 1,
     default_retry_wait: 5.mins,
     retry_count: 1
@@ -73,7 +73,7 @@ On calling the `.run` method of UberTask inside this function, we add this funct
 
 #### parameters
 
-1. name:
+1. name -
    Default value is nil. Set the value of this parameter which
    signifies what the function does.
 
@@ -107,7 +107,7 @@ We need to call this inside the `UberTask#run` method. This event is triggered w
 ```ruby
 def install_ruby
   UberTask.run(
-    name: "Install Ruby"
+    "Install Ruby"
     retry_count: 2
   ) do
 
@@ -191,6 +191,13 @@ TODO: need to come up with an appropriate example.
 1. block:
    Pass a Ruby block that contains the code to be executed.
 
+## Examples
+
+You can find examples of gem usage at `examples/` folder:
+```
+ruby examples/download_and_move_file.rb
+```
+
 ## License
 
 The gem is available as open source under the terms of the

examples/download_and_move_file.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'uber_task'
+require 'colorize'
+require 'tmpdir'
+
+require_relative 'download_file'
+require_relative 'move_file'
+require_relative 'failing_task'
+
+EXISTENT_FILE_URI = 'https://github.com/shakacode/uber_task/raw/main/README.md'
+NON_EXESTENT_FILE_URI = 'https://github.com/shakacode/uber_task/raw/main/NON_EXISTENT.md'
+NON_VITAL_FILE_URI = 'https://github.com/shakacode/uber_task/raw/main/NON_VITAL.md'
+
+module Examples
+  class DownloadAndMoveFile
+    def self.run(uri:, download_path:, move_path:)
+      UberTask.run('Download and move file') do
+        UberTask.on_success do
+          UberTask.logger.info(
+            'Top-level task was completed successfully!'.green,
+          )
+        end
+
+        UberTask.on_subtask_error do |_task, event, err|
+          case err
+          # Network errors occuring in subtasks are handled here in top-level
+          when OpenURI::HTTPError
+            UberTask.retry(reason: err, wait: 5)
+          # Subtasks can be skipped
+          when Examples::FailingTask::Error
+            UberTask.logger.info(
+              'Encountered expected error, skipping...'.yellow,
+            )
+
+            UberTask.skip
+          else
+            UberTask.logger.error(
+              "Encountered unexpected error - #{err.message}".red,
+            )
+            event.handled
+          end
+        end
+
+        Examples::DownloadFile.run(
+          uri: NON_VITAL_FILE_URI,
+          to: download_path,
+          retry_count: 1,
+          vital: false, # execution won't stop when this task fails
+        )
+
+        Examples::FailingTask.run
+
+        Examples::DownloadFile.run(
+          uri: uri,
+          to: download_path,
+          retry_count: 3,
+          vital: true, # execution will stop if this task fails
+        )
+
+        Examples::MoveFile.run(from: download_path, to: move_path)
+      end
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  Dir.mktmpdir do |dir|
+    download_path = File.join(dir, 'download_path')
+    move_path = File.join(dir, 'move_path')
+
+    puts '--- Running successfull case ---'
+    Examples::DownloadAndMoveFile.run(
+      uri: EXISTENT_FILE_URI,
+      download_path: download_path,
+      move_path: move_path,
+    )
+
+    puts "\n--- Running case which fails to download file ---\n"
+    Examples::DownloadAndMoveFile.run(
+      uri: NON_EXESTENT_FILE_URI,
+      download_path: download_path,
+      move_path: move_path,
+    )
+  end
+end

examples/download_file.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'uber_task'
+require 'colorize'
+require 'open-uri'
+
+module Examples
+  class DownloadFile
+    def self.run(uri:, to:, **task_options)
+      UberTask.run(
+        'Download file from external source',
+        default_retry_wait: 5,
+        retry_count: 3,
+        **task_options,
+      ) do
+        UberTask.on_success do
+          UberTask.logger.info(
+            "Downloaded file #{uri} and saved it at #{to}".green,
+          )
+        end
+
+        UberTask.on_retry do
+          UberTask.logger.info(
+            "Retrying to download file from #{uri}...".yellow,
+          )
+        end
+
+        save_external_file!(uri: uri, to: to)
+      end
+    end
+
+    def self.save_external_file!(uri:, to:)
+      URI.parse(uri).open { |io| File.write(to, io.read) }
+    end
+    private_class_method :save_external_file!
+  end
+end

examples/failing_task.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'uber_task'
+
+module Examples
+  class FailingTask
+    Error = Class.new(StandardError)
+
+    def self.run(**task_options)
+      UberTask.run('Failing task', **task_options) do
+        raise Error, 'failed'
+      end
+    end
+  end
+end

examples/move_file.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'uber_task'
+require 'colorize'
+require 'fileutils'
+
+module Examples
+  class MoveFile
+    def self.run(from:, to:, **task_options)
+      UberTask.run(
+        'Move file',
+        default_retry_wait: 1,
+        retry_count: 3,
+        **task_options,
+      ) do
+        UberTask.on_success do
+          UberTask.logger.info "Moved file from #{from} to #{to}".green
+        end
+
+        UberTask.on_retry do
+          UberTask.logger.info(
+            "Retrying to move file from #{from} to #{to}...".yellow,
+          )
+        end
+
+        move_file!(from: from, to: to)
+      end
+    end
+
+    def self.move_file!(from:, to:)
+      FileUtils.mv(from, to)
+    end
+    private_class_method :move_file!
+  end
+end