planter-cli 3.0.3 → 3.0.5

data/src/_README.md

@@ -7,16 +7,39 @@
 
 Plant a directory structure and files using templates.
 
+<!--GITHUB-->
+- [Planter](#planter)
+  - [Installation](#installation)
+  - [Configuration](#configuration)
+    - [Scripts](#scripts)
+    - [Templates](#templates)
+      - [Multiple choice type](#multiple-choice-type)
+    - [File-specific handling](#file-specific-handling)
+      - [If/then logic for file handling](#ifthen-logic-for-file-handling)
+    - [Regex replacements](#regex-replacements)
+    - [Finder Tags](#finder-tags)
+    - [Placeholders](#placeholders)
+      - [Default values in template strings](#default-values-in-template-strings)
+      - [Modifiers](#modifiers)
+      - [If/then logic](#ifthen-logic)
+  - [Usage](#usage)
+  - [Documentation](#documentation)
+  - [Development and Testing](#development-and-testing)
+    - [Source Code](#source-code)
+    - [Requirements](#requirements)
+    - [Rake](#rake)
+    - [Guard](#guard)
+  - [Contributing](#contributing)
+  - [License](#license)
+  - [Warranty](#warranty)
+<!--END GITHUB-->
+
 ## Installation
 
     gem install planter-cli
 
 If you run into errors, try `gem install --user-install planter-cli`, or as a last ditch effort, `sudo gem install planter-cli`.
 
-### Optional
-
-If [Gum](https://github.com/charmbracelet/gum) is available it will be used for command line input.
-
 ## Configuration
 
 Planter's base configuration is in `~/.config/planter/planter.yml`. This file can contain any of the keys used in templates (see below) and will serve as a base configuration for all templates. Any key defined in this file will be overridden if it exists in a template.
@@ -42,7 +65,7 @@ Scripts can be executable files in any language, and receive the template direct
 
 Templates are directories found in `~/.config/planter/templates/[TEMPLATE_NAME]`. All files and directories inside of these template directories are copied when that template is called. Filenames, directory names, and file contents can all use template placeholders.
 
-Template placeholders are defined with `%%KEY%%`, where key is the key defined in the `variables` section of the configuration. %%KEY%% placeholders can be used in directory/file names, and in the file contents. These work in any plain text or RTF format document, including XML, so they can be used in things like Scrivener templates and MindNode files as well.
+Template placeholders are defined with `%%KEY%%`, where key is the key defined in the `variables` section of the configuration. `%%KEY%%` placeholders can be used in directory/file names, and in the file contents. These work in any plain text or RTF format document, including XML, so they can be used in things like Scrivener templates and MindNode files as well. See the subsections for info on default values and modifiers for template placeholders.
 
 Each template contains a `_planter.yml` file that defines variables and other configuration options. The file format for all configuration files is [YAML](https://yaml.org/spec/1.2.2/).
 
@@ -53,27 +76,32 @@ variables:
   - key: var_key
     prompt: Prompt text
     type: string # [string,paragraph,float,integer,number,date,choice] defaults to string
-    # value: (force value, string can include %%variables%% and regexes will be replaced. For date type can be today, time, now, etc.)
+    value: # (force value, string can include %%variables%% and regexes will be replaced. For date type can be today, time, now, etc.)
     default: Untitled
     min: 1
     max: 5
+    date_format: "%Y-%m-%d" # can be any strftime format, will be applied to any date type
+```
+
+For the date type, value can be `today`, `now`, `tomorrow`, `last thursday`, etc. and natural language will be converted to a time. The formatting will be determined automatically based on the type of the value, e.g. "now" gets a time string, but "today" just gets a YYYY-mm-dd string. This can be modified using the `date_format` key, which accepts any [strftime](https://www.fabriziomusacchio.com/blog/2021-08-15-strftime_Cheat_Sheet/) value. You can also include a date format string in single parenthesis after a natural language date value, e.g. `value: "now 'This year: %Y'"`.
+
+A configuration can include additional keys:
+
+```yaml
 script: # array of scripts, args passed as [script and args] TEMPLATE_DIR PWD
   - process.py
 git_init: false # if true, initialize a git repository in the newly-planted directory
 files: # Dictionary for file handling (see [File-specific handling](#file-specific-handling))
 replacements: # Dictionary of pattern/replacments for regex substitution, see [Regex replacements](#regex-replacements)
-repo: # If a repository URL is provided, it will be pulled and duplicated instead of copying a file structure
+repo: # If a repository URL is provided, it will be pulled and duplicated instead of copying an existing file structure
 ```
 
-#### Default values in template strings
-
-In a template you can add a default value for a placholder by adding `%default value` to it. For example, `%%project%Default Project%%` will set the placeholder to `Default Project` if the variable value matches the default value in the configuration. This allows you to accept the default on the command line but have a different value inserted in the template. To use another variable in its place, use `$KEY` in the placeholder, e.g. `%%project%$title%%` will replace the `project` key with the value of `title` if the default is selected. Modifiers can be used on either side of the `%`, e.g. `%%project%$title:snake%%`.
 
 #### Multiple choice type
 
 If the `type` is set to `choice`, then the key `choices` can contain a hash or array of choices. The key that accepts the choice should be surrounded with parenthesis (required for each choice).
 
-If a Hash is defined, each choice can have a result string:
+If a Hash/Dictionary is defined, each choice can have a result string:
 
 ```yaml
 variables:
@@ -89,7 +117,9 @@ variables:
       (z)sh: "#! /bin/zsh"
 ```
 
-If an array is defined, the string of the choice will also be its result:
+When a choice is selected from a dictionary, the result string will be inserted instead of the choice title.
+
+If an array is defined, the string of the choice will also be its result (minus any parenthesis):
 
 ```yaml
 variables:
@@ -105,48 +135,35 @@ variables:
       - 1. zsh
 ```
 
-If the choice starts with a number (as above), then a numeric list will be generated and typing the associated index number will accept that choice. Numeric lists are automatically numbered, so the preceding digit doesn't matter, as long as it's a digit. In this case a default can be defined with an integer for its placement in the list (starting with 1), and parenthesis aren't required.
-
-#### If/then logic
-
-A template can use if/then logic, which is useful with multiple choice types. It can be applied to any type, though.
-
-The format for if/then logic is:
-
-```
-%%if KEY OPERATOR VALUE%%
-content
-%%else if KEY OPERATOR VALUE2%%
-content 2
-%%else%%
-content 3
-%%endif%%
-```
-
-There should be no spaces around the comparison, e.g. `%% if language == javascript %%` won't work. The block must start with an `if` statement and end with `%%endif%%` or `%%end%%`. The `%%else%%` statement is optional -- if it doesn't exist then the entire block will be removed if no conditions are met.
-
-The key should be an existing key defined in `variables`. The operator can be any of:
+If the choice starts with a number (as above), then a numeric list will be generated and typing the associated index number will accept that choice. Numeric lists are automatically numbered, so the preceding digit doesn't matter, as long as it's a digit, and only the first item needs a digit to trigger numbering. In this case a default can be defined with an integer (in the `defaults:` key) for its placement in the list (starting with 1), and parenthesis aren't required.
 
-- `==` or `=` (equals)
-- `=~` (matches regex)
-- `*=` (contains)
-- `^=` (starts with)
-- `$=` (ends with)
-- `>` (greater than)
-- `>=` (greater than or equal)
-- `<` (less than)
-- `<=` (less than or equal)
-
-The value after the operator doesn't need to be quoted, anything after the operator will be compared to the value of the key.
+`value:` and `default:` can include previous variables, with modifiers:
 
-Logic can be used on multiple lines like the example above, or on a single line (useful for filenames):
-
-```
-%%project%%.%%if language == javascript%%js%%else if language == ruby%%rb%%else%%sh%%endif%%
+```yaml
+- variables:
+  - key: language
+    prompt: Programming language
+    type: choice
+    default: 2
+    choices:
+      - 1. ruby
+      - javascript
+      - python
+      - bash
+      - zsh
+  - key: shebang
+    prompt: Shebang line
+    type: choice
+    default: "%%language:first_letter:lowercase%%"
+    choices:
+      (r)uby: "#! /usr/bin/env ruby"
+      (j)avascript: "#! /usr/bin/env node"
+      (p)ython: "#! /usr/bin/env python"
+      (b)ash: "#! /bin/bash"
+      (z)sh: "#! /bin/zsh"
 ```
 
-Content within if/else blocks can contain variables.
-
+The above would define the `language` variable first, accepting `javascript` as default, then when displaying the menu for `shebang`, the language variable would have its first letter lowercased and set as the default option for the menu.
 
 ### File-specific handling
 
@@ -178,7 +195,17 @@ Merged content
 
 By default files that already exist in the destination directory are not overwritten, and merging allows you to add missing parts to a Rakefile or Makefile, for example.
 
-If `ask` is specified, a memu will be provided on the command line asking how to handle a file. If the file doesn't already exist, you will be asked only whether to copy the file or not. If it does exist, `overwrite` and `merge` options will be added.
+If `ask` is specified, a menu will be provided on the command line asking how to handle a file. If the file doesn't already exist, you will be asked only whether to copy the file or not. If it does exist, `overwrite` and `merge` options will be added.
+
+#### If/then logic for file handling
+
+The operation for a file match can be an if/then statement. There are two formats for this.
+
+First, you can simply write `OPERATION if VARIABLE COMP VALUE`, e.g. `copy if language == ruby`. This can have an `else` statement: `overwrite if language == ruby else copy`.
+
+You can also format it as `if VARIABLE COMP VALUE: OPERATION; else: OPERATION`. This format allows `else if` statements, e.g. `if language == perl: copy;else if language == ruby: overwrite; else: ignore`.
+
+Planter's if/then parsing does not handle parenthetical or boolean operations.
 
 ### Regex replacements
 
@@ -196,12 +223,75 @@ Replacements are performed on both file/directory names and file contents. This
 
 If `preserve_tags` is set to `true` in the config (either base or template), then existing Finder tags on the file or folder will be copied to the new file when a template is planted.
 
+### Placeholders
+
+Placeholders are `%%VARIABLE%%` strings used in filenames and within the content of the files. At their most basic, this would just look like `%%project_name%%`. But you can supply default values, string modifiers, and even if/then logic.
+
+#### Default values in template strings
+
+In a template you can add a default value for a placholder by adding `%default value` to it. For example, `%%project%Default Project%%` will set the placeholder to `Default Project` if the variable value matches the default value in the configuration (or doesn't exist). This allows you to accept the default on the command line but have a different value inserted in the template. To use another variable in its place, use `$KEY` in the placeholder, e.g. `%%project%$title%%` will replace the `project` key with the value of `title` if the default is selected. Modifiers can be used on either side of the `%`, e.g. `%%project%$title:snake%%`.
+
+#### Modifiers
+
+A `%%variable%%` in a template can include modifiers that affect the output of the variable. These are added as `%%variable:MODIFIER%%` and multiple modifiers can be strung together, e.g. `%%language:lowercase:first_letter%%`. The available modifiers are (listed with available abbreviations):
+
+- `snake` (`s`): snake_case the value
+- `camel` (`cam`): camelCase the value
+- `upper` (`u`): UPPERCASE the value
+- `lower` (`l`, `d`): lowercase the value
+- `title` (`t`): Title Case The Value
+- `slug` or `file` (`sl`): slug-format-the-value
+- `first_letter` (`fl`): Extract the first letter from the value
+- `first_word` (`fw`): Extract the first word from the value
+
+#### If/then logic
+
+A template can use if/then logic, which is useful with multiple choice types. It can be applied to any type, though.
+
+The format for if/then logic is:
+
+```
+%%if KEY OPERATOR VALUE%%
+content
+%%else if KEY OPERATOR VALUE2%%
+content 2
+%%else%%
+content 3
+%%endif%%
+```
+
+There should be no spaces around the comparison, e.g. `%% if language == javascript %%` won't work. The block must start with an `if` statement and end with `%%endif%%` or `%%end%%`. The `%%else%%` statement is optional -- if it doesn't exist then the entire block will be removed if no conditions are met.
+
+The key should be an existing key defined in `variables`. The operator can be any of:
+
+- `==` or `=` (equals)
+- `=~` (matches regex)
+- `*=` (contains)
+- `^=` (starts with)
+- `$=` (ends with)
+- `>` (greater than)
+- `>=` (greater than or equal)
+- `<` (less than)
+- `<=` (less than or equal)
+
+Any of these operators can be inverted (negated) by preceding with an exclamation point, e.g. `!=` means `not equal` and `!*=` means `does not contain`.
+
+The value after the operator doesn't need to be quoted, anything after the operator will be compared to the value of the key.
+
+Logic can be used on multiple lines like the example above, or on a single line (useful for filenames):
+
+
+    %%project%%.%%if language == javascript%%js%%else if language == ruby%%rb%%else%%sh%%endif%%
+
+
+Content within if/else blocks can contain variables. Planter's if/then parsing does not handle parenthetical or boolean operations.
+
 ## Usage
 
 The executable for Planter is `plant`. You can run `plant TEMPLATE` in any directory and TEMPLATE will be planted in the current directory. You can also use `--in PATH` to plant in another directory.
 
 ```
-Usage: planter [options] TEMPLATE
+Usage: plant [options] TEMPLATE
     --defaults                       Accept default values for all variables
     -i, --in TARGET                  Plant in TARGET instead of current directory
     -o, --overwrite                  Overwrite existing files
@@ -224,7 +314,6 @@ Variables can be passed on the command line with `--var KEY:VALUE`. This flag ca
 ## Documentation
 
 - [YARD documentation][RubyDoc] is hosted by RubyDoc.info.
-- [Interactive documentation][Omniref] is hosted by Omniref.
 
 [RubyDoc]: http://www.rubydoc.info/gems/planter-cli
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: planter-cli
 version: !ruby/object:Gem::Version
-  version: 3.0.3
+  version: 3.0.5
 platform: ruby
 authors:
 - Brett Terpstra
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-02 00:00:00.000000000 Z
+date: 2024-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bump
@@ -368,11 +368,13 @@ files:
 - lib/planter.rb
 - lib/planter/array.rb
 - lib/planter/color.rb
+- lib/planter/config.rb
 - lib/planter/errors.rb
 - lib/planter/file.rb
 - lib/planter/fileentry.rb
 - lib/planter/filelist.rb
 - lib/planter/hash.rb
+- lib/planter/numeric.rb
 - lib/planter/plant.rb
 - lib/planter/prompt.rb
 - lib/planter/script.rb
@@ -472,6 +474,7 @@ files:
 - spec/planter/filelist_spec.rb
 - spec/planter/hash_spec.rb
 - spec/planter/plant_spec.rb
+- spec/planter/prompt_spec.rb
 - spec/planter/script_spec.rb
 - spec/planter/string_spec.rb
 - spec/planter/symbol_spec.rb
@@ -482,6 +485,7 @@ files:
 - spec/templates/test/%%project:snake%%.rtf
 - spec/templates/test/Rakefile
 - spec/templates/test/_planter.yml
+- spec/templates/test/_scripts/plant.sh
 - spec/templates/test/_scripts/test.sh
 - spec/templates/test/_scripts/test_fail.sh
 - spec/templates/test/test.rb
@@ -522,6 +526,7 @@ test_files:
 - spec/planter/filelist_spec.rb
 - spec/planter/hash_spec.rb
 - spec/planter/plant_spec.rb
+- spec/planter/prompt_spec.rb
 - spec/planter/script_spec.rb
 - spec/planter/string_spec.rb
 - spec/planter/symbol_spec.rb
@@ -532,6 +537,7 @@ test_files:
 - spec/templates/test/%%project:snake%%.rtf
 - spec/templates/test/Rakefile
 - spec/templates/test/_planter.yml
+- spec/templates/test/_scripts/plant.sh
 - spec/templates/test/_scripts/test.sh
 - spec/templates/test/_scripts/test_fail.sh
 - spec/templates/test/test.rb