Merge pull request #625 from hilary/slugs_everywhere

generator: slugs everywhere [closes #624]

Author: hilary

README.md

@@ -12,13 +12,16 @@ the language, so you're all set.
 
 ## Anatomy of an Exercise
 
-The files for an exercise live in `exercises/<exercise_name>` (where
-`<exercise_name>` is the slug for the exercise, e.g. `clock` or
-`atbash-cipher`). Inside its directory, each exercise has:
+The files for an exercise live in `exercises/<slug>`. The slug for an exercise
+is a unique nickname composed of a-z (lowercase) and -, e.g. `clock` or
+`atbash-cipher`. Inside its directory, each exercise has:
 
 * a test suite, `<exercise_name>_test.rb`
 * an example solution, `.meta/solutions/<exercise_name>.rb`
 
+where `<exercise_name>` is the underscored version of the exercise's slug, e.g.,
+`clock` or `atbash_cipher`.
+
 If the exercise has a test generator, the directory will also contain:
 
 * `.version`
@@ -47,6 +50,7 @@ rake test:clock
 
 To pass arguments to the test command, like `-p` for example, you can run
 the following:
+
 ```sh
 rake test:clock -- -p
 ```
@@ -93,13 +97,11 @@ tree -L 1 ~/code/exercism
 
 From within the xruby directory, run the following command:
 
-```
-bin/generate <exercise_name>
-```
+    bin/generate <slug>
 
 #### Changing a Generated Exercise
 
-Do not edit `<exercise_name>/<exercise_name>_test.rb`. Any changes you make will
+Do not edit `<slug>/<exercise_name>_test.rb`. Any changes you make will
 be overwritten when the test suite is regenerated.
 
 There are two reasons why a test suite might change:
@@ -111,7 +113,7 @@ In the first case, the changes need to be made to the `canonical-data.json` file
 the exercise, which lives in the x-common repository.
 
 ```
-../x-common/exercises/<exercise_name>/
+../x-common/exercises/<slug>/
 ├── canonical-data.json
 ├── description.md
 └── metadata.yml
@@ -124,20 +126,20 @@ exercise.
 Changes that don't have to do directly with the test inputs and outputs should
 be made to the exercise's test case generator, discussed
 in [implementing a new generator](#implementing-a-generator), next.  Then you
-can regenerate the exercise with `bin/generate <exercise_name>`.
+can regenerate the exercise with `bin/generate <slug>`.
 
 #### Implementing a Generator
 
 An exercise's test case generator class produces the code that goes inside
 the minitest `test_<whatever>` methods. An exercise's generator lives in
-`exercises/<exercise_name>/.meta/generator/<exercise_name>_cases.rb`.
+`exercises/<slug>/.meta/generator/<exercise_name>_cases.rb`.
 
 The test case generator is a derived class of `ExerciseCase` (in
 `lib/generator/exercise_case.rb`). `ExerciseCase` does most of the work of
 extracting the canonical data. The derived class wraps the JSON for a single
 test case. The default version looks something like this:
 
-```
+```ruby
 require 'generator/exercise_case'
 
 class <ExerciseName>Case < Generator::ExerciseCase
@@ -150,9 +152,9 @@ class <ExerciseName>Case < Generator::ExerciseCase
 end
 ```
 
-where `<ExerciseName>` is the <exercise_name> slug in CamelCase. This is
-important, since the generator script will infer the name of the class from the
-<exercise_name> slug.
+where `<ExerciseName>` is the CamelCased version of the exercise's slug. This is
+important, since the generator script will infer the name of the class from
+`<slug>`.
 
 This class must provide the methods used by the test
 template. A
@@ -162,8 +164,10 @@ base class provides methods for the default template for everything except
 `#workload`.
 
 `#workload` generates the code for the body of a test, including the assertion
-and any setup required. The base class provides a variety of assertion and
-helper methods. Beyond that, you can implement any helper methods that you need
+and any setup required. The base class provides a variety of
+[assertion](https://github.com/exercism/xruby/blob/master/lib/generator/exercise_case/assertion.rb) and
+[helper](https://github.com/exercism/xruby/blob/master/lib/generator/exercise_case.rb) methods.
+Beyond that, you can implement any helper methods that you need
 as private methods in your derived class. See below for more information
 about [the intention of #workload](#workload-philosophy)
 

lib/generator/command_line.rb

@@ -16,14 +16,11 @@ def parse(args)
     attr_reader :paths
 
     def generators
-      exercises.map do |exercise_name|
-        generator(repository(exercise_name))
-      end
+      exercises.map { |slug| generator(repository(slug)) }
     end
 
     def exercises
-      @options[:all] ? Files::GeneratorCases.available(paths.track) :
-        [@options[:exercise_name]]
+      @options[:all] ? Files::GeneratorCases.available(paths.track) : [@options[:slug]]
     end
 
     def generator(repository)
@@ -38,9 +35,9 @@ def freeze?
       @options[:freeze] || @options[:all]
     end
 
-    def repository(exercise_name)
+    def repository(slug)
       LoggingRepository.new(
-        repository: Repository.new(paths: paths, exercise_name: exercise_name),
+        repository: Repository.new(paths: paths, slug: slug),
         logger: logger
       )
     end

lib/generator/command_line/generator_optparser.rb

@@ -6,7 +6,7 @@ class GeneratorOptparser
       freeze: false,
       all: false,
       verbose: false,
-      exercise_name: nil
+      slug: nil
     }.freeze
 
     attr_reader :options
@@ -27,7 +27,7 @@ def options_valid?
     def parse_options
       @options = DEFAULT_OPTIONS.dup
       option_parser.parse!(@args)
-      options.tap { |opts| opts[:exercise_name] = @args.shift unless opts[:all] }
+      options.tap { |opts| opts[:slug] = @args.shift unless opts[:all] }
     end
 
     def option_parser
@@ -75,15 +75,15 @@ def validate_options
     end
 
     def validate_exercise
-      return true if options[:exercise_name]
+      return true if options[:slug]
       $stderr.puts "Exercise name required!\n"
       $stdout.puts usage
       false
     end
 
     def validate_cases
-      return true if available_generators.include?(options[:exercise_name])
-      $stderr.puts "A generator does not currently exist for #{options[:exercise_name]}!"
+      return true if available_generators.include?(options[:slug])
+      $stderr.puts "A generator does not currently exist for #{options[:slug]}!"
       false
     end
   end

lib/generator/files.rb

@@ -48,13 +48,13 @@ def write(content)
     end
 
     # An Exercise is used as part of a Repository
-    # so expects :paths and :exercise_name to be defined.
+    # so expects :paths and :slug to be defined.
     module Exercise
       def paths
         fail NotImplementedError, 'Should return a Generator::Paths object'
       end
 
-      def exercise_name
+      def slug
         fail NotImplementedError, 'Should return a String object'
       end
     end

lib/generator/files/generator_cases.rb

@@ -3,16 +3,16 @@ module Files
     module GeneratorCases
       class << self
         def available(track_path)
-          cases_filepaths(track_path).map { |filepath| exercise_name(filepath) }.sort
+          cases_filepaths(track_path).map { |filepath| slugify(filepath) }.sort
         end
 
-        def class_name(exercise_name)
-          filename(exercise_name)[0..-2].split('_').map(&:capitalize).join
+        def class_name(exercise_name_or_slug)
+          filename(exercise_name_or_slug)[0..-2].split('_').map(&:capitalize).join
         end
 
-        def source_filepath(track_path, exercise_name)
-          path = meta_generator_path(track_path, exercise_name)
-          filename = filename(exercise_name) + '.rb'
+        def source_filepath(track_path, slug)
+          path = meta_generator_path(track_path, slug)
+          filename = filename(slug) + '.rb'
           File.join(path, filename)
         end
 
@@ -23,16 +23,16 @@ def cases_filepaths(track_path)
           Dir.glob(generator_glob, File::FNM_DOTMATCH)
         end
 
-        def exercise_name(filepath)
+        def slugify(filepath)
           %r{([^/]*)_cases\.rb$}.match(filepath).captures[0].tr('_', '-')
         end
 
-        def filename(exercise_name)
-          "#{exercise_name.tr('-', '_')}_cases"
+        def filename(exercise_name_or_slug)
+          "#{exercise_name_or_slug.tr('-', '_')}_cases"
         end
 
-        def meta_generator_path(track_path, exercise_name)
-          File.join(track_path, 'exercises', exercise_name, '.meta', 'generator')
+        def meta_generator_path(track_path, slug)
+          File.join(track_path, 'exercises', slug, '.meta', 'generator')
         end
       end
     end

lib/generator/files/metadata_files.rb

@@ -12,7 +12,7 @@ def canonical_data
       private
 
       def exercise_metadata_path
-        File.join(paths.metadata, 'exercises', exercise_name)
+        File.join(paths.metadata, 'exercises', slug)
       end
     end
 

lib/generator/files/track_files.rb

@@ -24,7 +24,7 @@ def tests_template
       private
 
       def exercise_path
-        File.join(paths.track, 'exercises', exercise_name)
+        File.join(paths.track, 'exercises', slug)
       end
 
       def meta_path
@@ -36,15 +36,15 @@ def solutions_path
       end
 
       def minitest_tests_filename
-        "#{exercise_name.gsub(/[ -]/, '_')}_test.rb"
+        "#{slug.gsub(/[ -]/, '_')}_test.rb"
       end
 
       def version_filename
         '.version'
       end
 
       def example_filename
-        "#{exercise_name}.rb"
+        "#{slug}.rb"
       end
 
       def tests_template_absolute_filename

lib/generator/repository.rb

@@ -6,12 +6,12 @@ class Repository
     include Files::MetadataFiles
     include TemplateValuesFactory
 
-    def initialize(paths:, exercise_name:)
+    def initialize(paths:, slug:)
       @paths = paths
-      @exercise_name = exercise_name
+      @slug = slug
     end
 
-    attr_reader :paths, :exercise_name
+    attr_reader :paths, :slug
 
     def version
       tests_version.to_i
@@ -56,7 +56,7 @@ def update_example_solution
 
     def create_tests_file
       @repository.create_tests_file
-      @logger.info "Generated #{exercise_name} tests version #{version}"
+      @logger.info "Generated #{slug} tests version #{version}"
     end
   end
 end

lib/generator/template_values.rb

@@ -6,7 +6,7 @@ class TemplateValues
     def initialize(abbreviated_commit_hash:, version:, exercise_name:, test_cases:, canonical_data_version: nil)
       @abbreviated_commit_hash = abbreviated_commit_hash
       @version = version
-      @exercise_name = exercise_name ? exercise_name.tr('-_', '_') : ''
+      @exercise_name = exercise_name
       @test_cases = test_cases
       @canonical_data_version = canonical_data_version
     end
@@ -16,7 +16,7 @@ def get_binding
     end
 
     def exercise_name_camel
-      exercise_name.split(/[-_]/).map(&:capitalize).join
+      exercise_name.split('_').map(&:capitalize).join
     end
   end
 
@@ -26,26 +26,30 @@ def template_values
         abbreviated_commit_hash: canonical_data.abbreviated_commit_hash,
         canonical_data_version: canonical_data.version,
         version: version,
-        exercise_name: exercise_name,
+        exercise_name: slug_underscore,
         test_cases: extract
       )
     end
 
     private
 
+    def slug_underscore
+      slug ? slug.tr('-_', '_') : ''
+    end
+
     def extract
       load cases_load_name
       extractor.cases(canonical_data.to_s)
     end
 
     def extractor
         CaseValues::Extractor.new(
-          case_class: Object.const_get(Files::GeneratorCases.class_name(exercise_name))
+          case_class: Object.const_get(Files::GeneratorCases.class_name(slug))
         )
     end
 
     def cases_load_name
-      Files::GeneratorCases.source_filepath(paths.track, exercise_name)
+      Files::GeneratorCases.source_filepath(paths.track, slug)
     end
   end
 end

lib/tasks/exercise.rb

@@ -1,12 +1,12 @@
 class Exercise
   class << self
     def all
-      exercise_names.map { |e| new(e) }
+      slugs.map { |e| new(e) }
     end
 
     private
 
-    def exercise_names
+    def slugs
       FileList['exercises/*'].pathmap('%f').exclude('TRACK_HINTS.md')
     end
   end
@@ -23,7 +23,7 @@ def directory
   end
 
   def example_file
-    example_filename
+    File.join('.meta', 'solutions', "#{name}.rb")
   end
 
   def testable_example_file
@@ -36,10 +36,6 @@ def test_file
 
   private
 
-  def example_filename
-    File.join('.meta', 'solutions', "#{name}.rb")
-  end
-
   def base_file_name
     @_base_file_name ||= name.tr('-', '_')
   end