tk/spectre.console
1
0
Fork 0
mirror of https://github.com/nsnail/spectre.console.git synced 2025-04-16 08:52:50 +08:00
Code Issues Packages Projects Releases Wiki Activity

Improve XmlDoc output (#1503)

Browse Source 
* Add command description and examples in XML Output

Closes #1115
This commit is contained in:
Yennefer 2024-03-29 20:30:59 +01:00 committed by GitHub
parent 43f9ae92ad
commit 1a3249cdae
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
11 changed files with 87 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
src/Spectre.Console.Cli/Internal/Commands/XmlDocCommand.cs
View File

@ -84,6 +84,13 @@ internal sealed class XmlDocCommand : Command<XmlDocCommand.Settings>
node.SetNullableAttribute("Settings", command.SettingsType?.FullName); node.SetNullableAttribute("Settings", command.SettingsType?.FullName);
if (!string.IsNullOrWhiteSpace(command.Description))
{
var descriptionNode = doc.CreateElement("Description");
descriptionNode.InnerText = command.Description;
node.AppendChild(descriptionNode);
}
// Parameters // Parameters
if (command.Parameters.Count > 0) if (command.Parameters.Count > 0)
{ {
@ -103,6 +110,27 @@ internal sealed class XmlDocCommand : Command<XmlDocCommand.Settings>
node.AppendChild(CreateCommandNode(doc, childCommand)); node.AppendChild(CreateCommandNode(doc, childCommand));
} }
// Examples
if (command.Examples.Count > 0)
{
var exampleRootNode = doc.CreateElement("Examples");
foreach (var example in command.Examples.SelectMany(static x => x))
{
var exampleNode = CreateExampleNode(doc, example);
exampleRootNode.AppendChild(exampleNode);
}
node.AppendChild(exampleRootNode);
}
return node;
}
private static XmlNode CreateExampleNode(XmlDocument document, string example)
{
var node = document.CreateElement("Example");
node.SetAttribute("commandLine", example);
return node; return node;
} }

2
test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_1.Output.verified.txt
View File

@ -21,6 +21,7 @@
</Parameters> </Parameters>
<!--DOG--> <!--DOG-->
<Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings"> <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
<Description>The dog command.</Description>
<Parameters> <Parameters>
<Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" /> <Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" />
<Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" /> <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />
@ -28,6 +29,7 @@
</Command> </Command>
<!--HORSE--> <!--HORSE-->
<Command Name="horse" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings"> <Command Name="horse" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
<Description>The horse command.</Description>
<Parameters> <Parameters>
<Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" /> <Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" />
<Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" /> <Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" />

26
test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_10.Output.verified.txt Normal file
View File

@ -0,0 +1,26 @@
<?xml version="1.0" encoding="utf-8"?>
<Model>
<!--DOG-->
<Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
<Description>The dog command.</Description>
<Parameters>
<Argument Name="LEGS" Position="0" Required="false" Kind="scalar" ClrType="System.Int32">
<Description>The number of legs.</Description>
<Validators>
<Validator ClrType="Spectre.Console.Tests.Data.EvenNumberValidatorAttribute" Message="Animals must have an even number of legs." />
<Validator ClrType="Spectre.Console.Tests.Data.PositiveNumberValidatorAttribute" Message="Number of legs must be greater than 0." />
</Validators>
</Argument>
<Argument Name="AGE" Position="1" Required="true" Kind="scalar" ClrType="System.Int32" />
<Option Short="a" Long="alive,not-dead" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean">
<Description>Indicates whether or not the animal is alive.</Description>
</Option>
<Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />
<Option Short="n,p" Long="name,pet-name" Value="VALUE" Required="false" Kind="scalar" ClrType="System.String" />
</Parameters>
<Examples>
<Example commandLine="dog -g" />
<Example commandLine="dog --good-boy" />
</Examples>
</Command>
</Model>

1
test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_2.Output.verified.txt
View File

@ -2,6 +2,7 @@
<Model> <Model>
<!--DOG--> <!--DOG-->
<Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings"> <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
<Description>The dog command.</Description>
<Parameters> <Parameters>
<Argument Name="LEGS" Position="0" Required="false" Kind="scalar" ClrType="System.Int32"> <Argument Name="LEGS" Position="0" Required="false" Kind="scalar" ClrType="System.Int32">
<Description>The number of legs.</Description> <Description>The number of legs.</Description>

2
test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_3.Output.verified.txt
View File

