app_archetype 1.2.8 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69596e80065838a6a6ee3e106cf923c0a5cde9c3ab021ad453cec86693b7a54e
-  data.tar.gz: 0c2efba5fa04672d651f85ee96c1758d5a1b2af04dc8229684f6a510208bcc46
+  metadata.gz: 2bb47f2a7af33ef1049d56b7e69a036d61d7de23460550b543a4ac4d61642981
+  data.tar.gz: a50728d4d05815813e7dbfa4106fabfe6905abde52991a287f7de4cc5fbcccc4
 SHA512:
-  metadata.gz: 6bdf46483034b8a0655597c181a2710a8d426f10b27aef0f9ae3d49598f3457e5f9231aab1c853dfbd17fefa2ceb2cb2a80e251a146a25abac3bb72e5ae789e0
-  data.tar.gz: 5925cafc17983ad94872e22a430a858b5f53feb1ebef9a4b1b00f1c6a337816b7331d0cc51f06c5d9bba74f57b1884378cc869cb283ceac46272970039ad10ca
+  metadata.gz: bb195a0f24fcada15e1bebb8f08b45b97c2be98d84ceab8e145a4becccf33c4358039207e32f71a661dfee3c98a202a595ea81a5be8eca5a796dc0ecfd82c8de
+  data.tar.gz: bae355af34912e60be9260355222fb295226df3b01c0ad4346e8678831688cb0e13238cccd56e177cdcdda32c417e269630dd1ea6fed1663b1a48600d6b98f94

data/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    app_archetype (1.2.8)
+    app_archetype (1.3.0)
       cli-format (~> 0.2)
+      hashie
       highline (~> 2.0)
       json (~> 2.3)
       json-schema (~> 2.8)
@@ -12,11 +13,13 @@ PATH
       ostruct (~> 0.3)
       ruby-handlebars (~> 0.4)
       thor (~> 1.0)
