« 25 Days of Ruby Gems - Ruby Advent Calendar 2020, December 1st - December 25th

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

Written by geraldb Gerald Bauer

Let’s start with a quiz:

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

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

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

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?

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:

Compare:

module $module$     | module <%= module %>  | module {{ module }}  | 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?

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

Built with Ruby (running Jekyll) on 2021-03-12 22:04:06 +0000 in 0.371 seconds.
Hosted on GitHub Pages. </> Source on GitHub. (0) Dedicated to the public domain.