Stimulate your development! Quicken is a command line tool to generate software project based on clear, repeatable recipes.

Quicken is a software project scaffolder written in Ruby. It allows to create projects based on a recipe that defines steps necessary to create and configure new projects. It is based on an extensible plugin architecture that allows anyone to write custom generators based on their needs. See Plugins for more informations

• Installation
• Usage
• Recipes
  • Example
• Plugins
  • Install Plugins
  • Write New Plugins
  • Helpers
  • Distribute Plugins
• Development
• Contributing
• Code of Conduct
• Attributions

Install it via RubyGems

$ gem install quicken-ruby

Upon installing the qk executable will be available in your command line. Run qk help to see a list of all available commands and flags.

The most important ones are:

• qk init Initialize a new recipe.yml file in the current directory with a base template.
  Pass the -e flag to create an empty file

• qk init plugin [NAME] Initialize a new project for a Quicken plugin in a new directory called quicken-NAME under the current folder.

• qk create Create a new project in the current directory using the default recipe file, which is looked for in the directory itself as recipe.yml.
  Specify a custom file by passing its path to the -f flag (supports both local files and remote ones via HTTP/HTTPS, so you can host your recipe files on something GitHub Gist and pass the raw file URL).

Recipe files are YAML files defined as a list of steps, which will be executed sequentially in the order they are defined.
Steps are identified by the corresponding plugin name and optional arguments defined by the plugin itself.

- echo: This is an example recipe

- readme:
    project_name: Quicken
    author_name: Matteo Joliveau
    author_email: matteojoliveau@gmail.com
    description: This is a test project generated by Quicken!
    
- echo: I will run after the readme plugin

Plugins are the core of Quicken. They implement the actual scaffolding logic and allow for extensions to be quickly written.

Plugins are packaged as Ruby gems under the name quicken-PLUGINNAME, for example quicken-git. Installing a new project is as simple as running gem install quicken-git.

Plugins consist in a plain Ruby class implementing initialize(args), where args is an hash extracted from the recipe file, and call(). They live under the namespace Quicken::Plugins and must be requirable from quicken/plugins/NAME.

An example of bare minumum Quicken plugin:

module Quicken
  module Plugins
    class MyPlugin
      def initialize args
        @args = args
      end
      
      def call
        puts "Called with args: #{@args}!"
      end
    end
  end
end

Quicken offers a set of classes and modules to ease plugins development. The most useful one is the Quicken::Plugin class, which includes some basic helper methods and defines a standard constructor as:

def initialize args
  @args = args
end

So the above example can be rewritten as:

require 'quicken'

module Quicken
  module Plugins
    class MyPlugin < Quicken::Plugin
      def call
        puts "Called with args: #{@args}!"
      end
    end
  end
end

There are also some helper modules that add convenience methods to run commonly used logic, like prompt the user or access files.
The basic one is Quicken::Helpers::Base, which is automatically included by extending the Plugin class and offers many useful methods taken from Thor::Shell::Basic, like say or ask.

require 'quicken'

module Quicken
  module Plugins
    class MyPlugin < Quicken::Plugin
      def call
        color = ask 'What is your favourite color?', default: 'blue'
        say "I like #{color} too!"
      end
    end
  end
end

If your plugin needs to work with files, include Quicken::Helpers::File.

require 'quicken'

module Quicken
  module Plugins
    class MyPlugin < Quicken::Plugin
      include Quicken::Helpers::File
      
      def initialize args
        @path = args[:path]
      end
      
      def call
        @file = read_file @path
        say "The file contains: #{@file}"
        
        outcome = write_file 'hello.txt', 'Hello!'
        if outcome == :file_exists
          say 'README already present. Skipping...'
        else
          say 'Created hello.txt file!'
        end
      end
    end
  end
end

Quicken::Helpers::Template provides methods to work with ERB templates, like parse to parse template strings, and compile to generate the final value from variables.
This is how the readme plugins generates new README.md files.

require 'quicken'

module Quicken
  module Plugins
    class Readme < Quicken::Plugin
      include Quicken::Helpers::File
      include Quicken::Helpers::Template

      def initialize args
        @template = args.delete(:template)
        @variables = args
        parse template
      end

      def call
        result = compile @variables
        outcome = write_file 'README.md', result
        if outcome == :file_exists
          say 'README already present. Skipping...'
        else
          say 'Created README file'
        end
      end

      private

      def template
        @template ||= DEFAULT
      end

      DEFAULT = <<~ERB
        # <%= project_name %>
        ### by <%= author_name %> <<%= author_email %>>
        ---
        <%= description %>
      ERB
    end
  end
end

Plugins must be packaged as Ruby gems under the name quicken-PLUGINNAME, for example quicken-git. The main entry point must be located under lib/quicken/plugins. This is an example of plugins folder structure:

.
├── Gemfile
├── Gemfile.lock
├── LICENSE
├── README.md
├── Rakefile
├── bin
│   ├── console
│   └── setup
├── lib
│   └── quicken
│       ├── git
│       │   └── version.rb
│       ├── plugins
│       │   └── git.rb
│       └── git.rb
└── quicken-git.gemspec

This repo uses the Git Flow paradigm to organize and manage branches. Please refer to this cheatsheet for more informations.

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/quicken-rb/quicken. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Everyone interacting in the Quicken project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Logo made by srip from www.flaticon.com is licensed by CC 3.0 BY