Let's start with a situation I've run into more times than I'd like to admit. You've spent an afternoon writing a cool piece of logic, you've organized it into a folder, and you're excited to package it as a gem. You try to use it in a separate script, and you hit this:

require 'word_weaver'

puts WordWeaver.weave("Hello world")
# NameError: uninitialized constant WordWeaver

You look at your file structure and it looks perfect: you have lib/word_weaver.rb and you have lib/word_weaver/weaver.rb where the actual class is defined. You're thinking, "I required the gem, why can't it see the class?"

The "Uninitialized Constant" Headache

The mistake here is a fundamental misunderstanding of how Ruby handles require. When you require 'word_weaver', Ruby looks for a file named word_weaver.rb in your load path. It finds it, executes it, and then stops. It does not automatically go digging through the word_weaver/ subdirectory to find other files.

If your lib/word_weaver.rb file is empty or just contains a version number, the WordWeaver class defined in lib/word_weaver/weaver.rb never actually gets loaded into memory. That's why Ruby tells you the constant is uninitialized—as far as the runtime is concerned, that class doesn't exist yet.

The Entry Point Pattern

To fix this, you need to treat your main gem file (the one that shares the gem's name) as the "conductor" for the rest of your library. Your lib/word_weaver.rb should be responsible for requiring all the necessary internal components.

Here is the corrected setup for lib/word_weaver.rb:

# lib/word_weaver.rb
require_relative 'word_weaver/version'
require_relative 'word_weaver/weaver'

module WordWeaver
  def self.weave(text)
    Weaver.new(text).process
  end
end

By using require_relative inside the entry file, you ensure that whenever a user calls require 'word_weaver', the entire dependency chain of your gem is pulled in. Now, the WordWeaver module and the Weaver class are both available, and the NameError vanishes.

Taming the Gemspec File

Once the code actually runs, the next hurdle is the .gemspec file. This is the manifest that tells RubyGems what your gem is and, more importantly, which files to include in the final package. A common mistake is manually listing every file in the files array, which becomes a maintenance nightmare the moment you add a new folder.

I highly recommend using a dynamic approach to gather your files. If you're using Git, you can let Git tell the gemspec which files are tracked. It's much cleaner:

Spec.files = `git ls-files -z`.split("\x0").reject do |f|
  (f == '.gemspec') || (f == '.gitignore')
end

This snippet asks Git for a list of all files, splits them correctly, and ignores the gemspec itself. It ensures that you don't accidentally ship your .gitignore or local README.md drafts to the public registry.

Testing Locally Before Publishing

You don't want to push a broken version to RubyGems.org. I always test my gems locally first. There are two commands you need to memorize for this workflow: gem build and gem install.

Run gem build word_weaver.gemspec. This creates a .gem file (a compressed archive of your code). Then, install it locally using the path to that file:

gem install ./word_weaver-0.1.0.gem

Now you can open a fresh irb session and require 'word_weaver' just like any other gem you've downloaded from the internet. If it works there, you're safe to push it to the world.

📋 Practical Task

Building the "CaseShifter" Gem

Your task is to create a small, functional Ruby gem from scratch called case_shifter. This gem should provide a utility to transform strings into "staggered case" (e.g., "Hello World" becomes "HeLlO wOrLd").

Requirements:

• File Structure: Create a lib/ directory. Inside, create case_shifter.rb (the entry point) and a subdirectory lib/case_shifter/shifter.rb (where the logic lives).
• The Logic: Implement a CaseShifter::Shifter class with a method stagger(text) that alternates the case of each character.
• The Entry Point: Ensure lib/case_shifter.rb requires the Shifter class and provides a convenience module method CaseShifter.shift(text).
• The Gemspec: Create a case_shifter.gemspec file with a valid name, version, and author. Use the git ls-files method or explicitly list your lib/ files to ensure they are included.
• Verification: Run gem build and gem install on your local machine. Verify it works by running a one-liner in your terminal: ruby -r case_shifter -e "puts CaseShifter.shift('Software Engineering')".