@ -16,6 +16,7 @@
</Parameters> </Parameters>
<!--DOG--> <!--DOG-->
<Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings"> <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
<Description>The dog command.</Description>
<Parameters> <Parameters>
<Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" /> <Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" />
<Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" /> <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />
@ -24,6 +25,7 @@
</Command> </Command>
<!--HORSE--> <!--HORSE-->
<Command Name="horse" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings"> <Command Name="horse" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
<Description>The horse command.</Description>
<Parameters> <Parameters>
<Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" /> <Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" />
<Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" /> <Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" />

1
test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_4.Output.verified.txt
View File

@ -16,6 +16,7 @@
</Parameters> </Parameters>
<!--DOG--> <!--DOG-->
<Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings"> <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
<Description>The dog command.</Description>
<Parameters> <Parameters>
<Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" /> <Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" />
<Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" /> <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />

2
test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_6.Output.verified.txt
View File

@ -2,6 +2,7 @@
<Model> <Model>
<!--DEFAULT COMMAND--> <!--DEFAULT COMMAND-->
<Command Name="__default_command" IsBranch="false" IsDefault="true" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings"> <Command Name="__default_command" IsBranch="false" IsDefault="true" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
<Description>The dog command.</Description>
<Parameters> <Parameters>
<Argument Name="LEGS" Position="0" Required="false" Kind="scalar" ClrType="System.Int32"> <Argument Name="LEGS" Position="0" Required="false" Kind="scalar" ClrType="System.Int32">
<Description>The number of legs.</Description> <Description>The number of legs.</Description>
@ -20,6 +21,7 @@
</Command> </Command>
<!--HORSE--> <!--HORSE-->
<Command Name="horse" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings"> <Command Name="horse" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
<Description>The horse command.</Description>
<Parameters> <Parameters>
<Argument Name="LEGS" Position="0" Required="false" Kind="scalar" ClrType="System.Int32"> <Argument Name="LEGS" Position="0" Required="false" Kind="scalar" ClrType="System.Int32">
<Description>The number of legs.</Description> <Description>The number of legs.</Description>

1
test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_7.Output.verified.txt
View File

@ -21,6 +21,7 @@
</Parameters> </Parameters>
<!--__DEFAULT_COMMAND--> <!--__DEFAULT_COMMAND-->
<Command Name="__default_command" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings"> <Command Name="__default_command" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
<Description>The horse command.</Description>
<Parameters> <Parameters>
<Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" /> <Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" />
<Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" /> <Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" />

2
test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_8.Output.verified.txt
View File

@ -16,6 +16,7 @@
</Parameters> </Parameters>
<!--DOG--> <!--DOG-->
<Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings"> <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
<Description>The dog command.</Description>
<Parameters> <Parameters>
<Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" /> <Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" />
<Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" /> <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />
@ -24,6 +25,7 @@
</Command> </Command>
<!--__DEFAULT_COMMAND--> <!--__DEFAULT_COMMAND-->
<Command Name="__default_command" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings"> <Command Name="__default_command" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
<Description>The horse command.</Description>
<Parameters> <Parameters>
<Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" /> <Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" />
<Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" /> <Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" />

2
test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_9.Output.verified.txt
View File

@ -18,6 +18,7 @@
</Parameters> </Parameters>
<!--DOG--> <!--DOG-->
<Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings"> <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
<Description>The dog command.</Description>
<Parameters> <Parameters>
<Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" /> <Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" />
<Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" /> <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />
@ -26,6 +27,7 @@
</Command> </Command>
<!--__DEFAULT_COMMAND--> <!--__DEFAULT_COMMAND-->
<Command Name="__default_command" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings"> <Command Name="__default_command" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
<Description>The horse command.</Description>
<Parameters> <Parameters>
<Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" /> <Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" />
<Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" /> <Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" />

20
test/Spectre.Console.Cli.Tests/Unit/CommandAppTests.Xml.cs
View File

@ -110,6 +110,26 @@ public sealed partial class CommandAppTests
return Verifier.Verify(result.Output); return Verifier.Verify(result.Output);
} }
[Fact]
[Expectation("Test_10")]
public Task Should_Dump_Correct_Model_For_Case_6()
{
// Given
var fixture = new CommandAppTester();
fixture.Configure(config =>
{
config.AddCommand<DogCommand>("dog")
.WithExample("dog -g")
.WithExample("dog --good-boy");
});
// When
var result = fixture.Run(Constants.XmlDocCommand);
// Then
return Verifier.Verify(result.Output);
}
[Fact] [Fact]
[Expectation("Test_6")] [Expectation("Test_6")]
public Task Should_Dump_Correct_Model_For_Model_With_Default_Command() public Task Should_Dump_Correct_Model_For_Model_With_Default_Command()