+      tty-prompt (~> 0.23.1)
+      tty-table (~> 0.12.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (6.1.4)
+    activesupport (6.1.4.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -53,11 +56,12 @@ GEM
       path_expander (~> 1.0)
       ruby_parser (~> 3.1, > 3.1.0)
       sexp_processor (~> 4.8)
+    hashie (4.1.0)
     highline (2.0.3)
-    i18n (1.8.10)
+    i18n (1.8.11)
       concurrent-ruby (~> 1.0)
     ice_nine (0.11.2)
-    json (2.5.1)
+    json (2.6.1)
     json-schema (2.8.1)
       addressable (>= 2.4)
     jsonnet (0.4.0)
@@ -65,16 +69,18 @@ GEM
     kwalify (0.7.2)
     launchy (2.5.0)
       addressable (~> 2.7)
-    logger (1.4.3)
+    logger (1.4.4)
     method_source (1.0.0)
-    mini_portile2 (2.6.1)
+    mini_portile2 (2.7.1)
     minitest (5.14.4)
-    os (1.1.1)
-    ostruct (0.4.0)
+    os (1.1.4)
+    ostruct (0.5.0)
     parallel (1.19.2)
     parser (2.7.1.5)
       ast (~> 2.4.1)
     parslet (1.8.2)
+    pastel (0.8.0)
+      tty-color (~> 0.5)
     path_expander (1.1.0)
     private_gem (1.1.4)
       bundler (> 1.7, < 3.0)
@@ -138,20 +144,41 @@ GEM
       docile (~> 1.1)
       simplecov-html (~> 0.11)
     simplecov-html (0.12.3)
+    strings (0.2.1)
+      strings-ansi (~> 0.2)
+      unicode-display_width (>= 1.5, < 3.0)
+      unicode_utils (~> 1.4)
+    strings-ansi (0.2.0)
     text-table (1.2.4)
     thor (1.0.1)
     thread_safe (0.3.6)
+    tty-color (0.6.0)
+    tty-cursor (0.7.1)
+    tty-prompt (0.23.1)
+      pastel (~> 0.8)
+      tty-reader (~> 0.8)
+    tty-reader (0.9.0)
+      tty-cursor (~> 0.7)
+      tty-screen (~> 0.8)
+      wisper (~> 2.0)
+    tty-screen (0.8.1)
+    tty-table (0.12.0)
+      pastel (~> 0.8)
+      strings (~> 0.2.0)
+      tty-screen (~> 0.8)
     tty-which (0.4.2)
     tzinfo (2.0.4)
       concurrent-ruby (~> 1.0)
     unicode-display_width (1.7.0)
+    unicode_utils (1.4.0)
     virtus (1.0.5)
       axiom-types (~> 0.1)
       coercible (~> 1.0)
       descendants_tracker (~> 0.0, >= 0.0.3)
       equalizer (~> 0.0, >= 0.0.9)
+    wisper (2.0.1)
     yard (0.9.25)
-    zeitwerk (2.4.2)
+    zeitwerk (2.5.1)
 
 PLATFORMS
   ruby

data/README.md

@@ -14,7 +14,9 @@ gem install app_archetype
 
 For inclusion in another script or application, add this line to your application's Gemfile:
 
-Add the following to your Gemfile
+```ruby
+gem 'app_archetype'
+```
 
 ## Getting Started
 
@@ -44,42 +46,71 @@ echo 'export ARCHETYPE_EDITOR="vi"' >> $HOME/.zshrc # sets vim as default editor
 echo 'export ARCHETYPE_EDITOR="vi"' >> $HOME/.bashrc # sets vim as default editor
 ```
 
-## Usage
+### Use in another project/script (standalone)
 
-### Creating a template
+An alternative method of usage is to create standalone ruby scripts for standalone exection (outside of the `ARCHETYPE_TEMPLATE_DIR`). As an example, the following describes a code component renderer, where a command class for a simple CLI application can be rendered automatically.
 
-Templates are a collection of files in the template folder with a manifest. The structure is thus:
+For this example you may wish to introduce a `scripts` folder to a project:
+
+```bash
+mkdir path/to/my_project/scripts
+```
+
+And under that make an archetypes template directory:
 
 ```text
- - $ARCHETYPE_TEMPLATE_DIR
- | - my_template
- | - | - template/
- | - | - | - file.erb
- | - | - | - file2.txt
- | - | - manifest.json
+ - 📁 path/to/my_project/scripts
+ | - 📁 generators/
+ | - | - 📁 command/
+ | - | - | - 📁 template/
+ | - | - | - | - 📁 lib/
+ | - | - | - | - | 📁 app_archetype/
+ | - | - | - | - | - | 📁 commands/
+ | - | - | - | - | - | - | 📄 {{command_name.snake_case}}.rb.hbs
+ | - | - | - 📄 manifest.json
+ | - | 📄 create_new_command
 ```
 
-Each template must include a manifest which has instructions necessary to render the template at run time.
+A standalone generator can be written using the standalone render method exposed in the `AppArchetype` namespace. The following would be the content of the `create_new_command` script.
 
-To create a blank template run the new command with the relative (from your template directory) path to your new template. For example to create a ruby gem you might:
+```ruby
+#!/usr/bin/env ruby
 
-```bash
-archetype new ruby/gem # creates a template at $ARCHETYPE_TEMPLATE_DIR/ruby/gem
+require_relative '../lib/app_archetype'
 
-# or
+puts 'CREATE NEW COMMAND'
 
-archetype new ruby_gem # creates a template at $ARCHETYPE_TEMPLATE_DIR/ruby_gem
+manifest = AppArchetype.render_template(
+  collection_dir: File.join(__dir__, 'generators'),
+  template_name: 'command',
+  destination_path: File.expand_path(File.join(__dir__, '..'))
+)
+```
+
+## Usage
 
-# or
+### Creating a template
 
-archetype new ruby/gem/on_rails # creates a template at $ARCHETYPE_TEMPLATE_DIR/ruby/gem/on_rails
+Templates are a collection of files in the template folder with a manifest. The structure is thus:
 
-# etc.
+```text
+ - 📁 $ARCHETYPE_TEMPLATE_DIR
+ | - 📁 my_template
+ | - | - 📁 template/
+ | - | - | - 📄 file.erb
+ | - | - | - 📄 file2.txt
+ | - | - 📄 manifest.json
+```
+
+To create a blank template like the one above in the `ARCHETYPE_TEMPLATE_DIR` run:
+
+```bash
+archetype new
 ```
 
 #### Template Manifests
 
-A manifest has a name, version and set of variables. A sample manifest looks like this:
+Template manifests describe what should be done with a template at render time. For more detailed documentation on the AppArchetype manifest schema see [https://docs.biggerconcept.com/app_archetype/templates/manifest/](https://docs.biggerconcept.com/app_archetype/templates/manifest/) for more detail, however as a brief overview, a manifest has a name, version and set of variables. A sample manifest looks like this:
 
 ```json
 {
@@ -133,34 +164,125 @@ If plain ol' JSON isn't quite enough for you - manifests can also be expressed i
 
 See [https://jsonnet.org/](https://jsonnet.org/) for more jsonnet documentation
 
-#### Template Files
+#### Template Folder
 
 Templates are a collection of files within a folder. You may put any files you want in side the `/template` directory and when it comes time to use the template.
 
-ERB templates or handlebar templates will be rendered using the variables specified in the manifest.json. Anything that's not ERB or HBS will be copied across to the destination as is.
+ERB templates or handlebar templates (HBS) will be rendered using the variables specified in the manifest.json. Anything that's not ERB or HBS will be copied across to the destination as is.
+
+You can include handlebars in file names, and like template files, the variables will be used to render the filenames. See [https://docs.biggerconcept.com/app_archetype/templates/folder/](https://docs.biggerconcept.com/app_archetype/templates/folder/) for more detailed information about template folders.
+
+#### Variable Supporting Functions
+
+AppArchetype exposes functions to either further parse the value of a variable or generate data as a value of a variable. The use cases are subtly different, but can be described in the following groups:
+
+- [Generator Functions](https://docs.biggerconcept.com/app_archetype/templates/functions/generators/) useful for generating data for use within filenames and template files
+- [Helper Functions](https://docs.biggerconcept.com/app_archetype/templates/functions/helpers/) useful for parsing values provided for variables.
+
+See the supporting documentation for more specifid information about supporting functions.
+
+### Using the CLI
 
-You can include handlebars in file names, and like template files, the variables will be used to render the filenames.
+When setup with a template directory and when installed into the system, app archetype has the following commands:
+
+- `render` - Renders a template to the current location
+- `list` - Prints a list of known templates to STDOUT
+- `find` - Searches for a template by name
+- `open` - Opens manifest of template in `ARCHETYPE_EDITOR` process
+- `new` - Creates a new blank template in `ARCHETYPE_TEMPLATE_DIR`
+- `delete` - Deletes template and manifest from `ARCHETYPE_TEMPLATE_DIR`
+- `variables` - Prints list of known variables from a manifest
+- `path` - Prints path to `ARCHETYPE_TEMPLATE_DIR` to STDOUT
+- `version` - Prints gem version to STDOUT
+- `help` - Provides help on any of the above commands
+
+You will find detailed usage instructions of all commands here: [https://docs.biggerconcept.com/app_archetype/commands/](https://docs.biggerconcept.com/app_archetype/commands/)
 
 ### Rendering a Template
 
-Adjust the template manifest to include the variables you want, and then run:
+The [`archetype render`](https://docs.biggerconcept.com/app_archetype/commands/render/) command will render a template from the `ARCHETYPE_TEMPLATE_DIR` to the current CLI location.
+
+It supports an optional `--name` parameter that refers to the name of the template to render, when this is not provided, the tool will present a list of known templates.
+
+To use:
 
 ```bash
 mkdir where_id_like_to_render
 cd where_id_like_to_render
-archetype render my_template
+archetype render --name my_template
 ```
 
-And the template will be rendered with the instructions in the manifest to the destinaton location as simple as that.
-
 ### Listing Templates
 
-You can list the templates in your template directory at any time by running the list command:
+You can list the templates in your template directory at any time by running the [`archetype list`](https://docs.biggerconcept.com/app_archetype/commands/list/) command:
 
 ```bash
 archetype list
 ```
 
+You will see a summary of known templates similar to this:
+
+```text
+NAME                        VERSION
+go_module                   2.0.1  
+bash_script                 1.0.0  
+ruby_cli_gem                1.0.0  
+```
+
+### Finding Templates
+
+You can search known templates in your template directory using the [`archetype find`](https://docs.biggerconcept.com/app_archetype/commands/find/) command:
+
+```bash
+archetype find --name bash
+```
+
+You will be presented with a list of templates that include the given name:
+
+```text
+NAME                        VERSION
+bash_script                 1.0.0  
+```
+
+### Opening Template Manifest
+
+If you have your `ARCHETYPE_EDITOR` variable set in your environment. You can use the [`archetype open`](https://docs.biggerconcept.com/app_archetype/commands/open/) command to open the manifest in a new editor process (for example `vi`).
+
+Similar to the `archetype find` command, you may provide a name option to choose the manifest:
+
+```bash
+archetype open --name bash_script
+```
+
+### Creating a new Template
+
+The [`archetype new`](https://docs.biggerconcept.com/app_archetype/commands/new/) renders a new blank template into the `ARCHETYPE_TEMPLATE_DIR` location.
+
+Simply run:
+
+```bash
+archetype new
+```
+
+And follow the prompts.
+
+### Deleting an existing template
+
+You can delete a template manifest and its files by running the [`archetype delete`](https://docs.biggerconcept.com/app_archetype/commands/delete/) command. 
+
+```bash
+archetype delete --name bash_script
+```
+
+### Help and configuration
+
+The Gem provides 2 commands to inspect its config. They are:
+
+- [`archetype path`](https://docs.biggerconcept.com/app_archetype/commands/path/) which displays the currently configured `ARCHETYPE_TEMPLATE_DIR`
+- [`archetype version`](https://docs.biggerconcept.com/app_archetype/commands/version/) which displays the current installed gem version
+
+Additionally the [`archetype help`](https://docs.biggerconcept.com/app_archetype/commands/help/) provides more detailed usage information about all of the above mentioned commands.
+
 ## Contributing
 
 See CONTRIBUTING.md for more information

data/app_archetype.gemspec

@@ -17,6 +17,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_dependency 'cli-format', '~> 0.2'
+  spec.add_dependency 'hashie'
   spec.add_dependency 'highline', '~> 2.0'
   spec.add_dependency 'json', '~> 2.3'
   spec.add_dependency 'jsonnet', '~> 0.4.0'
@@ -26,6 +27,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'ostruct', '~> 0.3'
   spec.add_dependency 'ruby-handlebars', '~> 0.4'
   spec.add_dependency 'thor', '~> 1.0'
+  spec.add_dependency 'tty-prompt', '~> 0.23.1'
+  spec.add_dependency 'tty-table', '~> 0.12.0'
 
   spec.add_development_dependency 'bump', '~> 0.9'
   spec.add_development_dependency 'private_gem', '~> 1.1'

data/bin/app_archetype

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+
+lib_path = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib_path) unless $LOAD_PATH.include?(lib_path)
+
+require 'pry'
+require 'app_archetype/cli'
+
+Signal.trap('INT') do
+  warn("\n#{caller.join("\n")}: interrupted")
+  exit(1)
+end
+
+begin
+  AppArchetype::CLI.start
+rescue StandardError => e
+  puts "✖ ERROR: #{e.message}"
+  puts e.backtrace.join("\n")
+  exit 1
+end

data/bin/archetype

@@ -14,7 +14,7 @@ end
 begin
   AppArchetype::CLI.start
 rescue StandardError => e
-  puts "ERROR: #{e.message}"
+  puts "✖ ERROR: #{e.message}"
   puts e.backtrace.join("\n")
   exit 1
 end