kojo 0.3.5 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25c101bd252d7f7193d4d7eddad538945e7d0baaec2e3ee979c68f02616e661f
-  data.tar.gz: 6183debd6556f157f5995f408e61d7634b6474263d54094fce7d9f6a3b440106
+  metadata.gz: 39cdf289cbe0c64d4344cbe494922c1b377f940da377b74367227de926679c62
+  data.tar.gz: 062efc5aaa4e6bae3dbc3bc9adefd3e8b8a2f6b76e088a8b6ca5ba4c536a131e
 SHA512:
-  metadata.gz: 7c914b9e6cb19e274e23b8dd59b37b06315a8790949cd0f91c09967275381a5dd1305892ed5afdc9d0d51868db284567fe8e6504f0675b6ab7162beb3fec9fc0
-  data.tar.gz: bdb59bc7cf7cd74fedbf791fc4fb297f72e7a9f7bc2b6285f6853ac0d21eed5e32378873ab21935e280e6df2cabaf4993f5f6ccb4d0a8a9f102260012d99346d
+  metadata.gz: 2c88d0578808aff72c649bdcfc9a0919fcfd29179793d08ae617d10f44b61d82df8dff86d2745defe6b079ebce958210158d89aa4d62a27ff495e42c7ef2c834
+  data.tar.gz: 39392b24f84d4e62df6e2b4278b2363e41eb61fb453a651b15ecbc23af96a72e78feef478b628e184ffc3068374db5ed64917a1c47f2560b784e9404dda72b0c

data/README.md

@@ -2,8 +2,7 @@
 
 ![kojo](images/kojo.png)
 
