19-quik.md

Day 19 - quik Gem - Quick Starter Template Script Wizard - The Missing Code Generator and Project Scaffolder for Gems, Sinatra, Jekyll 'n' More

Written by {% avatar geraldb %} Gerald Bauer

Let's start with a quiz:

Q: How do you get started with creating a new gem?

• (A) From zero / scratch ;-)
• (B) Using bundler with $ bundle gem
• (C) Using quik with $ quik new gem
• (D) Using hoe with $ sow (incl. with hoe rake tasks gem)
• (E) Other (Please Tell).

Q: How do you get started with creating a new sinatra app or service?

• (A) From zero / scratch ;-)
• (B) Using padrino with $ padrino g project
• (C) Using quik with $ quik new sinatra
• (D) Other (Please Tell).

Q: How do you get started with creating a new jekyll theme?

• (A) From zero / scratch ;-)
• (B) Using jekyll with $ jekyll new-theme
• (C) Using quik with $ quik new jekyll
• (D) Other (Please Tell).

One quick starter to rule them all?

Let's welcome the quik gem and command line tool.

The idea: Many starter templates / boilerplates are ready-to-fork github repos. Why not turn github repos into quik starter templates?! Let's do it in 1-2-3 steps.

Step 1: Download Single-File Quik Starter (.ZIP) Archive

Did you know? You can download github repos without git? That is, you can download always up-to-date single-file (.ZIP) archives that get (auto-)built and packaged by github using the latest source files (from the master branch).

Let's look inside the gem quik starter archive, that is, gem-starter-template.zip downloaded from quikstart/gem-starter-template/archive/master.zip, for example:

lib/
  $filename$.rb
  $filename$/
    version.rb
test/
  helper.rb
  test_version.rb
.gitignore
HISTORY.md
Manifest.txt
README.md
Rakefile

(Source: quikstart/gem-starter-template)

Step 2: Parameterize Files - Use a Template Language

Let's parametrize the lib/hello/version.rb script for use in a gem template / scaffold, for example:

module Hello

  MAJOR = 0
  MINOR = 0
  PATCH = 1
  VERSION = [MAJOR,MINOR,PATCH].join('.')

  def self.version
    VERSION
  end

  def self.banner
    "hello/#{VERSION} on Ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) [#{RUBY_PLATFORM}]"
  end

end  # module Hello

Q: What template language would you choose?

• (A) Embedded Ruby (ERB)
• (B) Liquid
• (C) Other (Please Tell).

Yes, let's use a new (simpler) template language (e.g. $name$)!

Let's lookt at the parametrized lib/$filename$/version.rb script from the gem quick starter:

module $module$

  MAJOR = 0
  MINOR = 0
  PATCH = 1
  VERSION = [MAJOR,MINOR,PATCH].join('.')

  def self.version
    VERSION
  end

  def self.banner
    "$name$/#{VERSION} on Ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) [#{RUBY_PLATFORM}]"
  end

end  # module $module$

(Source: quikstart/gem-starter-template/template/lib/$filename$/version.rb)

Why not (re)use Embedded Ruby (ERB) or Liquid? A new meta template template language is:

• Simpler -- works inside filenames too ;-) e.g. lib/$filename$/version.rb
• Shorter -- less typing (plus: no worries about whitespace)

Compare:

module $module$     | module <%= module %>  | module {%raw%}{{ module }}{%endraw%}  | module Hello
  ...               |  ...                  |   ...                |   ...
end                 | end                   | end                  | end

And most important - a new meta template template language is "orthogonal" to Embedded Ruby (ERB) and Liquid. It let's you parameterize Embedded Ruby (ERB) or Liquid templates too - no need for escaping or "raw" blocks etc.

Step 3: What's Missing? All together Now - Automate with a Script

Q: What script language would you choose?

• (A) Ruby
• (B) Python
• (C) JavaScript
• (D) Other (Please Tell).

Let's use Ruby ;-) with a new wizard mini language, that is, a domain-specific language (DSL).

Example - gem-starter-template/quik.rb:

say "Hello from the gem quick starter wizard script"

name  = ask "Name of the gem", "hola"

def make_module( name )
   ...
end

module_name = ask "Module name of the gem", make_module( name )


## use template repo e.g. github.com/quikstart/gem-starter-template

use "quikstart/gem-starter-template"

config do |c|
  c.name     = name
  c.filename = name     ## for now assume name is 1:1 used as filename
  c.module   = module_name

  c.date     = Time.new.strftime("%Y-%m-%d")  ## e.g. use like $date$  => 2015-08-27
end

(Source: quikstart/gem-starter-template/quik.rb)

Voila. That's it.

Appendix: quik help - Quik Starter Commands

$ quik --help      # or
$ qk -h

Resulting in:

NAME
    qk/quik - ruby quick starter template script wizard .:. the missing code generator

SYNOPSIS
    quik [global options] command [command options] [arguments...]

VERSION
    1.0.0

GLOBAL OPTIONS
    --help            - Show this message
    --verbose         - (Debug) Show debug messages
    --version         - Display the program version

COMMANDS
    list, ls, l - List ruby quick starter scripts
    new, n      - Run ruby quick starter script

    help        - Shows a list of commands or help for one command

quik ls - List Quik Starter Wizards

Use:

$ quik list    # or
$ quik ls      # or
$ quik l       # or
$ qk l

Resulting in:

  1..gem        .:.  Gem Quick Starter Template
  2..gem-hoe    .:.  Gem Quick Starter Template (Hoe Classic Edition)
  3..sinatra    .:.  Sinatra Quick Starter Template
...

quik new - New Wizard Quik Start

To run a quick starter template wizard script to download and install (unzip/unpack) a template archive and configure the code ready-to-use. Try:

$ quik new gem    # or
$ quik n gem      # or
$ qk n gem

This will download the quik wizard script (quik.rb ) from the gem starter template repo and run through all steps e.g.:

Welcome, to the gem quick starter script.

Q: What's your gem's name? [hola]:   hello
Q: What's your gem's module? [Hola]: Hello

Thanks! Ready-to-go. Stand back.

  Downloading Gem Starter Template...
  Setting up Gem Starter Template...
  ...
Done.

That's it. Now the gem starter code is ready in the hello folder.

Find Out More

References

• Home :: github.com/quikstart/quik
• Gem :: quik
• Docs :: quik