feat: add print help method

Author: nader-zouaoui

parser/arg-parser-arg.cpp

@@ -21,7 +21,14 @@ bool arg_parser_arg::is_match(const std::wstring& other_arg) const
 
 std::wstring arg_parser_arg::get_help() const
 {
-    return m_name + L" or " + get_alias_string() + L"/n         " + m_description;
+    
+    return L"\t" + get_all_flags_string() + L":\n" + arg_parser_add_wstring_behind_multiline_text(arg_parser_format_string_to_length(m_description, MAX_HELP_WIDTH), L"\t   ");
+}
+
+std::wstring arg_parser_arg::get_all_flags_string() const
+{
+    if (get_alias_string().empty()) return m_name;
+    return m_name + L", " + get_alias_string();
 }
 
 std::wstring arg_parser_arg::get_usage_text() const
@@ -50,8 +57,11 @@ std::wstring arg_parser_arg::get_alias_string() const
     // convert alias vector to wstring
     std::wstring alias_string;
     for (auto& m_alias : m_aliases) {
-        alias_string.append(m_alias);
+        if (m_alias.empty()) continue;
+        alias_string.append(m_alias + L", ");
     }
+    if (alias_string.find(L", ") != std::wstring::npos) alias_string.erase(alias_string.end() - 2, alias_string.end());
+    
     return alias_string;
 }
 
@@ -110,3 +120,64 @@ bool arg_parser_arg::parse(std::vector<std::wstring> arg_vect)
     return true;
 }
 
+
+std::wstring arg_parser_add_wstring_behind_multiline_text(const std::wstring& str, const std::wstring& prefix)
+{
+    std::wstring formatted_str;
+    std::wstring current_line;
+    std::wistringstream iss(str);
+    while (getline(iss, current_line, L'\n'))
+    {
+        if (current_line.empty())
+        {
+            formatted_str += L"\n";
+            continue;
+        }
+    
+        formatted_str += prefix;
+        formatted_str += current_line;
+        formatted_str += L"\n";
+    }
+    return formatted_str;
+}
+
+std::wstring arg_parser_format_string_to_length(const std::wstring& str, size_t max_width)
+{
+    std::wstring formatted_str;
+    std::wistringstream lines_stream(str);
+    std::wstring line;
+
+    while (std::getline(lines_stream, line, L'\n'))
+    {
+        std::wstring current_line;
+        std::wistringstream word_stream(line);
+        std::wstring word;
+
+        while (word_stream >> word)
+        {
+            if (current_line.size() + word.size() + 1 > max_width)
+            {
+                formatted_str += current_line + L"\n";
+                current_line = word + L" ";
+            }
+            else
+            {
+                current_line += word + L" ";
+            }
+        }
+
+        if (!current_line.empty())
+        {
+            formatted_str += current_line + L"\n\n";
+        }
+    }
+
+    // Remove the trailing newline, if any
+    if (!formatted_str.empty() && formatted_str.back() == L'\n\n')
+    {
+        formatted_str.pop_back();
+        formatted_str.pop_back();
+    }
+
+    return formatted_str;
+}

parser/arg-parser-arg.h

@@ -3,6 +3,9 @@
 #include <vector>
 #include <set>
 #include <functional>
+#include <sstream>
+#include <string>
+#define MAX_HELP_WIDTH 80
 
 struct arg_parser_arg {
     const std::wstring m_name;
@@ -27,6 +30,7 @@ struct arg_parser_arg {
     );
     bool is_match(const std::wstring& arg) const;
     virtual std::wstring get_help() const;
+    virtual std::wstring get_all_flags_string() const;
     virtual std::wstring get_usage_text() const;
     arg_parser_arg add_alias(std::wstring new_alias);
     int get_arg_count() const;
@@ -61,3 +65,5 @@ class arg_parser_arg_pos : public arg_parser_arg {
     ) : arg_parser_arg(name, alias, description, default_values, arg_count) {};
 };
 
+std::wstring arg_parser_add_wstring_behind_multiline_text(const std::wstring& str, const std::wstring& prefix);
+std::wstring arg_parser_format_string_to_length(const std::wstring& str, size_t max_width);

parser/arg-parser.cpp

@@ -36,6 +36,7 @@
 #include <vector>
 #include <sstream>
 
+
 arg_parser::arg_parser() {}
 
 void arg_parser::parse(
@@ -95,6 +96,31 @@ void arg_parser::parse(
     }
 }
 
