Loci

Appearance

Helpers ​

Helpers are methods available inside generator steps for manipulating files, rendering templates, running commands, and modifying Ruby source code.

All helpers are automatically included in every generator. They integrate with the tracer for output logging and respect --dry-run and --reverse flags.

File Operations ​

create_file ​

Creates a file with the given content. Accepts a block as an alternative to the content argument.

ruby
create_file "app/models/user.rb", <<~RUBY
  class User
  end
RUBY
ruby
create_file "config/settings.yml" do
  "timeout: 30\nretries: 3\n"
end

In reverse mode, create_file removes the file instead.

remove_file ​

Deletes a file. Skipped in reverse mode (already destructive).

ruby
remove_file "tmp/old_config.yml"

copy_file ​

Copies a file from source to destination. In reverse mode, removes the destination file.

ruby
copy_file "templates/config.yml", "config/settings.yml"

create_directory ​

Creates a directory. In reverse mode, removes the directory. alias: mkdir.

ruby
create_directory "app/services"

append_to_file ​

Appends content to the end of a file. Accepts a block. Skipped in reverse mode. (TODO: could we not skipt it?)

ruby
append_to_file "Gemfile", "\ngem 'sidekiq'\n"

prepend_to_file ​

Prepends content to the beginning of a file. Accepts a block. Skipped in reverse mode. (TODO: could we not skipt it?)

ruby
prepend_to_file "app/models/user.rb", <<~RUBY
  # frozen_string_literal: true"
RUBY

inject_into_file ​

Injects content into a file at a specific location using before: or after: anchors. Skipped in reverse mode. alias: inject

ruby
str = "\n  resources :posts\n"

inject "config/routes.rb", str, after: "Rails.application.routes.draw do\n"
ruby
inject "Gemfile", "gem 'pg'\n", before: "gem 'sqlite3'"

gsub_file ​

Performs a global substitution in a file. Skipped in reverse mode.

ruby
gsub_file "config/database.yml", "sqlite3", "postgresql"

chmod ​

Changes file permissions. Skipped in reverse mode.

ruby
chmod "bin/setup", 0o755

Templates ​

template ​

Renders an ERB template from the generator's templates/ directory and writes the result to the destination path. In reverse mode, removes the generated file.

ruby
template "controller.rb.tt"

Template files use the .tt extension. The destination path is derived by stripping .tt from the source name, or can be specified explicitly.

ruby
template "controller.rb.tt", "app/controllers/#{params.name}_controller.rb"

Inside templates, all generator methods and params are available.

erb
class <%= params.name.to_class %>Controller < ApplicationController
  def index
    @<%= params.name.pluralize %> = <%= params.name.to_class %>.all
  end
end

Custom Template Context ​

Pass a context: option to expose a different object's methods inside the template.

ruby
template "model.rb.tt", context: ParamsDecorator.new(params)

The context object's methods take priority. If a method is not found on the context, Loci falls back to the generator instance.

Ruby Code Helpers ​

inject_into_class ​

Injects content into a class or module body. Content is placed before the first method definition. Skipped in reverse mode.

ruby
inject_into_class "app/models/user.rb", "ClassName", "  has_many :posts\n"

Accepts a block:

ruby
inject_into_class "app/models/user.rb", "ClassName" do
  "  validates :name, presence: true\n"
end

inject_into_private ​

Injects content into the private section of a class. Creates the private keyword if it does not exist. Skipped in reverse mode.

ruby
inject_into_private "app/models/user.rb", "ClassName", <<~RUBY
  def normalize_name
    self.name = name.strip
  end
RUBY

gem ​

Adds a gem to the Gemfile. Supports version constraints, source options, and group scoping. Bidirectional: adds in forward mode, runs bundle remove in reverse.

ruby
gem "sidekiq"
ruby
gem "pg", "~> 1.5"
ruby
gem "rspec", group: :test
ruby
gem "my_gem", github: "user/repo", branch: "main"

Rails Helpers ​

rails_generate ​

Runs a Rails generator. In reverse mode, runs the corresponding rails destroy command. Aliased as rails_g.

ruby
rails_generate "migration", "CreateUsers", "name:string", "email:string"

add_route ​

Adds a route to config/routes.rb. Supports type: of :resources, :resource, or :namespace. Handles nested namespaces automatically. Skipped in reverse mode.

ruby
add_route "posts"
ruby
add_route "api/v1/users", type: :resources

This generates the proper namespace wrapping:

ruby
namespace :api do
  namespace :v1 do
    resources :users
  end
end

System Helpers ​

system_command ​

Executes a shell command. Aliased as cmd. Skipped in reverse mode.

ruby
cmd "bundle", "install"

cd ​

Changes the working directory for the duration of a block.

ruby
cd "frontend" do
  cmd "npm", "install"
end

Text Helpers ​

wrap_with ​

Wraps captured content in a block structure. Useful for building class or module bodies.

ruby
content = wrap_with("class User < ApplicationRecord") do
  "has_many :posts"
end

# class User < ApplicationRecord
#   has_many :posts
# end

wrap_with_modules ​

Wraps content in nested module declarations.

ruby
wrap_with_modules("api", "v1") do
  <<~RUBY
    class UsersController
    end
  RUBY
end

# module Api
#   module V1
#     class UsersController
#     end
#   end
# end