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