diff --git a/Coder.Cli/SampleCLI.cs b/Coder.Cli/SampleCLI.cs index 8f3e055c..af5f5585 100644 --- a/Coder.Cli/SampleCLI.cs +++ b/Coder.Cli/SampleCLI.cs @@ -1,4 +1,4 @@ -// Copyright (c) 2023-2026 ktsu-dev contributors +// Copyright (c) 2023-2026 ktsu-dev contributors namespace ktsu.Coder.Cli; @@ -99,7 +99,12 @@ public static void Main(string[] args) #pragma warning restore CA1031 // Do not catch general exception types } - private static FunctionDeclaration CreateSampleFunction() + /// + /// Builds the sample function the CLI demonstrates: calculate_sum(a, b, include_debug), + /// which returns the sum of its two integer arguments. + /// + /// The function declaration. + public static FunctionDeclaration CreateSampleFunction() { FunctionDeclaration function = new("calculate_sum") { @@ -112,7 +117,10 @@ private static FunctionDeclaration CreateSampleFunction() function.Parameters.Add(new Parameter("include_debug", "bool") { IsOptional = true, DefaultValue = Literal.Bool(false) }); // Add function body - function.Body.Add(new ReturnStatement(new AstLeafNode("a + b"))); + // An expression, not text: a string leaf is written as a string literal, so the function + // would return the text "a + b" rather than the sum. + function.Body.Add(new ReturnStatement( + new BinaryExpression(new VariableReference("a"), BinaryOperator.Add, new VariableReference("b")))); return function; } diff --git a/Coder.Test/Cli/SampleFunctionTests.cs b/Coder.Test/Cli/SampleFunctionTests.cs new file mode 100644 index 00000000..3ab92415 --- /dev/null +++ b/Coder.Test/Cli/SampleFunctionTests.cs @@ -0,0 +1,63 @@ +// Copyright (c) 2023-2026 ktsu-dev contributors + +namespace ktsu.Coder.Test.Cli; + +using ktsu.Coder.Ast; +using ktsu.Coder.Cli; +using ktsu.Coder.Languages; +using ktsu.Coder.Serialization; +using Microsoft.VisualStudio.TestTools.UnitTesting; + +/// +/// Tests the sample function demonstrates, which the README shows as the +/// canonical usage example. +/// +[TestClass] +public class SampleFunctionTests +{ + /// + /// Tests that the sample returns the sum of its arguments, not the text "a + b", in every + /// language and after a YAML round-trip. + /// + [TestMethod] + public void SampleFunctionReturnsTheSumNotAString() + { + FunctionDeclaration function = CoderCLI.CreateSampleFunction(); + YamlSerializer serializer = new(); + AstNode? reloaded = new YamlDeserializer().Deserialize(serializer.Serialize(function)); + Assert.IsNotNull(reloaded); + + ILanguageGenerator[] generators = + [ + new PythonGenerator(), + new CSharpGenerator(), + new CppGenerator(), + new JavaScriptGenerator(), + new RustGenerator(), + new GoGenerator(), + new CGenerator(), + ]; + + foreach (ILanguageGenerator generator in generators) + { + foreach (AstNode node in new[] { function, reloaded }) + { + string code = generator.Generate(node); + StringAssert.Contains(code, "a + b", $"{generator.GetType().Name} does not add the arguments:\n{code}"); + Assert.DoesNotContain("\"a + b\"", code, $"{generator.GetType().Name} returns a string literal:\n{code}"); + } + } + } + + /// + /// Tests the Python the README shows for the sample. + /// + [TestMethod] + public void SamplePythonReturnsTheSum() + { + string code = new PythonGenerator().Generate(CoderCLI.CreateSampleFunction()); + + StringAssert.Contains(code, "def calculate_sum(a: int, b: int, include_debug: bool = False) -> int:", StringComparison.Ordinal); + StringAssert.Contains(code, " return (a + b)", StringComparison.Ordinal); + } +} diff --git a/Coder.Test/Coder.Test.csproj b/Coder.Test/Coder.Test.csproj index fa7f8e6a..d9ff1b71 100644 --- a/Coder.Test/Coder.Test.csproj +++ b/Coder.Test/Coder.Test.csproj @@ -27,5 +27,7 @@ + + diff --git a/README.md b/README.md index 02b0de96..c758a5b4 100644 --- a/README.md +++ b/README.md @@ -261,7 +261,8 @@ function.Parameters.Add(new Parameter("debug", "bool") }); // Add function body -function.Body.Add(new ReturnStatement(new AstLeafNode("a + b"))); +function.Body.Add(new ReturnStatement( + new BinaryExpression(new VariableReference("a"), BinaryOperator.Add, new VariableReference("b")))); ``` ### Serializing to YAML @@ -276,21 +277,28 @@ Output: ```yaml functionDeclaration: - name: calculate_sum - returnType: int - parameters: - - name: a - type: int - - name: b - type: int - - name: debug - type: bool - isOptional: true - defaultValue: false - body: - - returnStatement: - expression: - Leaf: a + b + name: calculate_sum + returnType: int + parameters: + - name: a + type: int + - name: b + type: int + - name: debug + type: bool + isOptional: true + defaultValue: "false" + body: + - returnStatement: + expression: + binaryExpression: + left: + variableReference: + name: a + operator: Add + right: + variableReference: + name: b ``` ### Generating Code @@ -305,7 +313,7 @@ Output: ```python def calculate_sum(a: int, b: int, debug: bool = False) -> int: - return "a + b" + return (a + b) ``` ### Round-trip Serialization