run_tasks 3.3.0 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db5998bcac4e11397fd0abb44484d48dc78ce538cd31a5768ddadf4f23a3a6ae
-  data.tar.gz: 8fc911ccdf1f057f3fb8c310185fdd3021eb293710b05b5cc0ce4bf16bd98c6c
+  metadata.gz: 89b89a1b7418844bef966d37027b641a162cbcd4023a2e932a1848ccf3df69bc
+  data.tar.gz: d691b13bf7a3eab7ebc5bbbb9f5155c88686696667c8a305aa4ca9ce6cbd2c79
 SHA512:
-  metadata.gz: 5387ed714265c8705665e5012d1186fc148c87e85d5a6441e66edabc02515eb58c62c03ba71d4451b647d2a5c02f0fbc7ac46a1d8c414734eb2803eb39222559
-  data.tar.gz: 42ace3eb70928ae2d509cbfa8b26f3696ba55f6cf2a797280957c98e0b7704cafefce72d2e375cc570360b896cc9d1905947d0bd8e8ec8892f7f5297e4067d66
+  metadata.gz: 780a926350e17a09469794beb7e0fb8959df42ee893dd209436f1b85aefe2aca749a235060dc16764da502f0007b415421fadfa2294c8e66cc855b7eaf1f2a4d
+  data.tar.gz: 1ee1f1e74ae13f7962184f1e7134621fefb298068c89121af734bc7f74788b243c20f2554732491366635aea67e73d573f6f2c8ce96f572964d6d682a6aa1868

data/README.md