+void arg_parser::print_help() const
+{
+    std::wcout << L"NAME:\n" 
+
+        << L"\twperf - Performance analysis tools for Windows on Arm\n\n"
+        << L"\tUsage: wperf <command> [options]\n\n"
+        << L"SYNOPSIS:\n\n";
+    for (auto& command : m_commands_list)
+    {
+        std::wcout << L"\t" << command->get_all_flags_string() << L":\n" << command->get_usage_text() << L"\n" ;
+    }
+
+    std::wcout << L"OPTIONS:\n\n";
+    for (auto& flag : m_flags_list)
+    {
+        std::wcout << L" " << flag->get_help() << L"\n";
+    }
+    std::wcout << L"EXAMPLES:\n\n";
+    for (auto& command : m_commands_list)
+    {
+        if (command->get_examples().empty()) continue;
+        std::wcout << L"  " << command->get_examples() <<L"\n";
+    }
+}
+
 #pragma region error handling
 void arg_parser::throw_invalid_arg(const std::wstring& arg, const std::wstring& additional_message) const
 {
@@ -131,3 +157,18 @@ void arg_parser::throw_invalid_arg(const std::wstring& arg, const std::wstring&
 }
 
 #pragma endregion
+
+wstring arg_parser_arg_command::get_usage_text() const
+{
+    return arg_parser_add_wstring_behind_multiline_text(arg_parser_format_string_to_length(
+        m_useage_text + L"\n" + m_description, MAX_HELP_WIDTH), L"\t   ");
+}
+
+wstring arg_parser_arg_command::get_examples() const
+{
+    std::wstring example_output;
+    for (auto& example : m_examples) {
+        example_output += example + L"\n";
+    }
+    return arg_parser_add_wstring_behind_multiline_text(arg_parser_format_string_to_length(example_output, MAX_HELP_WIDTH),L"\t");
+}

parser/arg-parser.h

@@ -63,11 +63,17 @@ class arg_parser_arg_command : public arg_parser_arg_opt {
         const std::wstring name,
         const std::vector<std::wstring> alias,
         const std::wstring description,
-        const std::wstring examples,
-        const COMMAND_CLASS command
-    ) : arg_parser_arg_opt(name, alias, description), m_examples(examples), m_command(command) {};
+        const std::wstring useage_text,
+        const COMMAND_CLASS command,
+        const wstr_vec examples
+        ) : arg_parser_arg_opt(name, alias, description), m_examples(examples), m_command(command), m_useage_text(useage_text) {};
     const COMMAND_CLASS m_command = NO_COMMAND;
-    const std::wstring m_examples;
+    const wstr_vec m_examples;
+    const std::wstring m_useage_text;
+
+    wstring get_usage_text() const override;
+
+    wstring get_examples() const;
 
 };
 #pragma region arg structs
@@ -84,72 +90,95 @@ class arg_parser
         _In_ const int argc,
         _In_reads_(argc) const wchar_t* argv[]
     );
+    void print_help() const;
 #pragma endregion
 
 #pragma region Commands
     arg_parser_arg_command list_command = arg_parser_arg_command::arg_parser_arg_command(
         L"list",
         { L"-l" },
-        L"List available metrics and events.",
-        L"",
-        COMMAND_CLASS::LIST
+        L"List supported events and metrics. Enable verbose mode for more details.",
+        L"wperf list [-v] [--json] [--force-lock]",
+        COMMAND_CLASS::LIST,
+        {
+            L"> wperf list -v List all events and metrics available on your host with extended information."
+        }
     );
