Refactor internal API (#25)

* refactoring how the internal method API is handled to avoid name collisions. Fixes #23

* oops, missing something

* Fixing the compilation issue. The methods now should really direct you to the macros for overriding

Author: jwoertink

spec/lucky_task/runner_spec.cr

@@ -4,7 +4,7 @@ include HaveDefaultHelperMessageMatcher
 
 describe LuckyTask::Runner do
   it "adds tasks to the runner when task classes are created" do
-    expected_task_names = ["another_task", "my.cool_task", "my.custom_name", "task_with_args", "task_with_required_format_args", "task_with_switch_flags", "task_with_int32_flags", "task_with_float64_flags", "task_with_positional_args", "task_with_fancy_output"]
+    expected_task_names = ["another_task", "my.cool_task", "my.custom_name", "task_with_args", "task_with_required_format_args", "task_with_switch_flags", "task_with_int32_flags", "task_with_float64_flags", "task_with_positional_args", "task_with_fancy_output", "task_with_similar_method_names"]
 
     task_names = LuckyTask::Runner.tasks.map(&.task_name)
     task_names.size.should eq(expected_task_names.size)

spec/lucky_task/task_spec.cr

@@ -7,21 +7,21 @@ end
 
 describe LuckyTask::Task do
   it "creates a task_name from the class name when inheriting" do
-    My::CoolTask.new.task_name.should eq "my.cool_task"
+    My::CoolTask.task_name.should eq "my.cool_task"
   end
 
   it "uses a specified task_name over the auto generated task_name" do
-    Some::Other::Task.new.task_name.should eq "my.custom_name"
+    Some::Other::Task.task_name.should eq "my.custom_name"
   end
 
   it "creates summary text" do
-    My::CoolTask.new.summary.should eq "This task does something awesome"
+    My::CoolTask.task_summary.should eq "This task does something awesome"
   end
 
   it "has a default help message" do
-    message = My::CoolTask.new.help_message
+    message = My::CoolTask.task_help_message
     message.should contain "Run this task with 'lucky my.cool_task'"
-    message.should contain(My::CoolTask.new.summary)
+    message.should contain(My::CoolTask.task_summary)
   end
 
   describe "print_help_or_call" do
@@ -161,4 +161,16 @@ describe LuckyTask::Task do
       task.output.to_s.should contain "Fancy output"
     end
   end
+
+  describe "methods that used to conflict" do
+    it "allows you to name the args whatever" do
+      task = TaskWithSimilarMethodNames.new
+      task.print_help_or_call(args: ["--name=name", "--task-name=task-name", "--summary=summary", "--task-summary=task-summary", "--help-message=help-message"]).as(TaskWithSimilarMethodNames)
+      task.name.should eq("name")
+      task.task_name.should eq("task-name")
+      task.summary.should eq("summary")
+      task.task_summary.should eq("task-summary")
+      task.help_message.should eq("help-message")
+    end
+  end
 end

spec/support/tasks.cr

@@ -8,11 +8,8 @@ end
 
 class Some::Other::Task < LuckyTask::Task
   summary "bar"
-  task_name "my.custom_name"
-
-  def help_message
-    "Custom help message"
-  end
+  name "my.custom_name"
+  help_message "Custom help message"
 
   def call
   end
@@ -97,10 +94,20 @@ class TaskWithPositionalArgs < LuckyTask::Task
 end
 
 class TaskWithFancyOutput < LuckyTask::Task
-  summary "This is a task with some fancy output"
-
   def call
     output.puts "Fancy output".colorize.green
     self
   end
 end
+
+class TaskWithSimilarMethodNames < LuckyTask::Task
+  arg :name, "Using name"
+  arg :task_name, "Using task_name"
+  arg :summary, "Using summary"
+  arg :task_summary, "Using task_summary"
+  arg :help_message, "Using help_message"
+
+  def call
+    self
+  end
+end

src/lucky_task/runner.cr

@@ -1,14 +1,14 @@
 class LuckyTask::Runner
-  @@tasks = [] of LuckyTask::Task
+  @@tasks = [] of LuckyTask::Task.class
   class_property? exit_with_error_if_not_found : Bool = true
 
   extend LuckyTask::TextHelpers
 
-  def self.register_task(task : LuckyTask::Task) : Nil
+  def self.register_task(task : LuckyTask::Task.class) : Nil
     @@tasks.push(task)
   end
 
-  def self.tasks : Array(LuckyTask::Task)
+  def self.tasks : Array(LuckyTask::Task.class)
     @@tasks.sort_by!(&.task_name)
   end
 
@@ -21,7 +21,7 @@ class LuckyTask::Runner
       io.puts <<-HELP_TEXT
       Missing a task name
 
-      To see a list of available tasks, run #{"lucky --help".colorize(:green)}
+      To see a list of available tasks, run #{"lucky tasks".colorize(:green)}
       HELP_TEXT
     else
       if task = find_task(task_name)
@@ -47,15 +47,18 @@ class LuckyTask::Runner
   end
 
   def self.find_task(task_name : String) : LuckyTask::Task?
-    @@tasks.find { |task| task.task_name == task_name }
+    found_task = @@tasks.find { |task| task.task_name == task_name }
+    if found_task
+      found_task.new
+    end
   end
 
   def self.tasks_list : String
     String.build do |list|
       tasks.each do |task|
         list << ("  #{arrow} " + task.task_name).colorize(:green)
         list << list_padding_for(task.task_name)
-        list << task.summary
+        list << task.task_summary
         list << "\n"
       end
     end

src/lucky_task/task.cr

@@ -6,29 +6,35 @@ abstract class LuckyTask::Task
     property output : IO = STDOUT
 
     {% if !@type.abstract? %}
-      LuckyTask::Runner.register_task(self.new)
+      LuckyTask::Runner.register_task(self)
     {% end %}
 
-    @[Deprecated("Use `task_name` instead.")]
-    def name : String
-      task_name
+    # The name of your task as derived by the class name
+    # Use the `task_name` macro to define a custom task name
+    def self.task_name : String
+      "{{@type.name.gsub(/::/, ".").underscore}}"
     end
 
-    def task_name : String
-      "{{@type.name.gsub(/::/, ".").underscore}}"
+    # By default, task summaries are optional.
+    # Use the `summary` macro to define a custom summary
+    def self.task_summary : String
+      ""
     end
 
-    def help_message : String
-      <<-TEXT
-      #{summary}
+    # The help text to be displayed when a help flag
+    # is passed in (e.g. -h, --help)
+    # Use the `help_message`
+    def self.task_help_message : String
+      <<-TEXT.strip
+      #{task_summary}
 
       Run this task with 'lucky #{task_name}'
       TEXT
     end
 
     def print_help_or_call(args : Array(String))
       if wants_help_message?(args)
-        output.puts help_message
+        output.puts self.class.task_help_message
       else
         \{% for opt in @type.constant(:PARSER_OPTS) %}
         set_opt_for_\{{ opt.id }}(args)
@@ -43,24 +49,16 @@ abstract class LuckyTask::Task
     end
   end
 
+  # The general description of what this task does
+  #
+  # This is used in the help_text when a help flag is passed
+  # to the task through the CLI
   macro summary(summary_text)
-    def summary : String
+    def self.task_summary : String
       {{summary_text}}
     end
   end
 
-  # DEPRECATED: Use `task_name` instead
-  macro name(name_text)
-    @[Deprecated("Use `task_name` instead.")]
-    def name
-      task_name
-    end
-
-    def task_name : String
-      {{name_text}}
-    end
-  end
-
   # Renames the task name for CLI use
   #
   # By default the task name is derived from the full module and class name.
@@ -75,12 +73,28 @@ abstract class LuckyTask::Task
   #   # other methods, etc.
   # end
   # ```
-  macro task_name(name_text)
-    def task_name : String
+  macro name(name_text)
+    def self.task_name : String
       {{name_text}}
     end
   end
 
+  # Customize your help message with the provided `help_text`
+  #
+  # ```
+  # class KeyGen < LuckyTask::Task
+  #   summary "Generate a new key"
+  #   help_message "Call lucky key_gen to generate a new key"
+  #
+  #   # other methods, etc.
+  # end
+  # ```
+  macro help_message(help_text)
+    def self.task_help_message : String
+      {{help_text}}
+    end
+  end
+
   # Creates a method of `arg_name` that returns the value passed in from the CLI.
   # The CLI arg position is based on the order in which `positional_arg` is specified
   # with the first call being position 0, and so on.
@@ -279,5 +293,4 @@ abstract class LuckyTask::Task
   end
 
   abstract def call
-  abstract def summary : String
 end