Merge pull request #31 from at-grandpa/custom_help

Custom help

README.md

@@ -41,6 +41,7 @@ _"clim" = "cli" + "slim"_
 - [x] Required flag for option
 - [x] Nested sub commands
 - [x] `--help` option
+- [x] Customizable help message
 - [x] `version` macro
 - [x] Command name alias
 
@@ -53,7 +54,7 @@ Add this to your application's `shard.yml`:
 dependencies:
   clim:
     github: at-grandpa/clim
-    version: 0.3.0
+    version: 0.3.1
 ```
 
 ## Minimum sample
@@ -431,6 +432,44 @@ class MyCli < Clim
 end
 ```
 
+#### custom_help
+
+You can customize the help message. In the `custom_help` block, you need to return a `String`.
+
+```crystal
+class MyCli < Clim
+  main_command do
+    desc "my desc message."
+    usage "my usage message."
+    option "-n", type: String, desc: "name."
+    option "--my-age", type: Int32, desc: "age."
+    custom_help do |desc, usage, options_help|
+      <<-MY_HELP
+      command description: #{desc}
+      command usage: #{usage}
+
+      options:
+      #{options_help}
+      MY_HELP
+    end
+    run do |options, arguments|
+      puts options.help
+    end
+  end
+end
+```
+
+```console
+$ crystal run src/custom_help_test.cr
+command description: my desc message.
+command usage: my usage message.
+
+options:
+    -n                               name. [type:String]
+    --my-age                         age. [type:Int32]
+    --help                           Show this help.
+```
+
 ### help string
 
 ```crystal

shard.yml

@@ -1,5 +1,5 @@
 name: clim
-version: 0.3.0
+version: 0.3.1
 
 authors:
   - at-grandpa <@at_grandpa>

spec/clim/dsl_spec/custom_help_spec.cr

@@ -0,0 +1,44 @@
+require "../../dsl_spec"
+
+{% begin %}
+{%
+  main_help_message = <<-HELP_MESSAGE
+                      command description: my desc message.
+                      command usage: my usage message.
+
+                      options:
+                          --uint8=VALUE                    Option description. [type:UInt8]
+                          --uint16=VALUE                   Option description. [type:UInt16]
+                          --help                           Show this help.
+
+                      HELP_MESSAGE
+%}
+
+spec(
+  spec_class_name: OptionTypeSpec,
+  spec_dsl_lines: [
+    <<-CUSTOM_HELP
+    custom_help do |desc, usage, options_help|
+      <<-MY_HELP
+      command description: \#{desc}
+      command usage: \#{usage}
+
+      options:
+      \#{options_help}
+      MY_HELP
+    end
+    CUSTOM_HELP,
+    "desc \"my desc message.\"",
+    "usage \"my usage message.\"",
+    "option \"--uint8=VALUE\", type: UInt8",
+    "option \"--uint16=VALUE\", type: UInt16",
+  ],
+  spec_desc: "option type spec,",
+  spec_cases: [
+    {
+      argv:        ["--help"],
+      expect_help: {{main_help_message}},
+    },
+  ]
+)
+{% end %}

src/clim/command.cr

@@ -61,6 +61,16 @@ class Clim
     def define_version(parser)
     end
 
+    macro custom_help(&block)
+      def custom_help_def : String
+        Proc(String, String, String, String).new {{ block.id }} .call(desc, usage, self.parser.to_s)
+      end
+    end
+
+    def custom_help_def : String
+      Help.new(self).display
+    end
+
     macro main_command
       {% raise "Can not be declared 'main_command' as sub command." if @type.superclass.id.stringify == "Clim::Command" %}
     end
@@ -113,7 +123,7 @@ class Clim
     end
 
     private def help
-      Help.new(self).display
+      custom_help_def
     end
 
     private def display_help? : Bool

src/clim/version.cr

@@ -1,3 +1,3 @@
 class Clim
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end