From 7d6dc20403fe8d0538c3648fd0eeb3a37721a33a Mon Sep 17 00:00:00 2001
From: Sylphrena <sylphrena@noreply.codeberg.org>
Date: Mon, 4 Aug 2025 18:20:03 +0200
Subject: [PATCH] feat: add <command> placeholder to usage

---
 spec/formatter_spec.cr | 30 +++++++++++++++++++-----------
 spec/helper_spec.cr    |  2 +-
 src/cling/formatter.cr |  4 ++++
 3 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/spec/formatter_spec.cr b/spec/formatter_spec.cr
index 5217588..39a3c96 100644
--- a/spec/formatter_spec.cr
+++ b/spec/formatter_spec.cr
@@ -25,17 +25,19 @@ class WelcomeCommand < Cling::Command
   end
 end
 
-command = GreetCommand.new
-command.add_command WelcomeCommand.new
+command_with_subcommand = GreetCommand.new
+command_with_subcommand.add_command WelcomeCommand.new
+
+command_without_subcommand = GreetCommand.new
 formatter = Cling::Formatter.new
 
 describe Cling::Formatter do
   it "generates a help template" do
-    formatter.generate(command).chomp.should eq <<-HELP
+    formatter.generate(command_with_subcommand).chomp.should eq <<-HELP
       Greets a person
 
       Usage:
-      \tgreet <arguments> [options]
+      \tgreet <command> <arguments> [options]
 
       Commands:
       \twelcome    sends a friendly welcome message
@@ -53,11 +55,11 @@ describe Cling::Formatter do
   it "generates with a custom delimiter" do
     formatter.options.option_delim = '+'
 
-    formatter.generate(command).chomp.should eq <<-HELP
+    formatter.generate(command_with_subcommand).chomp.should eq <<-HELP
       Greets a person
 
       Usage:
-      \tgreet <arguments> [options]
+      \tgreet <command> <arguments> [options]
 
       Commands:
       \twelcome    sends a friendly welcome message
@@ -74,19 +76,25 @@ describe Cling::Formatter do
 
   it "generates a description section" do
     String.build do |io|
-      formatter.format_description(command, io)
+      formatter.format_description(command_with_subcommand, io)
     end.should eq "Greets a person\n\n"
   end
 
-  it "generates a usage section" do
+  it "generates a usage section with subcommand" do
+    String.build do |io|
+      formatter.format_usage(command_with_subcommand, io)
+    end.should eq "Usage:\n\tgreet <command> <arguments> [options]\n\n"
+  end
+
+  it "generates a usage section without subcommand" do
     String.build do |io|
-      formatter.format_usage(command, io)
+      formatter.format_usage(command_without_subcommand, io)
     end.should eq "Usage:\n\tgreet <arguments> [options]\n\n"
   end
 
   it "generates an arguments section" do
     String.build do |io|
-      formatter.format_arguments(command, io)
+      formatter.format_arguments(command_with_subcommand, io)
     end.should eq "Arguments:\n\tname    the name of the person (required)\n\n"
   end
 
@@ -94,7 +102,7 @@ describe Cling::Formatter do
     formatter.options.option_delim = '-'
 
     String.build do |io|
-      formatter.format_options(command, io)
+      formatter.format_options(command_with_subcommand, io)
     end.chomp.should eq <<-HELP
       Options:
       \t-h, --help       sends help information
diff --git a/spec/helper_spec.cr b/spec/helper_spec.cr
index 4fa1221..d680d30 100644
--- a/spec/helper_spec.cr
+++ b/spec/helper_spec.cr
@@ -49,7 +49,7 @@ describe Cling::MainCommand do
       Runs some Crystal commands
 
       Usage:
-      \tmain [options]
+      \tmain <command> [options]
 
       Commands:
       \tcontext
diff --git a/src/cling/formatter.cr b/src/cling/formatter.cr
index 3479c65..3160c1a 100644
--- a/src/cling/formatter.cr
+++ b/src/cling/formatter.cr
@@ -63,6 +63,10 @@ module Cling
 
       if command.usage.empty?
         io << "\n\t" << command.name
+        unless command.children.empty?
+          io << " <command>"
+        end
+
         unless command.arguments.empty?
           if command.arguments.values.any? &.required?
             io << " <arguments>"