A command-line utility powered by Cuprum that provides tools and utilities for defining command-line tools.
Cuprum::Cli provides some pre-defined commands for building CLI applications and tools.
The following commands are designed to support testing and continuous integration.
A built-in command to run an RSpec test suite.
bundle exec thor ci:rspec
Similar to the rspec CLI utility, the takes an optional list of file patterns as well as the following options:
:colortrue, forces the terminal output to display in color. If false, disables color output. Defaults to true.:coveragefalse, sets the ENV["COVERAGE"] value to false. Defaults to true.:envENV values to set when running RSpec utility.:format'progress'.:gemfileA built-in command to run each RSpec spec file in an individual process. Useful for identifying missing require statements or other dependencies that would not be surfaced when running the entire test suite.
bundle exec thor ci:rspec_each
Similar to the rspec CLI utility, the takes an optional list of file patterns as well as the following options:
:colortrue, forces the terminal output to display in color. If false, disables color output. Defaults to true.:envENV values to set when running RSpec utility.:gemfileFor users of the Async gem, Cuprum::Cli defines an improved version of the RSpec Each command that can parallelize running the individual tests (but be wary of external dependencies, such as databases).
The following commands are used to generate and manage local files.
A built-in command for generating a new source file or files based on defined templates. Automatically handles intermediate directories and supports multiple file generation (such as spec files or view component templates).
bundle exec thor file:new path/to/file.rb
The file:new command takes one required argument, the path to the generate file, as well as the following options:
:directoriestrue, generates intermediate directories, similar to the -p flag for the mkdir utility. Defaults to true.:dry_runtrue, does not generate the actual file, but outputs to the terminal as normal. Defaults to false.:generators:quiet:verbose--dry-run to preview the file contents.Additionally, the command supports any number of additional options, which are passed to the generator when generating the file or files. Note that if the matching generator does not support a given option, it will respond with an error.
Cuprum::Cli uses generator classes to define the files created by the file:new command.
Each generator defines a pattern or patterns that are used when determining which generator is called for a given request. It also defines a set of output files - these are the files generated when the generator is called. A generator can have multiple outputs, allowing Cuprum::Cli to create multiple files from a single command, such as a source file and the associated spec.
Finally, generators can define additional options that are used when building the contents of the generated files. For example, the Ruby generator allows specifying a --parent-class option, which changes the file contents from creating a new Module to creating a new Class with the specified parent.
Cuprum::Cli defines two built-in generators:
When the file:new command is called, the first step is to find the matching generator for that input path and options. Each generators defines a matching pattern or patterns.
Proc patterns match on both the input path and options. If the proc returns true, that generator is match.Regexp patterns match on the input path. If the regex matches the path, that generator is a match.String patterns match on the input path. If the path ends with the string, that generator is a match.If there is more than one generator that matches the file path and options, the last generator defined is used. This allows overriding default generators, or defining generators for more specific contexts, such as a web application’s model files or controllers.
If there are no matching generators, the file:new command returns with an error.
Each generator defines one or more outputs. When that generator is called, it creates a new file for each of those outputs, using the file path and template defined for that output. For example, the Ruby generator defines one output for the Ruby file and one output for the RSpec file.
Cuprum::Cli automatically extracts a number of properties from the given input path, such as the file name, file extension, and directory path. These properties can be used to customize the output path or the contents of the generated file, along with the options passed by the user to file:new.
For example, for the input path lib/space/rocket.rb and option --parent-class=Vehicle, the Ruby generator creates the following files.
In lib/space/rocket.rb:
# frozen_string_literal: true
require 'space'
module Space
class Rocket < Vehicle
end
end
In spec/space/rocket_spec.rb:
# frozen_string_literal: true
require 'space/rocket'
RSpec.describe Space::Rocket do
pending
end
Some generators allow you to pass a custom template for a specific output, or even disable that output entirely. For example, if you pass the --skip-rspec option to the Ruby template, the generator will not create the RSpec file.