An Informal Introduction Into Sparrow6
Tags: raku, rakulang, automation, powershell
Published: 2019-10-29 16:08:44

---
title: An Informal Introduction Into Sparrow6
published: true
description: informal introduction into Sparrow6 - Raku automation framework
tags: raku, rakulang, automation, powershell
---

Sparrow6 is an automation framework enables scripting and tasks automation in efficient manner.


---

```
#     _____                                                      __  
#    / ____|                                                    / /  
#   | (___    _ __     __ _   _ __   _ __    ___   __      __  / /_  
#    \___ \  | '_ \   / _` | | '__| | '__|  / _ \  \ \ /\ / / | '_ \ 
#    ____) | | |_) | | (_| | | |    | |    | (_) |  \ V  V /  | (_) |
#   |_____/  | .__/   \__,_| |_|    |_|     \___/    \_/\_/    \___/ 
#            | |                                                     
#            |_|                                                     
```
# Install

`zef install Sparrow6`


# First task

`nano task.pl6`

```perl
#!perl6

say 'Hello World'

```

Run task:

`perl6 -MSparrow6::DSL -e task-run`:

```
14:47:32 10/29/2019 [C:\Users\melezhik\projects\Sparrow6Intro] Hello World
```

# Configuring task

Just create a file named `config.yaml` and place it in the root directory:


`nano config.yaml`


```yaml
birds:
 - sparrow
 - crow
 - tomtit
```

To access configuration file inside task call `config()` function:

`nano task.pl6`

```perl
#!perl6

say "Hello World";

for config()<birds><> -> $b {
    say $b
}
```

`perl6 -MSparrow6::DSL -e task-run`

```
14:51:56 10/29/2019 [C:\Users\melezhik\projects\Sparrow6Intro] Hello World
14:51:56 10/29/2019 [C:\Users\melezhik\projects\Sparrow6Intro] sparrow
14:51:56 10/29/2019 [C:\Users\melezhik\projects\Sparrow6Intro] crow
14:51:56 10/29/2019 [C:\Users\melezhik\projects\Sparrow6Intro] tomtit
```

To override tasks parameters use Sparrow6 Rakudo API:


`nano run.pl6`

```perl
#!perl6

task-run ".", %(
   birds => ( 'wren', 'owl', 'eagle' )
)
```

`perl6 -MSparrow6::DSL run.pl6`:

```
14:56:43 10/29/2019 [.] Hello World
14:56:43 10/29/2019 [.] wren
14:56:43 10/29/2019 [.] owl
14:56:43 10/29/2019 [.] eagle
```


# Multi language support

Do you know, that Sparrow6 allows you to create tasks not only on Raku? Choose the one you like:


* Perl
* Bash
* Python
* Ruby
* Powershell

Sparrow6 is a language friendly framework. Why? Sometime I find it's more efficient to create tasks in the language more suitable to the problem being solved. 

**There is more then one language to do it** - TIMTOLTDI.

As an example let's rewrite our task in Powershell, it will work just fine.


`nano task.ps1`

```powershell
Write-Host "Hello Powershell"

foreach ( $b in config birds ) {
   Write-Host $b
}

```

`perl6 -MSparrow6::DSL run.pl6`:

```
15:19:59 10/29/2019 [.] Hello Powershell
15:19:59 10/29/2019 [.] wren
15:19:59 10/29/2019 [.] owl
15:19:59 10/29/2019 [.] eagle
```

# TDD

Sparrow6 enables embedded test facilities so one can "inject" tests right into scripts.


Let's ensure that our script is friendly and greets every time:


`nano task.check`

```check
regexp: Hello \s+ \S
```

`perl6 -MSparrow6::DSL run.pl6`:

```
15:23:29 10/29/2019 [.] Hello Powershell
15:23:29 10/29/2019 [.] wren
15:23:29 10/29/2019 [.] owl
15:23:29 10/29/2019 [.] eagle
[task check] stdout match <Hello \s+ \S> True
```

[Task Check DSL](https://github.com/melezhik/Sparrow6/blob/master/documentation/taskchecks.md) allows many other things to do to verify and parse arbitrary text output.

You don't need a dedicated testing framework, to test your scripts. Batteries are included!


# Task - functions

Sparrow6 tasks could act as functions returning values one can handle in high-level Raku scenarios.

Let's say we want to return one random bird from the input list. Update original code of `task.pl6`:

```perl
#!perl6

