kojo 0.0.1 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dcf75263bba96888bad2f8988215d0c20f911ed331a560aa5eb544ee029e0d9
-  data.tar.gz: 4a56066e3bead9aed02ce0140d011c7f678dceb6406cda08d81defc517fbe65a
+  metadata.gz: c58d14e183cbe6bbad4dc235351722f1fc8da21c04ccdba6df2a4e31e3c8afd7
+  data.tar.gz: dd80f41a56a7ee19c7dd4d3d66f3683607e071217c5177a6089c99bf9d256983
 SHA512:
-  metadata.gz: 5124c69508ed6730bf07d280ea0d31db15ceed65cb2fa45965e89c2a759b6aa001327509839ddc9d7cf3ae285230a55a9ad3ed68648caaa87d90711bfaffa556
-  data.tar.gz: 30ab1f2f3d98f5e8cf26b78f07e67765671af5d18fcf50c0a923be09be0dd3928e69592ca8843cc28167bd0044999fa63ad61a15e6c690388ec4f6cde1fc7743
+  metadata.gz: e0035c2e9229b9d5abe09ce695c12aac1a6591242bb516379aede669fce7319fd4c74a000cf40410cb9edbf86855644e11b3c09fe299a4bd466d693a464eb772
+  data.tar.gz: f87db6ee6fddc7efce65cba34e5d6513f6c4a553c1c417a03c7ec7119df2fa0e0e57133ee761ac277381ca1c4144c66f9a615e8edb05122b3da3885319fc58cf

data/README.md

@@ -1,16 +1,20 @@
-![kojo](kojo.png)
+<div align='center'>
+
+![kojo](images/kojo.png)
 
 Kojo - Configuration Ninja
 ==================================================
 
