txt: ## dist_zef-melezhik-Tomtit.md
  # Tomtit
  
  Tomtit - Raku Task Runner
  
  # Build Status
  
  ![SparkyCI](https://sparky.sparrowhub.io/badge/gh-melezhik-Tomtit?foo=bar)
  
  # Install
  
  ```
  zef install Tomtit
  
  ```
  
  # Quick start
  
  Tomtit is a task runner based on Sparrow6 engine, so just drop a few tasks under *some* folder
  and run them as Raku scenarios:
  
  ```
  mkdir -p tasks/hello
  
  ```
  
  `tasks/hello/task.bash`:
  
  ```
  echo "hello world"
  
  ```
  
  `.tomty/hello.raku`:
  
  ```
  task-run "tasks/hello";
  
  ```
  
  You can do *more* then that, [read more](https://github.com/melezhik/Sparrow6/blob/master/documentation/development.md)
  about Sparrow6 tasks on Sparrow6 documentation.
  
  # Cli api
  
  ```
  tom $action|$options $thing
  
  ```
  
  Initialize tomtit:
  
  ```
  tom --init
  
  ```
  
  Run scenario:
  
  ```
  tom $scenario
  
  ```
  
  Default action (list of scenarios):
  
  ```
  tom
  
  ```
  
  List available scenarios:
  
  ```
  tom --list
  
  ```
  
  Get help:
  
  ```
  tom --help
  
  ```
  
  Show the last executed scenario:
  
  ```
  tom --last
  
  ```
  
  Clean Tomtit cache:
  
  ```
  tom --clean
  
  ```
  
  Example:
  
  ```
  tom --list
  
  [scenarios list]
  test
  build
  install
  
  tom test        
  
  ```
  
  # Create scenarios
  
  Tomtit scenarios are just Raku wrappers for underlying Sparrow6 tasks.
  
  Create a `.tom` directory, to hold all the scenarios:
  
  ```
  mkdir .tom/
  nano .tom/build.raku
  nano .tom/test.raku
  nano .tom/install.raku
  
  ```
  
  And the drop some tasks at *some* folder:
  
  `tasks/build/task.bash`:
  
  ```
  set -e
  make
  make test
  sudo make install 
  
  ```
  
  `.tom/build.raku`:
  
  ```
  task-run "tasks/build";
  
  ```
  
  You might want to ignore Tomtit cache which commit files to SCM:
  
  ```
  git add .tom/
  echo .tom/.cache >> .gitignore
  
  ```
  
  # Using prebuilt Sparrow6 DSL functions
  
  [Sparrow6 DSL](https://github.com/melezhik/Sparrow6/blob/master/documentation/dsl.md) provides
  one with ready to use function for some standard automation tasks:
  
  `.tom/example.raku`:
  
  ```
  
  # you can use Sparrow6 DSL functions
  # to do many system tasks, like:
  
  # creation of files and directories
  
  file 'passwords.txt', %( 
      owner => "root",
      mode => "700",    
      content => "super secret" 
  );
  
  directory '.cache', %(
      owner => "server"
  );
  
  # or restarting of services
  
  service-restart "web-app";
  
  # or you can run a specific sparrow plugin
  # by using task-run function:
  
  task-run 'my task', 'plugin', %( foo => 'bar' );
  
  # for example, to set git repository, 
  # use git-base plugin:
  
  task-run "set git", "git-base", %(
      email => 'melezhik@gmail.com',
      name  => 'Alexey Melezhik',
      config_scope => 'local',
      set_credential_cache => 'on'
  );
  
  ```
  
  # Profiles
  
  Profiles are predefined sets of Tomtit scenarios.
  To start using scenarios from profile you say:
  
  ```
  tom --profile $profile
  
  ```
  
  Once the command is executed the profile scenarios get installed to the
  base Tomtit directory.
  
  To list available profiles say this:
  
  ```
  tom --profile
  
  ```
  
  To list profiles scenarios say this:
  
  ```
  tom --list --profile $profile
  
  ```
  
  You can install selected scenario from profile by using special notation:
  
  ```
  tom --profile $profile@$scenario
  
  ```
  
  For example to install `commit` scenario from `git` profile:
  
  ```
  tom --profile git@commit 
  
  ```
  
  # Portable profiles
  
  Tomtit exposes API to create portable profiles as regular Raku modules.
  
  You should create Raku module in `Tomtit::Profile` namespace with the *our* function `profile-data`,
  returning `Hash` with scenarios data.
  
  For example:
  
  ```
  unit module Tomtit::Profile::Pets:ver<0.0.1>;
  
  our sub profile-data () {
  
      my %a is Map  = (
          cat   => (slurp %?RESOURCES<cat.raku>.Str),
          dog   => (slurp %?RESOURCES<dog.raku>.Str),
          fish  => (slurp %?RESOURCES<fish.raku>.Str)
      );
  
  }
  
  ```
  
  The above module defines [Tomtit::Profile::Pets](https://github.com/melezhik/tomtit-profile-pets) profile with 3 scenarios `cat, dog, fish` installed as module resources:
  
  ```
  resources/
    cat.raku
    dog.raku
    fish.raku
  
  ```
  
  Now we can install it as regular Raku module and use through tom:
  
  ```
  zef install Tomtit::Profile::Pets
  
  ```
  
  Once module is installed we can install related profile. Note that we should replace `::` by `-` (\*) symbols
  when referring to profile name.
  
  ```
  tom --list --profile Tomtit-Profile-Pets
  
  load portable profile Tomtit::Profile::Pets as Raku module ...
  [profile scenarios]
  Tomtit::Profile::Pets@cat       installed: False
  Tomtit::Profile::Pets@dog       installed: False
  Tomtit::Profile::Pets@fish      installed: False
  
  tom --profile Tomtit-Profile-Pets
  
  install Tomtit::Profile::Pets@cat ...
  install Tomtit::Profile::Pets@dog ...
  install Tomtit::Profile::Pets@fish ...
  
  ```
  
  (\*) Tomtit require such a mapping so that Bash completion could work correctly.
  
  # Removing scenarios
  
  To remove installed scenario say this:
  
  ```
  tom --remove $scenario
  
  ```
  
  # Edit scenario source code
  
  Use `--edit` to create scenario from the scratch or to edit existed scenario source code:
  
  ```
  tom --edit $scenario
  
  ```
  
  # Getting scenario source code
  
  Use `--cat` command to print out scenario source code:
  
  ```
  tom --cat $scenario
  
  ```
  
  Use `--lines` flag to print out with line numbers.
  
  # Environments
  
  * Tomtit environments are configuration files, written on Raku and technically speaking are plain Raku Hashes
  * Environment configuration files should be placed at `.tom/conf` directory:
  
  .tom/env/config.raku:
  
  ```
  {
      name => "Tomtit",
      who-are-you => "smart bird"
  
  }
  
  ```
  
  Run Tomtit.
  
  It will pick the `.tom/env/config.raku` and read configuration from it, variables will be accessible as `config` Hash,
  inside Tomtit scenarios:
  
  ```
  my $name = config<name>;
  my $who-are-you = config<who-are-you>;
  
  ```
  
  To define *named* configuration ( environment ), simply create `.tom/env/config{$env}.raku` file and refer to it through
  `--env=$env` parameter:
  
  ```
  nano .tom/env/config.prod.raku
  
  tom --env=prod ... other parameters here # will run with production configuration
  
  ```
  
  You can run editor for environment configuration by using --edit option:
  
  ```
  tom --env-edit test    # edit test enviroment configuration
  
  tom --env-edit default # edit default configuration
  
  ```
  
  You can activate environment by using `--env-set` parameter:
  
  ```
  tom --env-set prod    # set prod environment as default
  tom --env-set         # to list active (current) environment
  tom --env-set default # to set current environment to default
  
  ```
  
  To view environment configuration use `--env-cat` command:
  
  ```
  tom --env-cat $env
  
  ```
  
  You print out the list of all environments by using `--env-list` parameters:
  
  ```
  tom --env-list
  
  ```
  
  # Tomtit cli configuration
  
  You can set Tomtit configuration in `~/tom.yaml` file:
  
  ```
  # list of portable Tomtit profiles,
  # will be available through Bash completion
  
  profiles:
  
    - Tomtit-Foo
    - Tomtit-Bar
    - Tomtit-Bar-Baz
  
  # you can also setup some Tomtit cli options here
  
  options:
  
    quiet: true
  
  ```
  
  # Options
  
  ```
  --verbose          # run scenario in verbose mode
  --quiet,-q         # run scenario in less verbose mode
  --color            # color output
  --no_index_update  # don't update Sparrow repository index
  --dump_task        # dump task code before execution, see SP6_DUMP_TASK_CODE Sparrow documentation
  
  ```
  
  Example of `~/tom.yaml` file:
  
  ```
  options:
    no_index_update: true
    quiet: true
  
  ```
  
  # Bash completion
  
  You can install Bash completion for tom cli.
  
  ```
  tom --completion
  source  ~/.tom_completion.sh
  
  ```
  
  # Development
  
  ```
  git clone https://github.com/melezhik/Tomtit.git
  zef install --/test .
  zef install Tomty
  tomty --all # run tests
  
  ```
  
  # See also
  
  * [ake](https://github.com/Raku/ake) - a Raku make-a-like inspired by rake
  
  # Author
  
  Alexey Melezhik
  
  # Thanks to
  
  God Who gives me inspiration in my work
  