say "Hello World";

for config()<birds><> -> $b {
  say $b
}

update_state %( random-bird => config()<birds>.pick )
```

And handle the value inside Raku high-level scenario `run.pl6`:

```perl
#!perl6

my %state = task-run ".", %(
   birds => ( 'wren', 'owl', 'eagle' )
);

say %state.perl;
```

And now run it:

`perl6 -MSparrow6::DSL run.pl6`:

```
18:03:16 10/29/2019 [.] Hello World
18:03:16 10/29/2019 [.] wren
18:03:16 10/29/2019 [.] owl
18:03:16 10/29/2019 [.] eagle
[task check] stdout match <Hello \s+ \S> True
{:random-bird("eagle")}
```

Today we have a rain of eagles, huh?

# Packaging and distribution

Once you're happy enough with your task and think it could be reusable by others, it's dead easy to wrap it in Sparrow6 package and distribute as a Sparrow6 plugin. Just add a couple of files.


## Documentation


It's should `Readme.md` documentation file in markdown format.


`nano Readme.md`

```markdown

# Birds

Prints birds' names. 

# Install

s6 --install birds. 

# Install

s6 --install birds

```

## Sparrow6 meta file

Create a file called `sparrow.json` to define plugin meta data:


`nano sparrow.json`

```json
{
  "name": "birds",
  "description": "Prints birds names",
  "version": "0.1.0"
}
```

To upload plugin run `s6`  Sparrow6 cli.

`s6 --upload`:

```
15:33:41 10/29/2019 [repository] upload plugin
15:33:41 10/29/2019 [repository] upload birds@0.1.0
```

Now someone else could enjoy reading beautiful birds' names:


`s6 --index-update`:

```
15:36:15 10/29/2019 [repository] update local index
15:36:15 10/29/2019 [repository] index updated from file://C:\Users\melezhik/repo/api/v1/index
``` 

`s6 --install birds`:

```
15:37:49 10/29/2019 [repository] install plugin birds
```


Either through cli:

`s6 --plg-run birds`:

```
15:38:44 10/29/2019 [task-cli] run plg birds
15:38:44 10/29/2019 [task-cli] run thing birds
15:38:45 10/29/2019 [birds] Hello Powershell
15:38:45 10/29/2019 [birds] sparrow
15:38:45 10/29/2019 [birds] crow
15:38:45 10/29/2019 [birds] tomtit
[task check] stdout match <Hello \s+ \S> True
```

Or by Raku API


`tom --edit birds`


```perl
#!perl6

task-run "print birds names", "birds", %(
  birds => (
   'GreenSparrow',
   'BlackSparrow',
   'YellowSparrow'
  )
)

```

`tom birds`:

```
15:43:38 10/29/2019 [repository] index updated from file://C:\Users\melezhik/repo/api/v1/index
15:43:39 10/29/2019 [print birds names] Hello Powershell
15:43:39 10/29/2019 [print birds names] GreenSparrow
15:43:39 10/29/2019 [print birds names] BlackSparrow
15:43:39 10/29/2019 [print birds names] YellowSparrow
[task check] stdout match <Hello \s+ \S> True
```


---

# Conclusion

This was informal introduction into Sparrow6 - Raku automation framework.

Thank you for reading. Follow [Sparrow6](https://github.com/melezhik/Sparrow6) to know more. I hope you'll find Sparrow6 a useful tool and start using it, as I do in my daily @work.