-[![Gem](https://img.shields.io/gem/v/kojo.svg?style=flat-square)](https://rubygems.org/gems/kojo)
-[![Build](https://img.shields.io/travis/DannyBen/kojo.svg?style=flat-square)](https://travis-ci.org/DannyBen/kojo)
-[![Maintainability](https://img.shields.io/codeclimate/maintainability/DannyBen/kojo.svg?style=flat-square)](https://codeclimate.com/github/DannyBen/kojo)
-[![Issues](https://img.shields.io/codeclimate/issues/github/DannyBen/kojo.svg?style=flat-square)](https://codeclimate.com/github/DannyBen/kojo)
+[![Gem Version](https://badge.fury.io/rb/kojo.svg)](https://badge.fury.io/rb/kojo)
+[![Build Status](https://travis-ci.com/DannyBen/kojo.svg?branch=master)](https://travis-ci.com/DannyBen/kojo)
+[![Maintainability](https://api.codeclimate.com/v1/badges/f24566ad04b5054a2251/maintainability)](https://codeclimate.com/github/DannyBen/kojo/maintainability)
 
----
 
+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.
 
+</div>
 
 ---
 
@@ -24,4 +28,76 @@ Installation
 Usage
 --------------------------------------------------
 
-TODO
+If you prefer to learn by example, see the [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)
+
+Include variables in your configuration templates using this syntax:
+
+```ruby
+%{varname}
+```
+
+- Variables can be provided through the command line, or when using `@import`.
+- 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)
+
+Use the `@import filename` directive anywhere to include another file in the
+resulting configuration file.
+
+- The `@import` directive should be the only thing in the line.
+- The indentation will be respected when importing.
+- The `filename` parameter does not have to include an extension - Kojo will
+  use the same extension as the parent file.
+- The included file will be searched for relative to the file it is included 
+  in.
+- Arguments can be passed down to the included template by using this syntax:
+
+```ruby
+@import filename (arg: "value", arg2: "value")
+```
+
+The space after `filename` is optional.
+
+
+### One to Many Generation
+
+![kojo](images/features-config.svg)
+
+In order to generate several configuration files that are based on the same 
+template, you should:
+
+1. Create the configuration template, using `%{variables}` and `@imports` 
+   where appropriate.
+2. Create a configuration YAML file using this syntax:
+
+```yaml
+input: base-template.yml
+
+output:
+  outfile1.yml:
+    argument1: value
+    argument2: value
+
+  outfile2.yml:
+    argument1: value
+    argument2: value
+```
+
+
+### Compile an Entire Folder
+
+![kojo](images/features-compile.svg)
+
+Process a folder containing templates and `@imports`, and generate a mirror
+output folder, with all the variables and `@imports` evaluated.

data/bin/kojo-compile.rb

@@ -0,0 +1,45 @@
+require 'kojo'
+
+help "Compile a folder of templates to a similar output folder"
+
+usage "kojo compile INDIR [--save DIR --import DIR] [ARGS...]"
+usage "kojo compile (-h|--help)"
+
+option "-s --save DIR", "Save output to directory instead of printing"
+option "-i --import DIR", "Specify base directory for @import directives"
+
+param "ARGS", "Optional key=value pairs"
+
+example "kojo compile indir"
+example "kojo compile in --save out env=production"
+example "kojo compile in --save out --import snippets env=production"
+
+action do |args|
+  opts = args['ARGS'].args_to_hash
+  indir = args['INDIR']
+  outdir = args['--save']
+  import_base = args['--import']
+
+  files = Dir["#{indir}/**/*"].reject { |file| File.directory? file }
+
+  files.each do |file|
+    template = Kojo::Template.new(file, opts)
+    template.import_base = import_base if import_base
+    output = template.render
+
+    if outdir
+      outpath = file.sub(/#{indir}/, outdir)
+      
+      dir = File.dirname outpath
+      FileUtils.mkdir_p dir unless Dir.exist? dir
+
+      File.write outpath, output
+      say "Saved #{outpath}"  
+    else
+      outpath = file.sub(/#{indir}/, '')
+      say "\n!txtgrn!# #{outpath}"
+      say output
+    end
+  end
+end
+

data/bin/kojo-run.rb

@@ -18,18 +18,19 @@ action do |args|
   gen = Kojo::Generator.new args['CONFIG']
   outdir = args['--save']
   
-  if outdir
-    FileUtils.mkdir_p outdir unless Dir.exist? outdir
+  if outdir and !Dir.exist? outdir
+    FileUtils.mkdir_p outdir
+  end
 
-    gen.generate do |file, output|
-      path = "#{outdir}/#{file}"
+  gen.generate do |file, output|
+    path = "#{outdir}/#{file}"
+    if outdir
       File.write path, output
       say "Saved #{path}"
+    else
+      say "\n!txtgrn!# #{file}"
+      say output
     end
-  
-  else
-    puts gen.generate
-  
   end
 end
 

data/lib/kojo/generator.rb

@@ -12,18 +12,10 @@ module Kojo
       base_dir = File.dirname config_file
       infile = "#{base_dir}/#{config['input']}"
 
-      result = []
-
       config['output'].each do |outfile, opts|      
         output = render infile, opts.symbolize_keys
-        if block_given?
-          yield outfile, output
-        else
-          result << "\n# #{outfile}\n#{output}"
-        end
+        yield outfile, output
       end
-
-      result.empty? ? nil : result.join("\n")
     end
     
     private

data/lib/kojo/template.rb

@@ -1,12 +1,14 @@
 module Kojo
   class Template
     attr_reader :file, :extension, :args, :dir
+    attr_accessor :import_base
 
     def initialize(file, args={})
       @file = file
       @args = args
       @extension = file[/(\..*)$/]
       @dir = File.dirname file
+      @import_base = dir
     end
 
     def render
@@ -15,8 +17,10 @@ module Kojo
 
     private
 
-    def import(file, args={})
-      self.class.new("#{dir}/#{file}#{extension}", args).render
+    def import(file, import_args={})
+      filename = File.expand_path "#{file}#{extension}", import_base
+      all_args = args.merge import_args
+      self.class.new(filename, all_args).render
     end
 
     def evaluate(file, args={})

data/lib/kojo/version.rb

@@ -1,3 +1,3 @@
 module Kojo
-  VERSION = "0.0.1"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kojo
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.1
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-02 00:00:00.000000000 Z
+date: 2018-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mister_bin
@@ -108,10 +108,12 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.15'
-description: Configuration wizard
+description: Generate configuration files from templates, using variables and definition
+  files.
 email: db@dannyben.com
 executables:
 - kojo
+- kojo-compile.rb
 - kojo-generate.rb
 - kojo-run.rb
 extensions: []
@@ -119,6 +121,7 @@ extra_rdoc_files: []
 files:
 - README.md
 - bin/kojo
+- bin/kojo-compile.rb
 - bin/kojo-generate.rb
 - bin/kojo-run.rb
 - lib/kojo.rb
@@ -139,7 +142,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.4.0
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -150,5 +153,5 @@ rubyforge_project:
 rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
-summary: Configuration wizard
+summary: Configuration Ninja
 test_files: []