-Kojo Configuration Ninja
-==================================================
+# Kojo Configuration Ninja
 
 [![Gem Version](https://badge.fury.io/rb/kojo.svg)](https://badge.fury.io/rb/kojo)
 [![Build Status](https://github.com/DannyBen/kojo/workflows/Test/badge.svg)](https://github.com/DannyBen/kojo/actions?query=workflow%3ATest)
@@ -18,8 +17,7 @@ It is a command line utility, and it works on any text file format.
 
 ---
 
-Table of Contents
---------------------------------------------------
+## Table of Contents
 
 - [Installation](#installation)
 - [Usage](#usage)
@@ -28,28 +26,32 @@ Table of Contents
   - [Transform an Entire Folder](#transform-an-entire-folder)
   - [Transform One to Many using Config](#transform-one-to-many-using-config)
   - [Transform One to Many using Front Matter](#transform-one-to-many-using-front-matter)
+  - [Interactive Form Templates](#interactive-form-templates)
   - [Conditions and Loops with ERB](#conditions-and-loops-with-erb)
-- [Interactive Mode](#interactive-mode)
+- [Interactive Fallback](#interactive-fallback)
 - [Using from Ruby Code](#using-from-ruby-code)
 - [Contributing / Support](#contributing--support)
 
 ---
 
-Installation
---------------------------------------------------
+## Installation
 
-    $ gem install kojo
+```shell
+$ gem install kojo
+```
 
+Or with Docker:
 
+```shell
+$ alias kojo='docker run --rm -it -v $PWD:/app dannyben/kojo'
+```
 
-Usage
---------------------------------------------------
+## Usage
 
 If you prefer to learn by example, see the [examples](examples#examples) folder for 
 several use cases. Each example subfolder contains the command to run, the 
 relevant files, and the expected output.
 
-
 ### Variables
 
 ![kojo](images/features-vars.svg)
@@ -63,8 +65,6 @@ Include variables in your configuration templates by using this syntax:
 - Variables from the top level will be forwarded downstream, and aggregated 
   with any additional variables that are defined in subsequent `@imports`.
 
-
-
 ### Import
 
 ![kojo](images/features-import.svg)
@@ -86,8 +86,6 @@ resulting configuration file.
 
 The space after `filename` is optional.
 
-
-
 ### Transform an Entire Folder
 
 ![kojo](images/features-dir.svg)
@@ -97,8 +95,6 @@ output folder, with all the variables and `@imports` evaluated.
 
 You may use `%{variables}` in filenames.
 
-
-
 ### Transform One to Many using Config
 
 ![kojo](images/features-config.svg)
@@ -169,6 +165,20 @@ Your template that uses %{arg} goes here
 Additional arguments provided to the command line, will also be transferred
 to the template.
 
+### Interactive Form Templates
+
+![kojo](images/features-form.svg)
+
+Using the `kojo form` command lets you define an ERB or [ERBX][erbx] template, and include interactive prompts to enter the input. 
+
+1. Use either ERB tags (`<%= %>`, `<%- -%>`) or ERBX tags (`{{ }}`, `(( ))`).
+2. Use the built in `prompt` object, which is a [TTY::Prompt](tty-prompt) instance, to prompt for input when running the command (for example: `{{ prompt.ask? "Your Name?" }}`)
+3. Any unidentified ruby command will be forwarded to the `prompt` object, so `prompt.ask` is the same as just using `ask`.
+4. If there is a file with the same name as the template, and with an `.rb` extension (for example `form.md` and `form.md.rb`), then the ruby file will be loaded into the ERB template as if it was written inside it.
+5. If you prefer using a single template file (without the ruby appendix), you can simply use regular ERB/ERBX tags, like demonstrated below.
+
+![kojo](images/features-form-inline.svg)
+
 ### Conditions and Loops with ERB
 
 ![kojo](images/features-erb.svg)
@@ -182,10 +192,7 @@ Use this syntax for ruby code:
 <%- ruby code here -%>     # for code that should not be printed
 <%= ruby code here -%>     # for code that should be printed
 ```
-
-
-Interactive Mode
---------------------------------------------------
+## Interactive Fallback
 
 When Kojo encounters a variable that was not supplied (either through the command 
 line or through a configuration file), it will prompt for a value.
@@ -201,21 +208,20 @@ running from within Ruby code.
 When running from within Ruby code, you can also use `Kojo.interactive = true`
 and `Kojo.interactive?` to get the current state.
 
-
-Using from Ruby Code
---------------------------------------------------
+## Using from Ruby Code
 
 Although Kojo was primarily designed as a command line utility, you can also
 use it as a library from your Ruby code.
 
 These are the primary classes:
 
-| Class                       | Description                                  | CLI equivalent
-|-----------------------------|----------------------------------------------|---------------
-| `Kojo::Template`            | generate from a single template              | `kojo file`
-| `Kojo::FrontMatterTemplate` | generate from a template with a front matter | `kojo single`
-| `Kojo::Config`              | generate from a config file                  | `kojo config`
-| `Kojo::Collection`          | generate from a directory                    | `kojo dir`
+| Class                       | Description                                  | CLI equivalent |
+| --------------------------- | -------------------------------------------- | -------------- |
+| `Kojo::Template`            | generate from a single template              | `kojo file`    |
+| `Kojo::FrontMatterTemplate` | generate from a template with a front matter | `kojo single`  |
+| `Kojo::Config`              | generate from a config file                  | `kojo config`  |
+| `Kojo::Collection`          | generate from a directory                    | `kojo dir`     |
+| `Kojo::Form`                | generate interactively                       | `kojo form`    |
 
 ### Examples
 
@@ -249,6 +255,10 @@ params = { version: '0.1.1' }
 template.render params do |path, content|
   # code to handle results here
 end
+
+# Form
+template = Kojo::Form.new 'examples/form/movie.md'
+puts template.render
 ```
 
 In addition, Kojo extends Ruby's `File` class with the `File.deep_write`
@@ -265,12 +275,13 @@ config.generate do |path, content|
 end
 ```
 
-Contributing / Support
---------------------------------------------------
+## Contributing / Support
 
 If you experience any issue, have a question or a suggestion, or if you wish
 to contribute, feel free to [open an issue][issues].
 
 ---
 
-[issues]: https://github.com/DannyBen/kojo/issues
+[issues]: https://github.com/DannyBen/kojo/issues
+[erbx]: https://github.com/DannyBen/erbx
+[tty-prompt]: https://github.com/piotrmurach/tty-prompt#contents

data/lib/kojo.rb

@@ -9,6 +9,7 @@ require 'kojo/template'
 require 'kojo/collection'
 require 'kojo/config'
 require 'kojo/front_matter_template'
+require 'kojo/form'
 
 module Kojo
   class << self

data/lib/kojo/cli.rb

@@ -15,6 +15,7 @@ module Kojo
       runner.route 'dir',    to: Kojo::Commands::DirCmd
       runner.route 'config', to: Kojo::Commands::ConfigCmd
       runner.route 'single', to: Kojo::Commands::SingleCmd
+      runner.route 'form',   to: Kojo::Commands::FormCmd
 
       runner
     end

data/lib/kojo/commands/form.rb

@@ -0,0 +1,36 @@
+require 'mister_bin'
+
+module Kojo
+  module Commands
+    # Handle calls to the +kojo form+ command
+    class FormCmd < CommandBase
+      attr_reader :infile, :outdir
+
+      help "Fill a template form interactively"
+
+      usage "kojo form INFILE [--save FILE]"
+      usage "kojo form (-h|--help)"
+
+      option "-s --save FILE", "Save to file instead of printing"
+
+      param "INFILE", "ERBX template to transform"
+
+      example "kojo form report.md"
+      example "kojo form report.md --save output.md"
+
+      def run
+        infile = args['INFILE']
+        outfile = args['--save']
+        template = Kojo::Form.new infile
+        
+        if outfile
+          File.deep_write outfile, template.render
+          say "Saved #{outfile}"  
+        else
+          puts template.render 
+        end
+      end
+
+    end
+  end
+end

data/lib/kojo/form.rb

@@ -0,0 +1,61 @@
+require 'erbx'
+require 'tty-prompt'
+
+module Kojo
+  # The Form class handles interactive ERBX templates
+  class Form
+    attr_reader :file
+
+    def initialize(file)
+      @file = file
+    end
+
+    def content
+      @content ||= content!
+    end
+
+    def content!
+      content = File.read file
+      ruby_code = File.exist?("#{file}.rb") ? File.read("#{file}.rb") : nil
+      content = "<%-\n#{ruby_code}\n-%>\n#{content}" if ruby_code
+      content
+    end
+
+    def render
+      ERBX.new(content).result(binding)
+    rescue TTY::Reader::InputInterrupt
+      # :nocov:
+      raise Kojo::Interrupt
+      # :nocov:
+    end
+
+    def prompt
+      @prompt ||= TTY::Prompt.new
+    end
+
+    def method_missing(method_name, *args, &block)
+      if respond_to? method_name
+        prompt.send method_name, *args, *block
+      else
+        super
+      end
+    end
+
+    def respond_to?(method_name, include_private = false)
+      prompt.respond_to?(method_name) || super
+    end
+
+    # Below are TTY::Prompt functions that are not captured by the 
+    # `mthod_missing`, so we specify them explicitly
+
+    def select(*args, &block)
+      prompt.select *args, &block
+    end
+
+    def warn(*args, &block)
+      prompt.warn *args, &block
+    end
+
+
+  end
+end

data/lib/kojo/version.rb

@@ -1,3 +1,3 @@
 module Kojo
-  VERSION = "0.3.5"
+  VERSION = "0.3.6"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kojo
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.3.6
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-02-13 00:00:00.000000000 Z
+date: 2020-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mister_bin
@@ -52,6 +52,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: tty-prompt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: erbx
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.1
 description: Generate configuration files from templates, using variables and definition
   files.
 email: db@dannyben.com
@@ -69,10 +97,12 @@ files:
 - lib/kojo/commands/config.rb
 - lib/kojo/commands/dir.rb
 - lib/kojo/commands/file.rb
+- lib/kojo/commands/form.rb
 - lib/kojo/commands/single.rb
 - lib/kojo/config.rb
 - lib/kojo/exceptions.rb
 - lib/kojo/extensions/file.rb
+- lib/kojo/form.rb
 - lib/kojo/front_matter_template.rb
 - lib/kojo/refinements/array.rb
 - lib/kojo/refinements/hash.rb