Version 0.0.113 (#53)

* prepare to improve getting-started

* add TriggeredTask

* update docs

* update docs

docs/concepts/tasks/README.md

@@ -19,21 +19,20 @@ As every task are extended from `BaseTask`, you will see that most of them share
 
 
 ```
-                                            BaseTask
+                                           BaseTask
                                                │
                                                │
-  ┌──────┬───────────┬───────────┬─────────────┼────────────────┬───────────┬──────────┐
-  │      │           │           │             │                │           │          │
-  │      │           │           │             │                │           │          │
-  ▼      ▼           ▼           ▼             ▼                ▼           ▼          ▼
-Task  CmdTask  ResourceMaker  FlowTask  BaseRemoteCmdTask  HttpChecker PortChecker PathChecker
+  ┌──────┬───────────┬───────────┬─────────────┼─────────────────┬─────────────┬───────────┬──────────┐
+  │      │           │           │             │                 │             │           │          │
+  │      │           │           │             │                 │             │           │          │
+  ▼      ▼           ▼           ▼             ▼                 ▼             ▼           ▼          ▼
+Task  CmdTask  ResourceMaker  FlowTask  BaseRemoteCmdTask  TriggeredTask  HttpChecker PortChecker PathChecker
          │                                     │
          │                                     │
          ▼                               ┌─────┴──────┐
    DockerComposeTask                     │            │
                                          ▼            ▼
                                    RemoteCmdTask   RsyncTask
-
 ```
 
 Aside from the documentation, you can always dive down into [the source code](https://github.com/state-alchemists/zrb/tree/main/src/zrb/task) to see the detail implementation.

docs/tutorials/README.md

@@ -4,6 +4,7 @@
 
 - [Preparing Your Machine for Development](preparing-your-machine-for-development.md)
 - [Development to Deployment: Low Code](development-to-deployment-low-code.md)
+- [Integration With Other Tools](integration-with-other-tools.md)
 - [Running Task programmatically](running-task-programmatically.md)
 - [Running Task by Schedule](running-task-by-schedule.md)
 - [Getting Data from Other Tasks](getting-data-from-other-tasks.md)

docs/tutorials/integration-with-other-tools.md

@@ -0,0 +1,148 @@
+🔖 [Table of Contents](../README.md) / [Tutorials](README.md)
+
+# Integration with Other Tools
+
+CLI Tools can interact to each other in various ways. The most common way is redirecting standard input, output, and error.
+
+Every time you run a Zrb Task, Zrb will produce two types of output:
+- stdout and
+- stderr
+
+The Stderr usually contains some logs or error information, while the stout usually contains the output.
+
+# Stdout and Stderr
+
+Let's say you want to redirect Zrb's stderr to `stderr.txt` and Zrb's stdout to `stdout.txt`
+
+You can use any task's output for further processing. For example, redirect a task's output and error into files.
+
+```bash
+zrb base64 encode --text "non-credential-string" > stdout.txt 2> stderr.txt
+cat stdout.txt
+cat stderr.txt
+```
+
+You will see that `stdout.txt` contains just the output:
+
+```
+bm9uLWNyZWRlbnRpYWwtc3RyaW5n
+```
+
+While `stderr.txt` has everything else you expect to see on your screen:
+
+```
+Support zrb growth and development!
+☕ Donate at: https://stalchmst.com/donation
+🐙 Submit issues/PR at: https://github.com/state-alchemists/zrb
+🐤 Follow us at: https://twitter.com/zarubastalchmst
+🤖 ○ ◷ 2023-11-26 06:59:12.672 ❁  22713 → 1/1 🍎    zrb base64 encode • Completed in 0.05152606964111328 seconds
+To run again: zrb base64 encode --text "non-credential-string"
+```
+
+In most cases, you want to care more about the stdout.
+
+```bash
+zrb base64 encode --text "non-credential-string" > encoded-text.txt
+```
+
+# Using Zrb's Stdout as Other Tool's Input
+
+There are two ways to use Zrb's Stdout as Other Tool's Input.
+
+- Using Zrb's Stdout as Other Tool's Parameter
+- Using Zrb's Stderr as Other Tool's Input
+
+## Using Zrb's Stdout as Other Tool's Parameter
+
+The first one is by using it as a parameter. For example, `cowsay` takes one parameter and shows a bubbled text.
+
+```bash
+cowsay hello
+```
+
+This command will show a bubbled "hello" on your screen.
+
+You can use Zrb's output as `cowsay`'s parameter using `$(` and `)` like this:
+
+```bash
+cowsay $(zrb base64 encode --text "non-credential-string")
+```
+
+This command will show the bubbled output of `zrb base64 encode`.
+
+```
+Support zrb growth and development!
+☕ Donate at: https://stalchmst.com/donation
+🐙 Submit issues/PR at: https://github.com/state-alchemists/zrb
+🐤 Follow us at: https://twitter.com/zarubastalchmst
+🤖 ○ ◷ 2023-11-26 07:26:12.391 ❁  23643 → 1/1 🍋    zrb base64 encode • Completed in 0.051149845123291016 seconds
+To run again: zrb base64 encode --text "non-credential-string"
+ ______________________________
+< bm9uLWNyZWRlbnRpYWwtc3RyaW5n >
+ ------------------------------
+        \   ^__^
+         \  (oo)\_______
+            (__)\       )\/\
+                ||----w |
+                ||     ||
+```
+
+## Using Zrb's Stdout as Other Tool's Input
+
+Some other tools need to take information from user Stdin, for example, `lolcat`.
+
+In that case, you can use pipe (`|`) operator to redirect Zrb's output as `lolcat`'s input:
+
+```bash
+zrb base64 encode --text "non-credential-string" | lolcat
+```
+
+```
+Support zrb growth and development!
+☕ Donate at: https://stalchmst.com/donation
+🐙 Submit issues/PR at: https://github.com/state-alchemists/zrb
+🐤 Follow us at: https://twitter.com/zarubastalchmst
+🤖 ○ ◷ 2023-11-26 07:27:05.110 ❁  23687 → 1/1 🐭    zrb base64 encode • Completed in 0.05138230323791504 seconds
+To run again: zrb base64 encode --text "non-credential-string"
+bm9uLWNyZWRlbnRpYWwtc3RyaW5n
+```
+
+> __📝 NOTE:__ The output should be rainbow colored. You can install lolcat by following [it's documentation](https://github.com/busyloop/lolcat). If you are using Linux, and you don't like `snap`, you can try to use your OS's package manager (e.g., `sudo apt install lolcat`)
+
+# Using Other Tool's Output as Zrb's Task Parameter
+
+On the other hand, you can also use any CLI tool's output as Zrb's task parameter. This command will give you an interesting result:
+
+```bash
+zrb say --text "$(cowsay hi)" --width "80"
+```
+
+```
+🤖 ○ ◷ 2023-11-26 07:28:58.860 ❁  23732 → 1/3 🐮              zrb say •
+
+    ┌──────────────────────────────────────────────────────────────────────────────────┐
+    |  ____                                                                            |
+    | < hi >                                                                           |
+    |  ----                                                                            |
+    |         \   ^__^                                                                 |
+    |          \  (oo)\_______                                                         |
+    |             (__)\       )\/\                                                     |
+    |                 ||----w |                                                        |
+    |                 ||     ||                                                        |
+    └──────────────────────────────────────────────────────────────────────────────────┘
+          \
+           \
+      o    ___    o
+      | ┌-------┐ |
+      |(| o   o |)|
+        | └---┘ |
+        └-------┘
+
+Support zrb growth and development!
+☕ Donate at: https://stalchmst.com/donation
+🐙 Submit issues/PR at: https://github.com/state-alchemists/zrb
+🐤 Follow us at: https://twitter.com/zarubastalchmst
+🤖 ○ ◷ 2023-11-26 07:28:58.911 ❁  23732 → 1/3 🐮              zrb say • Completed in 0.05133986473083496 seconds
+```
+
+🔖 [Table of Contents](../README.md) / [Tutorials](README.md)

pyproject.toml

@@ -28,6 +28,7 @@ dependencies = [
   "ruamel.yaml ~= 0.17.32",
   "setuptools ~= 68.0.0",
   "autopep8 ~= 2.0.2",
+  "croniter ~= 2.0.1",
 ]
 
 [project.optional-dependencies]

requirements.txt

@@ -2,6 +2,7 @@
 flit==3.9.0         # better builder
 twine==4.0.2        # pip package uploader
 keyring==24.2.0     # authenticator (used by twine)
+tomli~=2.0.1
 
 # Zrb dependencies (should be copied to `pyproject.toml`)
 click~=8.1.4        # CLI framework
@@ -15,7 +16,7 @@ jsons~=1.6.3
 ruamel.yaml~=0.17.32
 setuptools~=68.0.0
 autopep8~=2.0.2     # Autoformatter
-tomli~=2.0.1
+croniter~=2.0.1
 
 # Zrb dev dependencies (should be copied to `pyproject.toml`)
 flake8~=6.0.0       # Linter

src/zrb/__init__.py

@@ -14,6 +14,7 @@
     ResourceMaker, Replacement, ReplacementMutator
 )
 from zrb.task.flow_task import FlowTask
+from zrb.task.triggered_task import TriggeredTask
 from zrb.task_input.any_input import AnyInput
 from zrb.task_input.task_input import Input
 from zrb.task_input.bool_input import BoolInput

src/zrb/builtin/__init__.py

@@ -11,6 +11,9 @@
 from zrb.builtin import devtool
 from zrb.builtin import generator
 from zrb.builtin import process
+from zrb.builtin import say
+from zrb.builtin import watch
+from zrb.builtin import schedule
 
 assert base64
 assert env
@@ -25,3 +28,6 @@
 assert devtool
 assert generator
 assert process
+assert say
+assert watch
+assert schedule

src/zrb/builtin/explain.py

@@ -2,7 +2,6 @@
 from zrb.helper.python_task import show_lines
 from zrb.builtin.group import explain_group
 from zrb.task.decorator import python_task
-from zrb.task.task import Task
 from zrb.runner import runner
 
 

src/zrb/builtin/say.py

@@ -0,0 +1,138 @@
+from zrb.helper.typing import Any, List
+from zrb.helper.python_task import show_lines
+from zrb.task.decorator import python_task
+from zrb.task_input.str_input import StrInput
+from zrb.task_input.int_input import IntInput
+from zrb.runner import runner
+import datetime
+import random
+
+_MIN_WIDTH = 50
+_MOTIVATIONAL_QUOTES = [
+    [
+        'The best time to plant a tree was 20 years ago.',
+        'The second best time is now.',
+        '~ Chinese Proverb'
+    ],
+    [
+        'The only way to do great work is to love what you do.',
+        '~ Steve Jobs'
+    ],
+    [
+        'Believe you can and you\'re halfway there.',
+        '~ Theodore Roosevelt'
+    ],
+    [
+        'It does not matter how slowly you go as long as you do not stop.',
+        '~ Confucius'
+    ],
+    [
+        'Everything you\'ve ever wanted is on the other side of fear.',
+        '~ George Addair'
+    ],
+    [
+        'Success is not final, failure is not fatal:',
+        'It is the courage to continue that counts.',
+        '~ Winston Churchill'
+    ],
+    [
+        'Hardships often prepare ordinary people',
+        'for an extraordinary destiny.',
+        '~ C.S. Lewis'
+    ],
+    [
+        'Your time is limited, don\'t waste it living someone else\'s life.',
+        '~ Steve Jobs'
+    ],
+    [
+        'Don’t watch the clock; do what it does. Keep going.',
+        '~ Sam Levenson'
+    ],
+    [
+        'You are never too old to set another goal or to dream a new dream.',
+        '~ C.S. Lewis'
+    ],
+    [
+        'The only limit to our realization of tomorrow',
+        'will be our doubts of today.',
+        '~ Franklin D. Roosevelt'
+    ],
+    [
+        'Believe in yourself.',
+        'You are braver than you think, more talented than you know,'
+        'and capable of more than you imagine.',
+        '~ Roy T. Bennett'
+    ],
+    [
+        'I can\'t change the direction of the wind,',
+        'but I can adjust my sails to always reach my destination.',
+        '~ Jimmy Dean'
+    ],
+    [
+        'You are enough just as you are.',
+        '~ Meghan Markle'
+    ],
+    [
+        'The future belongs to those',
+        'who believe in the beauty of their dreams.',
+        '~ Eleanor Roosevelt'
+    ]
+]
+
+
+@python_task(
+    name='say',
+    inputs=[
+        StrInput(name='text', default=''),
+        IntInput(name='width', default=80)
+    ],
+    description='Say anything, https://www.youtube.com/watch?v=MbPr1oHO4Hw',
+    runner=runner
+)
+def say(*args: Any, **kwargs: Any):
+    width: int = kwargs.get('width', 50)
+    if width < _MIN_WIDTH:
+        width = _MIN_WIDTH
+    text: str = kwargs.get('text', '')
+    top_border = '┌' + '─' * (width + 2) + '┐'
+    content = [
+        '| ' + line + ' |' for line in _get_content(text, width)
+    ]
+    bottom_border = '└' + '─' * (width + 2) + '┘'
+    lines = [top_border] + content + [bottom_border] + [
+        '      \\',
+        '       \\',
+        '  o    ___    o',
+        '  | ┌-------┐ |',
+        '  |(| o   o |)|',
+        '    | └---┘ |',
+        '    └-------┘',
+    ]
+    show_lines(kwargs['_task'], *lines)
+
+
+def _get_content(text: str, width: int) -> List[str]:
+    if text == '':
+        now = datetime.datetime.now()
+        today = 'Today is ' + now.strftime('%A, %B %d, %Y')
+        current_time = 'Current time is ' + now.strftime('%I:%M %p')
+        motivational_quote = random.choice(_MOTIVATIONAL_QUOTES)
+        return [
+            today.ljust(width),
+            current_time.ljust(width),
+            ''.ljust(width),
+        ] + [
+            line.ljust(width) for line in motivational_quote
+        ]
+    return _split_text_by_width(text, width)
+
+
+def _split_text_by_width(text: str, width: int) -> List[str]:
+    original_lines = text.split('\n')
+    new_lines = []
+    for original_line in original_lines:
+        new_lines += [
+            original_line[i:i+width].ljust(width)
+            for i in range(0, len(original_line), width)
+        ]
+    return new_lines