@@ -0,0 +1,484 @@
+# Run
+
+Manage your Ruby projects with a straightforward syntax.
+
+## Compatibility
+
+Run is known to work with Ruby >=2.4.
+
+## Installation
+
+```sh
+gem install "run_tasks"
+```
+
+To enable ZSH completions:
+
+```sh
+run install_completions
+```
+
+## Running Run
+
+```sh
+run your_task
+```
+
+If you want to display the available tasks:
+
+```sh
+run help
+```
+
+> The help provides Run's version, so `run version` will display the same screen.
+
+> Note that the command `run` displays the help screen by default when no task is specified.
+
+## Runfile version
+
+The first line of a Runfile declares the major version of Run it is written for:
+
+```rb
+version 4
+```
+
+When a Runfile declares another major version, Run hands over to the matching version if it is installed, so projects written for Run 3 and Run 4 can live side by side. A Runfile without this line is a version 2 one.
+
+## Writing tasks
+
+```rb
+# Displays hello.
+task :hello do
+  puts "hello!"
+end
+```
+
+The comment is used by the Run to display the help. It must be placed directly above the task and can be multiline.
+
+> Note that help verbatims support Markdown syntax.
+
+`task` also support aliases, so you can call a task with different names:
+
+```rb
+task [:console, :c] do
+  run "bundle exec rails c"
+end
+```
+
+Running `run c` or `run console` will then start the Rails console.
+
+## Running shell commands
+
+```rb
+# Accessing a non-existent file.
+task :boom do
+  run "stat foo"
+  run "echo 'hello!'"
+end
+```
+
+It outputs:
+
+```sh
+$ run boom
+
+> stat foo
+
+stat: cannot stat 'foo': No such file or directory
+```
+
+> As you can see, `run` captures errors and stops when something bad happens.
+
+## Calling other tasks
+
+You can run tasks arbitrarily from any other task by passing a symbol:
+
+```rb
+task :eslint do
+  run "npx eslint"
+end
+
+task :flow do
+  run "npx flow"
+end
+
+task :lint_js do
+  run :eslint
+  run :flow
+end
+```
+
+By running `run lint_js` you will call `eslint` and `flow` tasks.
+
+## Passing arguments
+
+You can pass arguments to tasks from the CLI:
+
+```rb
+task :hello do |name, age|
+  puts "Hello #{name}, you are #{age}."
+end
+```
+
+```sh
+$ run hello 'John Doe' 30
+Hello John Doe, you are 30.
+```
+
+But also from the Runfile itself:
+
+```rb
+task :test do
+  run :hello, "John Doe", 30
+end
+```
+
+Every argument passed from the CLI is auto-converted, as a whole:
+
+| Argument                                                  | Result    |
+|-----------------------------------------------------------|-----------|
+| an integer: `42`, `-3`, `0`                               | `Integer` |
+| a decimal: `1.5`, `0.5`, `-0.5`                           | `Float`   |
+| `true` / `false`                                          | boolean   |
+| anything else, including superfluous zeros: `007`, `00.5` | `String`  |
+
+> Arguments never become symbols: if your task needs one, call `.to_sym`.
+
+### Named parameters
+
+Tasks also support named parameters, from the Runfile:
+
+```rb
+task :hello do |name:, age:|
+  puts "Hello #{name}, you are #{age}."
+end
+
+task :test do
+  run :hello, name: "John Doe", age: 30
+end
+```
+
+And from the CLI, with `name=value`:
+
+```sh
+$ run hello name='John Doe' age=30
+Hello John Doe, you are 30.
+```
+
+The value is auto-converted like any other argument. Separate values with commas to pass an array, each element being auto-converted:
+
+| Command                                | Received by the task                |
+|----------------------------------------|-------------------------------------|
+| `run review reviewer=clement`          | `reviewer: "clement"`               |
+| `run review reviewer=clement,morisset` | `reviewer: ["clement", "morisset"]` |
+| `run build retries=3`                  | `retries: 3`                        |
+| `run build ids=1,2,x`                  | `ids: [1, 2, "x"]`                  |
+| `run build dry=true`                   | `dry: true`                         |
+| `run build tag=`                       | `tag: ""`                           |
+
+> A single value gives a scalar, not an array: if your task expects a list, use `Array(value)`. Commas cannot be escaped.
+
+### Named booleans
+
+We also support named booleans. For example, imagine you want to run your server in tunnel mode:
+
+```rb
+task :server do |tunnel: false|
+  run "my_server #{tunnel ? "--tunnel" : ""}"
+end
+```
+
+When you call...
+
+```sh
+run server +tunnel
+```
+
+...the parameter `tunnel: true` will be passed to your task. The same if you pass `-tunnel`, it will pass `false`.
+
+### Additional notes
+
+- Hyphens in names are replaced by underscores: `+dry-run` and `dry-run=1` give `dry_run:`.
+- A name cannot be given twice (`a=1 a=2`, `+a -a`, `+a a=2`).
+- A task receiving named parameters or booleans must declare keywords (`reviewer:`, `**options`…). A task declaring keywords and receiving an unknown one fails too, as with any Ruby block.
+
+## Quiet mode
+
+If you want to run a task (or a command) without it to being able to write on STDOUT/STDERR, pass the quiet flag to true :
+
+```rb
+task :echo do
+  run "echo 'test'", quiet: true
+end
+```
+
+It's useful, for example, when you want to delete a file at the beginning of a task without it to being verbose when the file does not exist.
+
+## Colorization & styles
+
+It is often needed to colorize/stylize the messages sent to the user with `puts`. For this matter, Run is natively shipped with basic styles.
+
+For example:
+
+```rb
+puts "Please wait...".yellow.bold
+```
+
+The available styles are :
+
+- bold
+- dim
+- italic
+- underline
+- inverse
+- strikethrough
+
+And the available colors are :
+
+- black
+- red
+- green
+- yellow
+- blue
+- magenta
+- cyan
+- white
+- bright_black
+- bright_red
+- bright_green
+- bright_yellow
+- bright_blue
+- bright_magenta
+- bright_cyan
+- bright_white
+
+## Helpers
+
+Run comes with a few helpers to help writing tasks quicker.
+
+### are_you_sure
+
+When called, it asks a question to the user which has the choice to enter `y`, `yes`, `n` or `no` (the default answer). When `no` is selected, the task will exit with a `9` code.
+
+```rb
+task :dangerous_task do
+  are_you_sure "This task will delete your hard drive. Are you sure about that?"
+  # Some dangerous actions.
+end
+```
+
+### bind
+
+`bind` lets you group several tasks/processes so when one stops all the other will stop as well.
+
+```rb
+task :dev do
+  bind :rails, :vite
+end
+
+task :rails do
+  run "bundle exec unicorn -c config/unicorn.rb -p 3000"
+end
+
+task :vite do
+  run "bin/vite dev"
+end
+```
+
+### catch_interruption
+
+Alternatively, if you have a command that stays open until you hit `CTRL+C` (like a Docker container) and you need to catch the binding, you probably want to use `catch_interruption` instead so it lets the command handle the interruption gracefully and executes some actions afterwards.
+
+```rb
+# Run server in development mode.
+task :server do
+  catch_interruption("docker run -d -p 8080:80 web_server") do
+    # Run some clean up actions here after the command has been interrupted.
+  end
+end
+```
+
+### exists
+
+Handy helper to verify if a program exists.
+
+```rb
+task :man do
+  command = exists("bat") ? "bat" : "cat"
+  run "#{command} #{__dir__}/README.md"
+end
+```
+
+### expand
+
+This one takes a glob string and process it to return a list of files.
+
+```rb
+task :scan do |glob|
+  expand(glob).each do |file_path|
+    # Do something.
+  end
+end
+```
+
+### menu
+
+It displays an advanced menu where you can choose an element that will be returned by the function.
+
+```rb
+# Array syntax
+task :deploy_aws do
+  region = menu "Location?", ["us‑east‑2", "us-west-1", "eu-west-1"]
+end
+```
+
+```rb
+# Hash syntax
+task :deploy_aws do
+  region = menu "Location?", {
+    "US East (Ohio)" => "us‑east‑2",
+    "US West (N. California)" => "us-west-1",
+    "Europe (Ireland)" => "eu-west-1",
+  }
+end
+```
+
+### pause
+
+You can pause a task if needed, waiting for the user to press any key.
+
+```rb
+task :deploy do
+  puts "Press enter to continue.".yellow
+  pause
+  run :deploy_production
+end
+```
+
+### question
+
+Displays a question and returns the answer.
+
+```rb
+task :survey do
+  comment = question "Did your meal was good?"
+end
+```
+
+You can also pass a regex to validation the entered value:
+
+```rb
+task :age do
+  age = question "What is your age?", /^\d+$/
+end
+```
+
+A default value can be set, it will be returned if the user enters nothing:
+
+```rb
+task :age do
+  age = question "What is your age?", /^\d+$/, default: "30"
+end
+```
+
+### yesno
+
+Asks a yes/no question and returns a boolean. The user can answer `y`, `yes`, `n` or `no`.
+
+```rb
+task :deploy do
+  run :migrate if yesno "Run migrations?"
+end
+```
+
+Without a default value, an answer is required. With one, it is returned if the user enters nothing:
+
+```rb
+task :deploy do
+  run :migrate if yesno "Run migrations?", default: true
+end
+```
+
+### wait_for_interruption
+
+If you need to wait for the user to interrupt a task of, for example, several running servers, you can use the `wait_for_interruption` helper.
+
+```rb
+# Run server in development mode.
+task :server do
+  Thread.new do
+    # Run first server.
+  end
+  Thread.new do
+    # Run second server.
+  end
+  # Wait for CTRL+C.
+  wait_for_interruption do
+    # Some actions to handle before terminating the task, like killing the servers.
+  end
+end
+```
+
+## Base tasks
+
+Run also comes with some generic tasks for recurring tasks.
+
+### publish
+
+You can publish your library with:
+
+```sh
+run publish
+```
+
+> At the moment, this is only compatible with gems.
+
+### rspec
+
+You can call directly `run rspec` or abstract the task like this:
+
+```rb
+# Run the tests.
+task [:specs, :s, :tests, :t] do |path = "spec/src"|
+  run :rspec, path
+end
+```
+
+> The `rspec` task will look into `spec/src` by default, so the above task is just explanatory is you want overload default behaviour.
+
+## Advanced usage
+
+### Specifying Runfile path
+
+If you want to load Run from another directory, you have two choices :
+
+- change the working directory in your script,
+- or pass the Runfile path with `RUNFILE=/path/to/Runfile.rb run my_task`
+
+### Exit codes
+
+Run has specific exit codes so you can handle it better in some environments, like in CI or in deployments:
+
+- 1: Run has exited abnormally.
+- 2: The required task does not exist.
+- 3: Unhandled Interrupt error coming from a failed shell command.
+- 4: An error has been raised in the Runfile.
+- 5: The Runfile contains a syntax error.
+- 6: Some parameters are invalid.
+- 7: Runfile not found.
+- 8: Unable to load a remote file.
+- 9: The user has answered "No" to an "Are you sure?" question.
+- 10: The required task already exists.
+- 11: The required command is not running.
+- 12: The required task does not exist.
+
+## Development
+
+For test purposes, it's often needed to install Run from a development branch. For this, you'll need to follow these steps:
+
+```sh
+gem install specific_install
+gem specific_install http://github.com/pyrsmk/run.git <branch>
+```
+
+Do not forget to uninstall other `run_tasks` packages if needed, to avoid conflicts. And if you're under Rbenv, you'll probably need to do `rbenv rehash` too.

