From 5c936c1e65ec4f6ba5428433a36d9cb3ee06764d Mon Sep 17 00:00:00 2001 From: mgrojo Date: Wed, 20 Sep 2023 23:45:31 +0200 Subject: [PATCH] Support for markdown output in help messages Users of CLIC can use this functionality to provide on-line versions of the help messages. --- example/src/clic_ex-commands-subsub.adb | 10 +++--- example/src/clic_ex-commands.adb | 20 +++++++++-- example/src/clic_ex-commands.ads | 12 +++---- src/clic-config.ads | 2 +- src/clic-formatter.adb | 44 +++++++++++++++++++++++++ src/clic-formatter.ads | 22 +++++++++++++ src/clic-markdown.adb | 19 +++++++++++ src/clic-markdown.ads | 12 +++++++ src/clic-subcommand-instance.adb | 2 +- src/clic-subcommand-instance.ads | 6 ++-- src/clic-subcommand.ads | 2 +- src/clic-tty.ads | 2 +- 12 files changed, 133 insertions(+), 20 deletions(-) create mode 100644 src/clic-formatter.adb create mode 100644 src/clic-formatter.ads create mode 100644 src/clic-markdown.adb create mode 100644 src/clic-markdown.ads diff --git a/example/src/clic_ex-commands-subsub.adb b/example/src/clic_ex-commands-subsub.adb index 714e994..77b2fd3 100644 --- a/example/src/clic_ex-commands-subsub.adb +++ b/example/src/clic_ex-commands-subsub.adb @@ -23,11 +23,11 @@ package body CLIC_Ex.Commands.Subsub is Put_Line => Ada.Text_IO.Put_Line, Put_Error => Ada.Text_IO.Put_Line, Error_Exit => GNAT.OS_Lib.OS_Exit, - TTY_Chapter => CLIC.TTY.Info, - TTY_Description => CLIC.TTY.Description, - TTY_Version => CLIC.TTY.Version, - TTY_Underline => CLIC.TTY.Underline, - TTY_Emph => CLIC.TTY.Emph); + TTY_Chapter => CLIC.Formatter.Chapter, + TTY_Description => CLIC.Formatter.Description, + TTY_Version => CLIC.Formatter.Version, + TTY_Underline => CLIC.Formatter.Underline, + TTY_Emph => CLIC.Formatter.Emph); begin Sub.Register (new Sub.Builtin_Help); Sub.Register (new CLIC_Ex.Commands.TTY.Instance); diff --git a/example/src/clic_ex-commands.adb b/example/src/clic_ex-commands.adb index 247d6a2..7552c48 100644 --- a/example/src/clic_ex-commands.adb +++ b/example/src/clic_ex-commands.adb @@ -1,6 +1,6 @@ with AAA.Strings; -with CLIC.TTY; +with CLIC.Formatter; with CLIC.User_Input; with CLIC.Config.Load; @@ -22,6 +22,9 @@ package body CLIC_Ex.Commands is No_TTY : aliased Boolean := False; -- Used to disable control characters in output + Markdown_Help : aliased Boolean := False; + -- Used to enable help display in markdown format + ------------------------- -- Set_Global_Switches -- ------------------------- @@ -50,6 +53,13 @@ package body CLIC_Ex.Commands is No_TTY'Access, Long_Switch => "--no-tty", Help => "Disables control characters in output"); + + Define_Switch (Config, + Markdown_Help'Access, + Long_Switch => "--markdown", + Help => + "Enables output of markdown format for help"); + end Set_Global_Switches; ------------- @@ -61,11 +71,15 @@ package body CLIC_Ex.Commands is Sub_Cmd.Parse_Global_Switches; if No_TTY then - CLIC.TTY.Force_Disable_TTY; + CLIC.Formatter.Force_Disable_TTY; + end if; + + if Markdown_Help then + CLIC.Formatter.Enable_Markdown; end if; if not No_Color and then not No_TTY then - CLIC.TTY.Enable_Color (Force => False); + CLIC.Formatter.Enable_Color (Force => False); -- This may still not enable color if TTY is detected to be incapable end if; diff --git a/example/src/clic_ex-commands.ads b/example/src/clic_ex-commands.ads index a670a07..e79a83b 100644 --- a/example/src/clic_ex-commands.ads +++ b/example/src/clic_ex-commands.ads @@ -2,7 +2,7 @@ private with Ada.Text_IO; private with GNAT.OS_Lib; private with CLIC.Subcommand.Instance; -private with CLIC.TTY; +private with CLIC.Formatter; private with CLIC.Config; package CLIC_Ex.Commands is @@ -24,9 +24,9 @@ private Put_Line => Ada.Text_IO.Put_Line, Put_Error => Ada.Text_IO.Put_Line, Error_Exit => GNAT.OS_Lib.OS_Exit, - TTY_Chapter => CLIC.TTY.Info, - TTY_Description => CLIC.TTY.Description, - TTY_Version => CLIC.TTY.Version, - TTY_Underline => CLIC.TTY.Underline, - TTY_Emph => CLIC.TTY.Emph); + TTY_Chapter => CLIC.Formatter.Chapter, + TTY_Description => CLIC.Formatter.Description, + TTY_Version => CLIC.Formatter.Version, + TTY_Underline => CLIC.Formatter.Underline, + TTY_Emph => CLIC.Formatter.Emph); end CLIC_Ex.Commands; diff --git a/src/clic-config.ads b/src/clic-config.ads index 0da736c..7705a61 100644 --- a/src/clic-config.ads +++ b/src/clic-config.ads @@ -29,7 +29,7 @@ package CLIC.Config with Preelaborate is access function (Key : Config_Key; Value : TOML.TOML_Value) return Boolean; -- Return False when a Key/Value combination is not valid. Can be used to - -- check formating of string value like email address for instance. + -- check formatting of string value like email address for instance. procedure Import (This : in out Instance; Table : TOML.TOML_Value; diff --git a/src/clic-formatter.adb b/src/clic-formatter.adb new file mode 100644 index 0000000..ff82702 --- /dev/null +++ b/src/clic-formatter.adb @@ -0,0 +1,44 @@ +with CLIC.TTY; +with CLIC.Markdown; + +package body CLIC.Formatter is + + Markdown_Enabled : Boolean := False; + + procedure Enable_Markdown is + begin + Markdown_Enabled := True; + end Enable_Markdown; + + procedure Force_Disable_TTY renames TTY.Force_Disable_TTY; + procedure Enable_Color (Force : Boolean := False) + renames TTY.Enable_Color; + + function Chapter (Str : String) return String is + (if Markdown_Enabled + then Markdown.Chapter (Str) + else TTY.Bold (Str)); + + + function Description (Str : String) return String is + (if Markdown_Enabled + then Markdown.Code (Str) + else TTY.Description (Str)); + + function Version (Str : String) return String is + (if Markdown_Enabled + then Markdown.Italic (Str) + else TTY.Version (Str)); + + function Underline (Str : String) return String is + (if Markdown_Enabled + then Markdown.Bold (Str) + else TTY.Underline (Str)); + + function Emph (Str : String) return String is + (if Markdown_Enabled + then Markdown.Code (Str) + else TTY.Emph (Str)); + + +end CLIC.Formatter; diff --git a/src/clic-formatter.ads b/src/clic-formatter.ads new file mode 100644 index 0000000..1abccf7 --- /dev/null +++ b/src/clic-formatter.ads @@ -0,0 +1,22 @@ +package CLIC.Formatter +with Preelaborate +is + + -- Provides markdown or TTY formatting for displaying help pages. + + procedure Force_Disable_TTY; + + procedure Enable_Markdown; + -- Enables markdown output of formatting functions. + + procedure Enable_Color (Force : Boolean := False); + -- Prepares colors for the terminal output. Unless Force, will do nothing + -- if a console redirection is detected. + + function Chapter (Str : String) return String; + function Description (Str : String) return String; + function Version (Str : String) return String; + function Underline (Str : String) return String; + function Emph (Str : String) return String; + +end CLIC.Formatter; diff --git a/src/clic-markdown.adb b/src/clic-markdown.adb new file mode 100644 index 0000000..3a6dec3 --- /dev/null +++ b/src/clic-markdown.adb @@ -0,0 +1,19 @@ + +package body CLIC.Markdown is + + function Chapter (Str : String) return String is + ("## " & Str); + + function Plain_Text (Str : String) return String is + (Str); + + function Code (Str : String) return String is + ('`' & Str & '`'); + + function Bold (Str : String) return String is + ('*' & Str & '*'); + + function Italic (Str : String) return String is + ('_' & Str & '_'); + +end CLIC.Markdown; diff --git a/src/clic-markdown.ads b/src/clic-markdown.ads new file mode 100644 index 0000000..8d79e22 --- /dev/null +++ b/src/clic-markdown.ads @@ -0,0 +1,12 @@ + +package CLIC.Markdown +with Preelaborate +is + + function Chapter (Str : String) return String; + function Plain_Text (Str : String) return String; + function Code (Str : String) return String; + function Bold (Str : String) return String; + function Italic (Str : String) return String; + +end CLIC.Markdown; diff --git a/src/clic-subcommand-instance.adb b/src/clic-subcommand-instance.adb index 6646c2b..49bd274 100644 --- a/src/clic-subcommand-instance.adb +++ b/src/clic-subcommand-instance.adb @@ -494,7 +494,7 @@ package body CLIC.Subcommand.Instance is Table.Append (TTY_Description ("")); Table.Append ("List of arguments for the command"); - Table.Print (Separator => " ", + Table.Print (Separator => " ", Put_Line => Put_Line_For_Access'Access); end; diff --git a/src/clic-subcommand-instance.ads b/src/clic-subcommand-instance.ads index 1bf03cc..5bb0786 100644 --- a/src/clic-subcommand-instance.ads +++ b/src/clic-subcommand-instance.ads @@ -20,8 +20,10 @@ generic -- Used to signal that the program should terminate with the give error -- code. Typicaly use GNAT.OS_Lib.OS_Exit. - -- The procedures below are used to format the output such as usage and - -- help. Use CLIC.Subcommand.No_TTY if you don't want or need formating. + -- The functions below are used to format the output such as usage and + -- help. Use CLIC.Subcommand.No_TTY if you don't want or need formatting. + -- CLIC also provides ready implementations in CLIC.Formatter, CLIC.TTY + -- and CLIC.Markdown. with function TTY_Chapter (Str : String) return String; with function TTY_Description (Str : String) return String; with function TTY_Version (Str : String) return String; diff --git a/src/clic-subcommand.ads b/src/clic-subcommand.ads index 105db56..1e42c9c 100644 --- a/src/clic-subcommand.ads +++ b/src/clic-subcommand.ads @@ -165,7 +165,7 @@ package CLIC.Subcommand is function No_TTY (Str : String) return String is (Str); -- Use this function for the TTY_* generic parameters of - -- CLIC.Subcommand.Instance if you don't want or need TTY formating. + -- CLIC.Subcommand.Instance if you don't want or need TTY formatting. private diff --git a/src/clic-tty.ads b/src/clic-tty.ads index d577a8b..5940920 100644 --- a/src/clic-tty.ads +++ b/src/clic-tty.ads @@ -19,7 +19,7 @@ is procedure Force_Disable_TTY with Post => not Is_TTY; - -- Disable TTY support even if availabe + -- Disable TTY support even if available -------------------- -- Color enabling --