-
     arg_parser_arg_command test_command = arg_parser_arg_command::arg_parser_arg_command(
         L"test",
         { L"" },
-        L"",
-        L"",
-        COMMAND_CLASS::TEST
+        L"Configuration information about driver and application.",
+        L"wperf test [--json] [OPTIONS]",
+        COMMAND_CLASS::TEST,
+        {}
     );
     arg_parser_arg_command help_command = arg_parser_arg_command::arg_parser_arg_command(
         L"-h",
         { L"--help" },
-        L"",
-        L"",
-        COMMAND_CLASS::HELP
+        L"Run wperf help command.",
+        L"wperf help",
+        COMMAND_CLASS::HELP,
+        {}
     );
     arg_parser_arg_command version_command = arg_parser_arg_command::arg_parser_arg_command(
         L"--version",
         { L"" },
-        L"",
-        L"",
-        COMMAND_CLASS::VERSION
+        L"Display version.",
+        L"wperf --version",
+        COMMAND_CLASS::VERSION,
+        {}
     );
     arg_parser_arg_command detect_command = arg_parser_arg_command::arg_parser_arg_command(
         L"detect",
         { L"" },
-        L"",
-        L"",
-        COMMAND_CLASS::DETECT
+        L"List installed WindowsPerf-like Kernel Drivers (match GUID).",
+        L"wperf detect [--json] [OPTIONS]",
+        COMMAND_CLASS::DETECT,
+        {}
     );
     arg_parser_arg_command sample_command = arg_parser_arg_command::arg_parser_arg_command(
         L"sample",
         { L"" },
-        L"",
-        L"",
-        COMMAND_CLASS::SAMPLE
+        L"Sampling mode, for determining the frequencies of event occurrences produced by program locations at the function, basic block, and /or instruction levels.",
+        L"wperf sample [-e] [--timeout] [-c] [-C] [-E] [-q] [--json] [--output] [--config] [--image_name] [--pe_file] [--pdb_file] [--sample-display-long] [--force-lock] [--sample-display-row] [--symbol] [--record_spawn_delay] [--annotate] [--disassemble]",
+         COMMAND_CLASS::SAMPLE,
+        {
+            L"> wperf sample -e ld_spec:100000 --pe_file python_d.exe -c 1 Sample event `ld_spec` with frequency `100000` already running process `python_d.exe` on core #1. Press Ctrl + C to stop sampling and see the results.",
+        }
     );
     arg_parser_arg_command record_command = arg_parser_arg_command::arg_parser_arg_command(
         L"record",
         { L"" },
-        L"",
-        L"",
-        COMMAND_CLASS::RECORD
+        L"Same as sample but also automatically spawns the process and pins it to the core specified by `-c`. Process name is defined by COMMAND.User can pass verbatim arguments to the process with[ARGS].",
+        L"wperf record [-e] [--timeout] [-c] [-C] [-E] [-q] [--json] [--output] [--config] [--image_name] [--pe_file] [--pdb_file] [--sample-display-long] [--force-lock] [--sample-display-row] [--symbol] [--record_spawn_delay] [--annotate] [--disassemble] --COMMAND[ARGS]",
+        COMMAND_CLASS::RECORD,
+        {
+            L"> wperf record -e ld_spec:100000 -c 1 --timeout 30 -- python_d.exe -c 10**10**100 Launch `python_d.exe - c 10 * *10 * *100` process and start sampling event `ld_spec` with frequency `100000` on core #1 for 30 seconds. Hint: add `--annotate` or `--disassemble` to `wperf record` command line parameters to increase sampling \"resolution\"."
+#ifdef ENABLE_SPE
+           ,L"(> wperf record -e arm_spe_0/ld=1/ -c 8 --cpython\PCbuild\arm64\python_d.exe -c 10**10**100 Launch `python_d.exe -c 10**10**100` process on core no. 8 and start SPE sampling, enable collection of load sampled operations, including atomic operations that return a value to a register. Hint: add `--annotate` or `--disassemble` to `wperf record` command."
+#endif
+        }
     );
     arg_parser_arg_command count_command = arg_parser_arg_command::arg_parser_arg_command(
         L"stat",
         { L"" },
-        L"",
-        L"",
-        COMMAND_CLASS::STAT
+        L"Counting mode, for obtaining aggregate counts of occurrences of special events.",
+        L"wperf stat [-e] [-m] [-t] [-i] [-n] [-c] [-C] [-E] [-k] [--dmc] [-q] [--json] [--output][--config] [--force-lock] --COMMAND[ARGS]",
+        COMMAND_CLASS::STAT,
+        {
+            L"> wperf stat -e inst_spec,vfp_spec,ase_spec,ld_spec -c 0 --timeout 3 Count events `inst_spec`, `vfp_spec`, `ase_spec` and `ld_spec` on core #0 for 3 seconds.",
+            L"> wperf stat -m imix -e l1i_cache -c 7 --timeout 10.5 Count metric `imix` (metric events will be grouped) and additional event `l1i_cache` on core #7 for 10.5 seconds.",
+            L"> wperf stat -m imix -c 1 -t -i 2 -n 3 --timeout 5 Count in timeline mode(output counting to CSV file) metric `imix` 3 times on core #1 with 2 second intervals(delays between counts).Each count will last 5 seconds."
+        }
     );
     arg_parser_arg_command man_command = arg_parser_arg_command::arg_parser_arg_command(
-        L"stat",
+        L"man",
         { L"" },
-        L"",
-        L"",
-        COMMAND_CLASS::MAN
+        L"Plain text information about one or more specified event(s), metric(s), and or group metric(s).",
+        L"wperf man [--json]",
+        COMMAND_CLASS::MAN,
+        {
+        }
     );
 
 #pragma endregion
@@ -344,19 +373,21 @@ class arg_parser
 
     COMMAND_CLASS m_command = COMMAND_CLASS::NO_COMMAND;
     std::vector<arg_parser_arg_command*> m_commands_list = {
-       &list_command,
-       &test_command,
        &help_command,
        &version_command,
-       &detect_command,
        &sample_command,
-       &record_command,
        &count_command,
+       &record_command,
+       &list_command,
+       &test_command,
+       &detect_command,
        &man_command
     };
 
     std::vector<arg_parser_arg*> m_flags_list = {
        &json_opt,
+       &metrics_arg,
+       &events_arg,
        &kernel_opt,
        &force_lock_opt,
        &sample_display_long_opt,
@@ -382,8 +413,6 @@ class arg_parser
        &interval_arg,
        &iteration_arg,
        &dmc_arg,
-       &metrics_arg,
-       &events_arg,
        &extra_args_arg
     };
 
@@ -395,4 +424,5 @@ class arg_parser
 protected:
     void throw_invalid_arg(const std::wstring& arg, const std::wstring& additional_message = L"") const;
 #pragma endregion
-};
+};
+

parser/main.cpp

@@ -38,5 +38,10 @@ int wmain(
 {
     arg_parser parser;
     parser.parse(argc, argv);
-    std::wcout << L"Hello " << (parser.annotate_opt.is_set() ? L"annotate" : L"no annotate") << L" World!\n";
+    if (parser.m_command == COMMAND_CLASS::HELP)
+    {
+        parser.print_help();
+        return 0;
+    }
+    std::wcout << L"Hello " << argv[1]<< (parser.annotate_opt.is_set() ? L"annotate" : L"no annotate") << L" World!\n";
 }