kojo 0.3.5 → 0.3.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25c101bd252d7f7193d4d7eddad538945e7d0baaec2e3ee979c68f02616e661f
-  data.tar.gz: 6183debd6556f157f5995f408e61d7634b6474263d54094fce7d9f6a3b440106
+  metadata.gz: 1952c33f6d6360f1a027ee30eefcfea5636a062c2c28c02d83916d99e51ed7c1
+  data.tar.gz: 9554ea0de969c79e11d40b237d4ffb24c3bceead6dc863511124af6b4753841b
 SHA512:
-  metadata.gz: 7c914b9e6cb19e274e23b8dd59b37b06315a8790949cd0f91c09967275381a5dd1305892ed5afdc9d0d51868db284567fe8e6504f0675b6ab7162beb3fec9fc0
-  data.tar.gz: bdb59bc7cf7cd74fedbf791fc4fb297f72e7a9f7bc2b6285f6853ac0d21eed5e32378873ab21935e280e6df2cabaf4993f5f6ccb4d0a8a9f102260012d99346d
+  metadata.gz: 40bdbcfa32871516c1776923dffd3d78b0757463941da85708b4292e9a84f5c8308dd655e1707493e6da9411771a12c18a57d7098ae0d85cc1c537bf41d3fcb7
+  data.tar.gz: 76d43feccd9c0210bd3239f86b089a27527fdbd293daaf771dcb3d8170dd5d57a864e2a7fc399a00b6989d963659eb1e7ea9a7b8e7f23561a288a27e7187d941

data/README.md

@@ -1,9 +1,8 @@
 <div align='center'>
 
-![kojo](images/kojo.png)
+![kojo](support/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)
@@ -11,15 +10,14 @@ Kojo Configuration Ninja
 
 
 Kojo helps you generate configuration files from templates, using variables 
-and definition files.  
-It is a command line utility, and it works on any text file format.
+and definition files. It is a command line utility, and works on any text file
+format.
 
 </div>
 
 ---
 