data/src/bootstrap.rb

@@ -7,7 +7,6 @@ require "readline"
 require "rubygems"
 require "securerandom"
 require "rb_monkey"
-require "rb_gemspec"
 require "rb_markdown"
 
 # Require all files.
@@ -77,11 +76,6 @@ task :publish do
   `rm #{gemspec.name}-#{gemspec.version}.gem`
 end
 
-# Display the manual.
-task :man do
-  puts Markdown::Engine.new(File.read("#{__dir__}/../CHEATSHEET.md")).to_ansi
-end
-
 # Expose helpers.
 Dir.glob(File.join(__dir__, "run", "helper", "*.rb")) do |path|
   filename = File.basename(path, ".rb")
@@ -117,6 +111,9 @@ rescue Interrupt
 rescue SyntaxError => error
   format_error error
   exit 5
+rescue Run::Error::DuplicateParameter, Run::Error::UnexpectedNamedParameters => error
+  puts error.message.red
+  exit 6
 rescue ArgumentError => error
   format_error error
   exit 6

data/src/run/core.rb

@@ -4,6 +4,10 @@ module Run
   module Core
     RUNFILE_FILENAME = ENV.fetch('RUNFILE', 'Runfile.rb')
     RESERVED_TASK_NAMES = ["help", "version"]
