txt: ## dist_zef-samy-App-Stouch.md
  # stouch
  
  **stouch** (**s**tock **touch**) is a program that can create files and directory trees from pre-existing templates. It is also capable of performing basic text substitution on the contents of created files.
  
  ## Installing
  
  **stouch** should be able to run on both Unix-like and Windows operating systems, as long as your system supports the dependencies listed below.
  
  **stouch** requires the [rakudo](https://rakudo.org/) compiler.
  
  **stouch** depends on the following Raku modules, which can be installed via [zef](https://github.com/ugexe/zef):
  
  * `IO::MiddleMan` (for tests)
  
  Once the required dependencies are installed, **stouch** can be installed via zef.
  
  ```
  zef install .
  
  ```
  
  ## Usage
  
  ```
  stouch [options] file ...
  
  ```
  
  This section is a rough overview of **stouch**'s capabilities, please consult the manual for more exhaustive documentation. The manual can be accessed via `rakudoc` or the `--man` option.
  
  ```
  rakudoc App::Stouch
  stouch --man
  
  ```
  
  By default, **stouch** will create files using templates determined from each file's suffix. When creating a file, **stouch** will copy the file/directory tree to the desired location, and perform any specified text substitutions on the created files.
  
  For **stouch** to work, you must first set up a template directory. The template directory can be specified by either `-d` option or the `STOUCH_TEMPLATES` environment variable. If neither of those are specified, **stouch** will default to `~/.stouch`. Each template in the template directory must be named after the file it is templating with the `.template` suffix. Here is an example template directory:
  
  ```
  template-directory/
  L raku.template
  L rakumod.template
  L c.template
  L pl.template
  ...
  
  ```
  
  This means we can use **stouch** to create the following files:
  
  ```
  stouch test.raku test.rakumod test.c test.pl
  
  ```
  
  When creating a file/directory, **stouch** will determine the template to use either by the desired file's suffix, or the `-t` option if it is specified.
  
  **stouch** can do text substitutions via *substitution targets*. A substitution target is a string with alphanumeric or underscore characters enclosed in two curly brackets, like this:
  
  ```
  {{this}} <-- is a substitution target
  
  ```
  
  Substitution targets can optionally be substituted via the `-s` option, which allows you to specify the text you would like to replace a substitution target. For example, say you have this template file:
  
  ```
  This is a {{type}} file!
  It does {{whatever}}!
  
  ```
  
  and you use **stouch** with `-s "type => text, whatever => stuff"`, the created file would look like this:
  
  ```
  This is a text file!
  It does stuff!
  
  ```
  
  **stouch** can also perform text substitutions on file paths.
  
  ```
  # This will create a file named foo.raku
  stouch -s "script => foo" {{script}}.raku
  
  ```
  
  These path substitutions can also apply to children paths of a template directory.
  
  ## Copyright
  
  Copyright 2024-2025, Samuel Young
  
  This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.
  