-Table of Contents
---------------------------------------------------
+## Table of Contents
 
 - [Installation](#installation)
 - [Usage](#usage)
@@ -28,31 +26,36 @@ 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)
+  - [Convert YAML to JSON](#convert-yaml-to-json)
+  - [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)
+![kojo](support/features-vars.svg)
 
 Include variables in your configuration templates by using this syntax: 
 `%{varname}`
@@ -63,11 +66,13 @@ 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`.
 
-
+Note that since the `%` sign is used for variable replacement, if you want
+your generated file to include a literal percent sign, you need to escape it
+as `%%` in your template.
 
 ### Import
 
-![kojo](images/features-import.svg)
+![kojo](support/features-import.svg)
 
 Use the `@import filename` directive anywhere to include another file in the
 resulting configuration file.
@@ -86,22 +91,18 @@ resulting configuration file.
 
 The space after `filename` is optional.
 
-
-
 ### Transform an Entire Folder
 
-![kojo](images/features-dir.svg)
+![kojo](support/features-dir.svg)
 
 Process a folder containing templates and `@imports`, and generate a mirror
 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)
+![kojo](support/features-config.svg)
 
 Using the `kojo config` command together with a simple definitions file, you
 can:
@@ -146,7 +147,7 @@ output:
 
 ### Transform One to Many using Front Matter
 
-![kojo](images/features-single.svg)
+![kojo](support/features-single.svg)
 
 Define a template that contains the instructions on how to transform it as a
 YAML front matter.
@@ -154,7 +155,7 @@ YAML front matter.
 The YAML front matter should be structured like this:
 
 ```yaml
-filename2:
+filename1:
   arg: value
   another_arg: value
 
@@ -169,9 +170,36 @@ Your template that uses %{arg} goes here
 Additional arguments provided to the command line, will also be transferred
 to the template.
 
+### Convert YAML to JSON
+
+![kojo](support/features-tojson.svg)
+
+Convert one or more YAML files to JSON.
+
+This can be useful when you require JSON files as output, but wish to edit
+(or generate using Kojo) using the less error-prone and more aesthetically
+pleasing YAML format.
+
+Note that this Kojo command does not provide any additional preprocessing - the
+input files should be valid YAML.
+
+### Interactive Form Templates
+
+![kojo](support/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](support/features-form-inline.svg)
+
 ### Conditions and Loops with ERB
 
-![kojo](images/features-erb.svg)
+![kojo](support/features-erb.svg)
 
 Template files are evaluated using ERB, so you can use any Ruby code for more
 advanced templates (for conditions, loops etc.).
@@ -182,15 +210,12 @@ 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.
 
-![kojo](images/interactive-mode.gif)
+![kojo](support/interactive-mode.gif)
 
 You can enable or disable interactive mode by setting the environment
 variable `KOJO_INTERACTIVE` to `yes` or `no`.
@@ -201,21 +226,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 +273,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 +293,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/cli.rb

@@ -15,6 +15,8 @@ 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.route 'tojson', to: Kojo::Commands::ToJsonCmd
 
       runner
     end

data/lib/kojo/commands/command_base.rb

@@ -4,9 +4,8 @@ module Kojo
   module Commands
     class CommandBase < MisterBin::Command
       def save(file, output)
-        outpath = "#{outdir}/#{file}"
-        File.deep_write outpath, output
-        say "Saved #{outpath}"  
+        File.deep_write file, output
+        say "Saved #{file}"
       end
     end
   end

data/lib/kojo/commands/config.rb

@@ -3,7 +3,7 @@ require 'mister_bin'
 
 module Kojo::Commands
   # Handle calls to the +kojo config+ command
-  class ConfigCmd < MisterBin::Command
+  class ConfigCmd < CommandBase
     using Kojo::Refinements
 
     attr_reader :gen, :outdir, :opts, :import_base, :config_file
@@ -33,7 +33,7 @@ module Kojo::Commands
       argfile = args['--args']
 
       if argfile
-        fileopts = YAML.load_file(argfile).symbolize_keys
+        fileopts = YAML.properly_load_file(argfile).symbolize_keys
         @opts = fileopts.merge opts
       end
 
@@ -59,13 +59,5 @@ module Kojo::Commands
         say output
       end
     end
-
-    def save(path, output)
-      dir = File.dirname path
-      FileUtils.mkdir_p dir unless Dir.exist? dir
-      File.write path, output
-      say "Saved #{path}"
-    end
-
   end
 end

data/lib/kojo/commands/dir.rb

@@ -33,7 +33,7 @@ module Kojo
         argfile = args['--args']
 
         if argfile
-          fileopts = YAML.load_file(argfile).symbolize_keys
+          fileopts = YAML.properly_load_file(argfile).symbolize_keys
           @opts = fileopts.merge @opts
         end
 
@@ -62,7 +62,7 @@ module Kojo
 
       def write(collection)
         collection.render @opts do |file, output|
-          save file, output
+          save "#{outdir}/#{file}", output
         end
       end
     end

data/lib/kojo/commands/file.rb

@@ -3,7 +3,7 @@ require 'mister_bin'
 module Kojo
   module Commands
     # Handle calls to the +kojo file+ command
-    class FileCmd < MisterBin::Command
+    class FileCmd < CommandBase
       using Kojo::Refinements
 
       attr_reader :opts, :outfile, :infile, :import_base
@@ -33,7 +33,7 @@ module Kojo
         argfile = args['--args']
 
         if argfile
-          fileopts = YAML.load_file(argfile).symbolize_keys
+          fileopts = YAML.properly_load_file(argfile).symbolize_keys
           @opts = fileopts.merge opts
         end
 
@@ -48,8 +48,7 @@ module Kojo
         output = template.render(opts)
 
         if outfile
-          File.write outfile, output
-          say "Saved #{outfile}"
+          save outfile, output
         else
           puts output
         end

data/lib/kojo/commands/form.rb

@@ -0,0 +1,35 @@
+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
+          save outfile, template.render
+        else
+          puts template.render 
+        end
+      end
+
+    end
+  end
+end

data/lib/kojo/commands/single.rb

@@ -46,7 +46,7 @@ module Kojo
 
       def write(template)
         template.render opts do |file, output|
-          save file, output
+          save "#{outdir}/#{file}", output
         end
       end
     end

data/lib/kojo/commands/to_json.rb

@@ -0,0 +1,67 @@
+require 'mister_bin'
+
+module Kojo
+  module Commands
+    # Handle calls to the +kojo dir+ command
+    class ToJsonCmd < CommandBase
+      using Kojo::Refinements
+
+      attr_reader :input, :save_files, :replace_files
+
+      help "Convert one or more YAML files to JSON"
+
+      usage "kojo tojson INPUT... [(--save | --replace)]"
+      usage "kojo tojson (-h|--help)"
+
+      option "-s --save", "Save each input file in the same directory"
+      option "-r --replace", "Save each input file in the same directory and delete the input file"
+
+      param "INPUT", "Path to a YAML file or multiple files using a glob pattern"
+
+      example "kojo tojson myfile.yaml"
+      example "kojo tojson myfile.yaml --save"
+      example "kojo tojson indir/*.yaml"
+      example "kojo tojson indir/*.yaml --replace"
+      example "kojo tojson indir/**/*.yml"
+
+      def run
+        @input = get_input_files
+        @save_files = args['--save'] || args['--replace']
+        @replace_files = args['--replace']
+
+        save_files ? write : show
+      end
+
+    private
+
+      def tojson(path)
+        JSON.pretty_generate YAML.properly_load_file(path)
+      end
+
+      # Glob patterns are usually handled by the shell, but in case
+      # we still have '*' in our string (for example, if it was sent
+      # quoted), we will do the globbing ourselves
+      def get_input_files
+        args['INPUT'].map do |path|
+          path.include?('*') ? Dir[path].sort : path
+        end.flatten
+      end
+
+      def show
+        input.each do |infile|
+          outfile = infile.gsub(/\.ya?ml/, '.json')
+          say "\n!txtgrn!# #{outfile}"
+          say tojson(infile)
+        end
+      end
+
+      def write
+        input.each do |infile|
+          outfile = infile.gsub(/\.ya?ml/, '.json')
+          save outfile, tojson(infile)
+          File.delete infile if replace_files
+        end
+      end
+    end
+  end
+end

data/lib/kojo/config.rb

@@ -1,5 +1,3 @@
-require 'yaml'
-
 module Kojo
   # The Config class handles multiple template generation from a 
   # definitions YAML file.
@@ -61,7 +59,7 @@ module Kojo
     end
 
     def config
-      @config ||= YAML.load_file config_file
+      @config ||= YAML.properly_load_file config_file
     end
   end
 

data/lib/kojo/extensions/yaml.rb

@@ -0,0 +1,10 @@
+require 'yaml'
+
+module YAML
+  # ref: https://bugs.ruby-lang.org/issues/17866
+  def self.properly_load_file(path)
+    YAML.load_file path, aliases: true
+  rescue ArgumentError
+    YAML.load_file path
+  end
+end

data/lib/kojo/form.rb

@@ -0,0 +1,60 @@
+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, **kargs, &block)
+      if respond_to? method_name
+        prompt.send method_name, *args, **kargs, &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/front_matter_template.rb

@@ -1,5 +1,3 @@
-require 'yaml'
-
 module Kojo
   # The FrontMatterTemplate class handles a single template file, that 
   # contains a YAML front matter.
@@ -34,7 +32,7 @@ module Kojo
     def read_file(file)
       raise Kojo::NotFoundError, "File not found: #{file}" unless File.exist? file
 
-      config = YAML.load_file file
+      config = YAML.properly_load_file file
       content = File.read(file)[/^---\s*$\n(.*)/m, 1]
 
       [config, content]

data/lib/kojo/refinements/string.rb

@@ -57,7 +57,7 @@ module Kojo
       end
 
       def erb(template, vars)
-        ERB.new(template, nil, '-').result(OpenStruct.new(vars).instance_eval { binding })
+        ERB.new(template, trim_mode: '-').result(OpenStruct.new(vars).instance_eval { binding })
       end
 
     end

data/lib/kojo/version.rb

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

data/lib/kojo.rb

@@ -1,14 +1,18 @@
 require 'requires'
 require 'byebug' if ENV['BYEBUG']
 
-requires 'kojo/refinements'
+require 'yaml'
+require 'json'
+
 requires 'kojo/extensions'
+requires 'kojo/refinements'
 
 require 'kojo/exceptions'
 require 'kojo/template'
 require 'kojo/collection'
 require 'kojo/config'
 require 'kojo/front_matter_template'
+require 'kojo/form'
 
 module Kojo
   class << self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kojo
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.3.9
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-02-13 00:00:00.000000000 Z
+date: 2022-02-22 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,14 @@ 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/commands/to_json.rb
 - lib/kojo/config.rb
 - lib/kojo/exceptions.rb
 - lib/kojo/extensions/file.rb
+- lib/kojo/extensions/yaml.rb
+- lib/kojo/form.rb
 - lib/kojo/front_matter_template.rb
 - lib/kojo/refinements/array.rb
 - lib/kojo/refinements/hash.rb
@@ -91,14 +123,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.2.15
 signing_key: 
 specification_version: 4
 summary: Configuration Ninja