+    NAME_PATTERN = /[a-zA-Z_]\w*(?:-\w+)*/
+    OPTION_PATTERN = /\A([+-])(#{NAME_PATTERN})\z/
+    NAMED_PARAMETER_PATTERN = /\A(#{NAME_PATTERN})=(.*)\z/m
+    RUNFILE_VERSION_PATTERN = /^\s*version\s*\(?\s*(\d+)/
     @@tasks = []
     @@runfile_version = nil
 
@@ -15,6 +19,7 @@ module Run
 
     # @return [void]
     def self.run_run
+      delegate_to_runfile_version! if File.file?(RUNFILE_FILENAME)
       if ARGV.size == 1 && ARGV[0] == "--completions"
         require File.expand_path(RUNFILE_FILENAME) if File.exist?(RUNFILE_FILENAME)
         puts completions.join("\n")
@@ -22,7 +27,7 @@ module Run
       end
       raise Run::Error::NonExistingRunfile.new if !File.file?(RUNFILE_FILENAME)
       if ARGV.size == 1 && ARGV[0] == "version"
-        puts version
+        puts VERSION
       elsif ARGV.size == 0 || (ARGV.size == 1 && ARGV[0] == "help")
         require File.expand_path(RUNFILE_FILENAME)
         check_runfile_version!
@@ -69,18 +74,36 @@ module Run
       }
     end
 
+    # @param contents [String]
+    # @return [Integer]
+    def self.declared_runfile_version(contents)
+      contents[RUNFILE_VERSION_PATTERN, 1]&.to_i || 2
+    end
+
+    # @param major [Integer]
+    # @return [Gem::Version, nil]
+    def self.installed_version_for(major)
+      Gem::Specification.find_all_by_name("run_tasks", "~> #{major}.0").map(&:version).max
+    end
+
     private
 
     # @return [void]
-    def self.check_runfile_version!
-      if (@@runfile_version || 2) != version.to_s.split(".").first.to_i
-        raise Run::Error::RunfileVersionMismatch.new
-      end
+    def self.delegate_to_runfile_version!
+      major = declared_runfile_version(File.read(RUNFILE_FILENAME))
+      return if major == VERSION.split(".").first.to_i
+
+      version = installed_version_for(major)
+      raise Run::Error::RunfileVersionMismatch.new(major) if !version
+
+      exec Gem.ruby, File.join(Gem.bindir, "run"), "_#{version}_", *ARGV
     end
 
     # @return [void]
-    def self.display_version
-      puts Gemspec::Metadata.new("run_tasks").read.version
+    def self.check_runfile_version!
+      if (@@runfile_version || 2) != VERSION.split(".").first.to_i
+        raise Run::Error::RunfileVersionMismatch.new
+      end
     end
 
     # @return [void]
@@ -91,19 +114,13 @@ module Run
     # @return [void]
     def self.display_help
       puts
-      puts " Run v#{version}".bright_blue
+      puts " Run v#{VERSION}".bright_blue
       contents = Run::Core::Help.run(File.read(File.join(Dir.pwd, RUNFILE_FILENAME)))
       if contents.strip.size > 0
-        puts
-        puts " Project tasks:".magenta
         puts
         puts contents
       end
       puts
-      puts " Global tasks:".magenta
-      puts
-      puts Run::Core::Help.run(File.read(File.join(__dir__, "..", "bootstrap.rb")))
-      puts
     end
 
     # @return [void]
@@ -111,32 +128,60 @@ module Run
       name = ARGV[0].gsub('-', '_').to_sym # Auto-replace hyphens to underscores.
       raise Run::Error::UnknownTask.new(name) if !task_exist?(name)
 
+      args, options = parse_arguments(ARGV.drop(1))
+      run name, *args, **options
+    end
+
+    # @param words [Array<String>]
+    # @return [Array(Array, Hash)]
+    def self.parse_arguments(words)
       args = []
       options = {}
 
-      ARGV.slice(1, ARGV.size - 1).each do |arg|
-        if (match = arg.match(/^\+([a-zA-Z_]\w*)$/))
-          options[match[1].to_sym] = true
-          next
-        elsif (match = arg.match(/^-([a-zA-Z_]\w*)$/))
-          options[match[1].to_sym] = false
-          next
-        elsif arg.match?(/^-?(?:0|[1-9]\d*)$/)
-          args << Integer(arg, 10)
-          next
-        elsif arg.match?(/^-?\d+\.\d+$/)
-          args << Float(arg)
-          next
+      words.each do |word|
+        if (match = word.match(OPTION_PATTERN))
+          sign, name = match.captures
+          add_option(options, name, sign == "+")
+        elsif (match = word.match(NAMED_PARAMETER_PATTERN))
+          name, value = match.captures
+          add_option(options, name, convert_named_value(value))
+        else
+          args << convert_argument(word)
         end
-        raise
-      rescue
-        next args << true if arg == "true"
-        next args << false if arg == "false"
-        next args << arg.to_sym if arg.match?(/^\w+$/)
-        args << arg
       end
 
-      run name, *args, **options
+      [args, options]
+    end
+
+    # @param value [String]
+    # @return [Integer, Float, Boolean, String]
+    def self.convert_argument(value)
+      case value
+      when /\A-?(?:0|[1-9]\d*)\z/ then Integer(value, 10)
+      when /\A-?(?:0|[1-9]\d*)\.\d+\z/ then Float(value)
+      when "true" then true
+      when "false" then false
+      else value
+      end
+    end
+
+    # @param value [String]
+    # @return [Object, Array]
+    def self.convert_named_value(value)
+      return convert_argument(value) if !value.include?(",")
+
+      value.split(",", -1).map { |item| convert_argument(item) }
+    end
+
+    # @param options [Hash]
+    # @param name [String]
+    # @param value [Object]
+    # @return [void]
+    def self.add_option(options, name, value)
+      key = name.tr("-", "_").to_sym
+      raise Run::Error::DuplicateParameter.new(key) if options.key?(key)
+
+      options[key] = value
     end
 
     # @param name [Symbol]
@@ -152,6 +197,9 @@ module Run
     def self.run_block_task(name, *args, **options)
       task = @@tasks.find{ |item| item[:names].include? name }
       raise Error::NonExistingTask.new(name) if task.nil?
+      if options.any? && !task[:task].accepts_keywords?
+        raise Error::UnexpectedNamedParameters.new(name, options.keys)
+      end
 
       task[:task].run(*args, **options)
     end
@@ -162,11 +210,6 @@ module Run
       Run::Task::SystemTask.new(command).run
     end
 
-    # @return [String]
-    def self.version
-      Gemspec::Metadata.new("run_tasks").read.version
-    end
-
     # @return [Boolean]
     def self.quiet?
       !!Thread.current[:quiet]

data/src/run/error/duplicate_parameter.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Run
+  module Error
+    class DuplicateParameter < StandardError
+      # @param name [Symbol]
+      def initialize(name)
+        super "Parameter '#{name}' is given more than once"
+      end
+    end
+  end
+end

data/src/run/error/runfile_version_mismatch.rb

@@ -3,8 +3,13 @@
 module Run
   module Error
     class RunfileVersionMismatch < StandardError
-      def initialize
-        super "Runfile version mismatches Run version"
+      # @param major [Integer, nil]
+      def initialize(major = nil)
+        if major
+          super "Runfile declares version #{major}, which needs Run #{major}: gem install run_tasks -v '~> #{major}.0'"
+        else
+          super "Runfile version mismatches Run version"
+        end
       end
     end
   end

data/src/run/error/unexpected_named_parameters.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Run
+  module Error
+    class UnexpectedNamedParameters < StandardError
+      # @param task_name [Symbol]
+      # @param names [Array<Symbol>]
+      def initialize(task_name, names)
+        super "Task '#{task_name}' does not accept named parameters: #{names.join(", ")}"
+      end
+    end
+  end
+end

data/src/run/task/block_task.rb

@@ -8,15 +8,16 @@ module Run
         @block = block
       end
 
+      # @return [Boolean]
+      def accepts_keywords?
+        @block.parameters.any?{ |type, _| [:key, :keyreq, :keyrest].include?(type) }
+      end
+
       # @param arguments [Array]
       # @param options [Hash]
       # @return [void]
       def run(*arguments, **options)
-        if options.size == 0
-          @block.call *arguments
-        else
-          @block.call *arguments, **options
-        end
+        @block.call(*arguments, **options)
       end
     end
   end

data/src/run/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Run
+  VERSION = "4.0.1"
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: run_tasks
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 4.0.1
 platform: ruby
 authors:
 - Aurélien Delogu
@@ -37,20 +37,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.1.0
-- !ruby/object:Gem::Dependency
-  name: rb_gemspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.2.1
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.2.1
 - !ruby/object:Gem::Dependency
   name: rb_markdown
   requirement: !ruby/object:Gem::Requirement
@@ -71,18 +57,20 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- CHEATSHEET.md
+- README.md
 - bin/run
 - completions/_run
 - src/bootstrap.rb
 - src/run/core.rb
 - src/run/core/help.rb
 - src/run/error/aborted.rb
+- src/run/error/duplicate_parameter.rb
 - src/run/error/existing_task.rb
 - src/run/error/non_existing_runfile.rb
 - src/run/error/non_existing_task.rb
 - src/run/error/reserved_task_name.rb
 - src/run/error/runfile_version_mismatch.rb
+- src/run/error/unexpected_named_parameters.rb
 - src/run/error/unknown_task.rb
 - src/run/helper/are_you_sure_helper.rb
 - src/run/helper/bind_helper.rb
@@ -96,6 +84,7 @@ files:
 - src/run/helper/yesno_helper.rb
 - src/run/task/block_task.rb
 - src/run/task/system_task.rb
+- src/run/version.rb
 homepage: https://github.com/pyrsmk/run
 licenses:
 - MIT

data/CHEATSHEET.md

@@ -1,238 +0,0 @@
-# Defining a task
-
-```rb
-task :eslint do
-end
-```
-
-# Defining a task with aliases
-
-```rb
-task [:console, :c] do
-end
-```
-
-# Defining a task with parameters
-
-```rb
-task :hello do |name, age|
-  puts "Hello #{name}, you are #{age}."
-end
-```
-
-# Running commands
-
-```rb
-task :clear_all do
-  run "rm -rf /*"
-end
-```
-
-# Running subtasks
-
-```rb
-task :linting do
-  run :eslint
-  run :rubocop
-end
-```
-
-# Running a task/command in quiet mode
-
-```rb
-task :clear_cache do
-  run "rm -rf cache/*", quiet: true
-end
-```
-
-# Using named booleans
-
-```sh
-run server +tunnel
-```
-
-```rb
-task :server do |tunnel: false|
-  run "http_server #{tunnel ? "--tunnel" : ""}"
-end
-```
-
-# Helpers
-
-## are_you_sure
-
-```rb
-task :dangerous_task do
-  are_you_sure "This task will delete your hard drive. Are you sure about that?"
-  # Some dangerous actions.
-end
-```
-
-## bind
-
-```rb
-task :rails do
-  run "bundle exec unicorn -c config/unicorn.rb -p 3000"
-end
-
-task :vite do
-  run "bin/vite dev"
-end
-
-task :dev do
-  # Bind `rails` and `vite` tasks together, if one closes, the other terminates too.
-  bind :rails, :vite
-end
-```
-
-```rb
-task :dev do
-  # Plug STDIN to the `rails` task.
-  bind :rails, :vite, stdin: :rails
-end
-```
-
-## catch_interruption
-
-```rb
-task :server do
-  catch_interruption("docker run -d -p 8080:80 web_server") do
-    run :clear_cache
-  end
-end
-```
-
-## exists
-
-```rb
-task :man do
-  command = exists("bat") ? "bat" : "cat"
-  run "#{command} #{__dir__}/README.md"
-end
-```
-
-## expand
-
-```rb
-task :scan do |glob|
-  expand(glob).each do |file_path|
-    puts file_path
-  end
-end
-```
-
-## menu
-
-```rb
-task :deploy_aws do
-  region = menu "Location?", ["us‑east‑2", "us-west-1", "eu-west-1"]
-end
-```
-
-```rb
-task :deploy_aws do
-  region = menu "Location?", {
-    "US East (Ohio)" => "us‑east‑2",
-    "US West (N. California)" => "us-west-1",
-    "Europe (Ireland)" => "eu-west-1",
-  }
-end
-```
-
-## pause
-
-```rb
-task :deploy do
-  puts "Press enter to continue.".yellow
-  pause
-  run :deploy_production
-end
-```
-
-## question
-
-```rb
-task :survey do
-  comment = question "Did your meal was good?"
-end
-```
-
-```rb
-task :age do
-  age = question "What is your age?", /^\d+$/
-end
-```
-
-```rb
-task :age do
-  age = question "What is your age?", /^\d+$/, default: "30"
-end
-```
-
-## yesno
-
-```rb
-task :deploy do
-  run :migrate if yesno "Run migrations?"
-end
-```
-
-```rb
-task :deploy do
-  run :migrate if yesno "Run migrations?", default: true
-end
-```
-
-## wait_for_interruption
-
-```rb
-task :server do
-  Thread.new do
-    run :rails
-  end
-  Thread.new do
-    run :vite
-  end
-  wait_for_interruption do
-    run :kill_rails
-    run :kill_vite
-  end
-end
-```
-
-# Colorization
-
-```rb
-puts "hello".bold
-puts "hello".dim
-puts "hello".italic
-puts "hello".underline
-puts "hello".inverse
-puts "hello".strikethrough
-puts "hello".black
-puts "hello".red
-puts "hello".green
-puts "hello".yellow
-puts "hello".blue
-puts "hello".magenta
-puts "hello".cyan
-puts "hello".white
-puts "hello".bright_black
-puts "hello".bright_red
-puts "hello".bright_green
-puts "hello".bright_yellow
-puts "hello".bright_blue
-puts "hello".bright_magenta
-puts "hello".bright_cyan
-puts "hello".bright_white
-```
-
-```rb
-puts "hello".green.bold.italic
-```
-
-# Advanced usage
-
-```sh
-RUNFILE=/path/to/Runfile.rb run my_task
-```