:toc: macro
:toclevels: 5
:figure-caption!:

= Rubysmith

[link=http://badge.fury.io/rb/rubysmith]
image::https://badge.fury.io/rb/rubysmith.svg[Gem Version]
[link=https://www.alchemists.io/projects/code_quality]
image::https://img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchemists Style Guide]
[link=https://circleci.com/gh/bkuhlmann/rubysmith]
image::https://circleci.com/gh/bkuhlmann/rubysmith.svg?style=svg[Circle CI Status]

Rubysmith is a command line interface for smithing Ruby projects.

This gem is useful in situations in which you need something more sophisticated than a
link:https://bundler.io/guides/bundler_in_a_single_file_ruby_script.html[Bundler Inline] script but
less complicated than a link:https://www.alchemists.io/projects/gemsmith[Gemsmith] gem. Rubysmith is
the foundation of Gemsmith and provides a lot of the same functionality as Gemsmith but solely
tailored for pure Ruby projects. Again, this is a great tool for spiking quick Ruby implementations,
sharing code snippets with others, or building full blown Ruby projects for collaboration with
others.

toc::[]

== Features

* Builds a Ruby project skeleton for custom design and development.
* Uses link:https://www.alchemists.io/projects/runcom[Runcom] for resource configuration management.
* Uses link:https://www.alchemists.io/projects/pragmater[Pragmater] for Ruby source pragma directives.
* Supports link:https://github.com/amazing-print/amazing_print[Amazing Print].
* Supports link:https://github.com/rubymem/bundler-leak[Bundler Leak].
* Supports link:https://git-scm.com[Git].
* Supports link:https://www.alchemists.io/projects/git-lint[Git Lint].
* Supports link:https://github.com/guard/guard[Guard].
* Supports link:http://pryrepl.org[Pry].
* Supports link:https://github.com/ruby/rake[Rake].
* Supports link:https://github.com/troessner/reek[Reek].
* Supports link:https://www.alchemists.io/projects/refinements[Refinements].
* Supports link:https://rspec.info[RSpec].
* Supports link:https://github.com/rubocop-hq/rubocop[Rubocop].
* Supports link:https://docs.rubocop.org/rubocop-performance[Rubocop Performance].
* Supports link:https://github.com/rubocop-hq/rubocop-rake[Rubocop Rake].
* Supports link:https://github.com/rubocop-hq/rubocop-rspec[Rubocop RSpec].
* Supports link:https://github.com/simplecov-ruby/simplecov[SimpleCov].
* Supports common settings and a structured layout for building projects.
* Provides common documentation:
** README
** CHANGES
** CONTRIBUTING
** CODE OF CONDUCT
** LICENSE

// == Screencasts

// [link=https://www.alchemists.io/screencasts/rubysmith]
// image::https://www.alchemists.io/images/screencasts/rubysmith/cover.svg[Screencast,600,240,role=focal_point]

== Requirements

. A UNIX-based system.
. link:https://www.ruby-lang.org[Ruby].
. link:https://rubygems.org[RubyGems].
. link:https://github.com/bundler/bundler[Bundler].

== Setup

To install, run:

[source,bash]
----
gem install rubysmith
----

== Usage

=== Command Line Interface (CLI)

From the command line, type: `rubysmith --help`

....
USAGE:
  -b, --build NAME [options]               Build new project.
  -c, --config ACTION                      Manage gem configuration: edit or view.
  -h, --help                               Show this message.
  -v, --version                            Show gem version.

BUILD OPTIONS:
  --[no-]amazing_print                 Add Amazing Print.
  --[no-]bundler-leak                  Add Bundler Leak.
  --[no-]console                       Add console script.
  --[no-]documentation                 Add documentation.
  --[no-]git                           Add Git.
  --[no-]git-lint                      Add Git Lint.
  --[no-]guard                         Add Guard.
  --min                                Use minimum/no options.
  --[no-]pry                           Add Pry.
  --[no-]rake                          Add Rake.
  --[no-]reek                          Add Reek.
  --[no-]refinements                   Add Refinements.
  --[no-]rspec                         Add RSpec.
  --[no-]rubocop                       Add Rubocop.
  --[no-]setup                         Add setup script.
  --[no-]simple_cov                    Add SimpleCov.
  --[no-]zeitwerk                      Add Zeitwerk.
....

=== Building

The core functionality of this gem centers around the `--build` command with optional customization
provided via build options. By default, all build options are enabled. Example:

[source,bash]
----
rubysmith --build demo
----

Running the above will generate a new `demo` Ruby project with all options enabled. Should you wish
to disable specific options, you can use the `--no-*` prefix. Example:

[source,bash]
----
rubysmith --build demo --no-pry --no-guard
----

With the above example, both Pry and Guard support would have been disabled when building the `demo`
project. Taking this a step further, you can also use the `--min` option to generate a project with
bare minimum of options. Example:

[source,bash]
----
rubysmith --build demo --min
----

The above is essentially the same as building with _all_ options disabled. This is handy in
situations where you need to quickly script something up for sharing with others yet still want to
avoid using a Bundler Inline script so gem dependencies are not installed each time the code is run.

To have specific options enabled/disabled _every time_ you build a new Ruby project, you can edit
your global configuration for making these settings permanent (see below for details).

=== Configuration

This gem can be configured via a global configuration:

....
$HOME/.config/rubysmith/configuration.yml
....

It can also be configured via link:https://www.alchemists.io/projects/xdg[XDG] environment
variables.

The default configuration is as follows:

[source,yaml]
----
:author:
  :name:
  :email:
  :url:
:documentation:
  :format: "md"
  :license: "mit"
:build:
  :amazing_print: true
  :bundler_leak: true
  :console: true
  :documentation: true
  :git: true
  :git_lint: true
  :guard: true
  :minimum: false
  :pry: true
  :rake: true
  :reek: true
  :refinements: true
  :rspec: true
  :rubocop: true
  :setup: true
  :simple_cov: true
  :zeitwerk: true
:builders:
  :pragmater:
    :comments:
      - "# frozen_string_literal: true"
    :includes:
      - "**/*.rb"
      - "**/*bin/console"
      - "**/*bin/guard"
      - "**/*bin/rubocop"
      - "**/*Gemfile"
      - "**/*Guardfile"
      - "**/*Rakefile"
----

Feel free to take this default configuration, modify, and save as your own custom
`configuration.yml`.

== Development

To contribute, run:

[source,bash]
----
git clone https://github.com/bkuhlmann/rubysmith.git
cd rubysmith
bin/setup
----

You can also use the IRB console for direct access to all objects:

[source,bash]
----
bin/console
----

== Tests

To test, run:

[source,bash]
----
bundle exec rake
----

== Versioning

Read link:https://semver.org[Semantic Versioning] for details. Briefly, it means:

* Major (X.y.z) - Incremented for any backwards incompatible public API changes.
* Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.
* Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.

== Code of Conduct

Please note that this project is released with a link:CODE_OF_CONDUCT.adoc[CODE OF CONDUCT]. By
participating in this project you agree to abide by its terms.

== Contributions

Read link:CONTRIBUTING.adoc[CONTRIBUTING] for details.

== License

Read link:LICENSE.adoc[LICENSE] for details.

== History

Read link:CHANGES.adoc[CHANGES] for details.
Built with link:https://www.alchemists.io/projects/gemsmith[Gemsmith].

== Credits

Engineered by link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].