diff --git a/README.md b/README.md index 0f6a7e1..35b6284 100644 --- a/README.md +++ b/README.md @@ -13,22 +13,15 @@ The experimental [TellC compiler](TellC/README.md) uses LLVM to build native exe ## A first program ```tell -Let name be "Ada". -Let age be 20. - -If age is greater than 18: - Say "Hello, {name}!". - Say "You are an adult.". -Otherwise: - Say "You are still young!". -End if. +Let colleague be "Avery". +Let workspace be "Customer Operations". +Say "Welcome, {colleague}. Your {workspace} workspace is ready.". ``` Output: ```text -Hello, Ada! -You are an adult. +Welcome, Avery. Your Customer Operations workspace is ready. ``` ## Run Tell natively diff --git a/TellC/examples/factorial.tell b/TellC/examples/factorial.tell index 360e726..0bbf0ca 100644 --- a/TellC/examples/factorial.tell +++ b/TellC/examples/factorial.tell @@ -1,3 +1,4 @@ +# Compute a factorial recursively and print the result for a reviewable input. to factorial(number: n) out number: if n <= 1: return 1 diff --git a/TellC/examples/foreign.tell b/TellC/examples/foreign.tell index ef3a2ef..f22aba0 100644 --- a/TellC/examples/foreign.tell +++ b/TellC/examples/foreign.tell @@ -1,5 +1,9 @@ -# Both declarations refer to functions exposed with the C ABI. +# These declarations bind to functions supplied by linked integration libraries. +# The C and Swift symbols must match the libraries' exported ABI exactly. extern c function add(int32 left, int32 right) returns int32 as "c_add" extern swift function double_value(float64 value) returns float64 as "swift_double_value" -let number result be add(2, 3) -say double_value(1.5) + +let number combined_count be add(2, 3) +let decimal adjusted_measurement be double_value(1.5) +say "Combined record count: {combined_count}" +say "Adjusted measurement: {adjusted_measurement}" diff --git a/TellC/examples/objects.tell b/TellC/examples/objects.tell index ded8493..ea215dc 100644 --- a/TellC/examples/objects.tell +++ b/TellC/examples/objects.tell @@ -1,15 +1,16 @@ -object MacBook: +# A private release policy exposed through a strongly typed public method. +object ReleasePolicy: own: - let text self password be "12345678" + let text self approved_environment be "production" others: - to check password(text: Password) out bool: - if Password = password: + to approve_environment(text: candidate_environment) out bool: + if candidate_environment = self.approved_environment: give back true end if give back false end function end object -let MacBook laptop be MacBook() -say laptop.check password("12345678") -say laptop.check password("wrong") +let ReleasePolicy policy be ReleasePolicy() +say policy.approve_environment("production") +say policy.approve_environment("staging") diff --git a/examples/basic_test.tell b/examples/basic_test.tell index 9ccd99e..6ccad76 100644 --- a/examples/basic_test.tell +++ b/examples/basic_test.tell @@ -1,2 +1,4 @@ -Check that 2 plus 2 is equal to 4. -Check that len(["Tell", "tests"]) is equal to 2. +# Minimal assertions for a small project planning workflow. +Let review_items be ["Design review", "Release review"]. +Check that len(review_items) is equal to 2. +Check that 24 times 60 is equal to 1440. diff --git a/examples/compiled-objects.tell b/examples/compiled-objects.tell index e3dd71e..117e2b8 100644 --- a/examples/compiled-objects.tell +++ b/examples/compiled-objects.tell @@ -1,20 +1,22 @@ -Create a class called Animal: - When creating an Animal with name: - Remember name as this.name. +# Inheritance and field updates in a service-request workflow. +Create a class called ServiceRequest: + When creating a ServiceRequest with reference and summary: + Remember reference as this.reference. + Remember summary as this.summary. End constructor. - To speak: - Say "{this.name} makes a sound.". + To describe: + Say "Request {this.reference}: {this.summary}.". End function. End class. -Create a class called Dog based on Animal: - To speak: - Say "Woof, {this.name}!". +Create a class called EscalatedRequest based on ServiceRequest: + To describe: + Say "Escalated request {this.reference}: {this.summary}.". End function. End class. -Let pet as Animal be a new Dog with "Rex". -Tell pet to speak. -Set pet.name to "Milo". -Tell pet to speak. +Let request as ServiceRequest be new EscalatedRequest with "SR-2048" and "Investigate delayed nightly reconciliation". +Tell request to describe. +Set request.summary to "Nightly reconciliation delay assigned to the data platform team". +Tell request to describe. diff --git a/examples/factorial.tell b/examples/factorial.tell index e63b2aa..36b4be3 100644 --- a/examples/factorial.tell +++ b/examples/factorial.tell @@ -1,11 +1,10 @@ -Note: Functions can call themselves, which is called recursion. - -To factorial with number: - If number is at most 1: +# A recursive calculation with a clearly labeled result. +To factorial with value: + If value is at most 1: Give back 1. End if. - Give back number times factorial(number minus 1). + Give back value times factorial(value minus 1). End function. -Let answer be the result of factorial with 6. -Say "6 factorial is {answer}.". +Let result be the result of factorial with 6. +Say "6 factorial is {result}.". diff --git a/examples/features.tell b/examples/features.tell index 4e882fa..6c11c6e 100644 --- a/examples/features.tell +++ b/examples/features.tell @@ -1,35 +1,34 @@ -Note: A small tour of Tell's core features. +# A compact service report using lists, functions, decisions, loops, and math. +Let review_durations be [12, 18, 15, 21, 24]. +Let target_duration be 20. + +To calculate_average(values): + Let total be 0. + For each value in values: + Set total to total plus value. + End loop. + Give back total divided by len(values). +End function. -Let name be "Ada". -Let score be 7. -Let numbers be [2, 4, 6, 8]. +Let average_duration be the result of calculate_average with review_durations. +Say "Average review time: {average_duration} days.". -If score is greater than 5: - Say "Welcome, {name}. Your score is {score}.". +If average_duration is at most target_duration: + Say "The team is meeting the {target_duration}-day target.". Otherwise: - Say "Keep practising, {name}.". + Say "The team is above the {target_duration}-day target.". End if. -Let size be the length of numbers. -Say "The list has {size} items.". - -Add 10 to numbers. -Say numbers. - -For each number in numbers: - Say number times 2. +Let squared_deviation_total be 0. +For each duration in review_durations: + Let difference be duration minus average_duration. + Set squared_deviation_total to squared_deviation_total plus difference times difference. End loop. +Use the math library as maths. +Let standard_deviation be maths.sqrt(squared_deviation_total divided by len(review_durations)). +Say "Variation across reviews: {standard_deviation} days.". + Repeat 3 times: - Say "Loop number {the current repetition number}.". + Say "Quality checkpoint {the current repetition number} recorded.". End repeat. - -To multiply(first, second): - Give back first times second. -End function. - -Let answer be the result of multiply with 6 and 7. -Say "Six times seven is {answer}.". - -Use the math library as maths. -Say maths.sqrt(81). diff --git a/examples/guessing_game.tell b/examples/guessing_game.tell index 9cb314b..b19f13a 100644 --- a/examples/guessing_game.tell +++ b/examples/guessing_game.tell @@ -1,18 +1,19 @@ -Note: A tiny number guessing game. The answer is fixed to keep the example predictable. - -Let secret be 7. +# A deterministic input exercise; the fixed value makes each run reproducible. +Let reference_value be 7. Let guess be 0. +Let attempts be 0. -While guess is not equal to secret: - Ask "Guess a number from 1 to 10: " and save the answer as raw_guess. +Say "Reference value exercise: enter a number from 1 to 10.". +While guess is not equal to reference_value: + Ask "Your entry: " and save the answer as raw_guess. Set guess to number(raw_guess). - If guess is less than secret: - Say "Too low. Try again.". - Otherwise: - If guess is greater than secret: - Say "Too high. Try again.". - End if. + Set attempts to attempts plus 1. + + If guess is less than reference_value: + Say "The entry is below the reference value. Try again.". + Otherwise if guess is greater than reference_value: + Say "The entry is above the reference value. Try again.". End if. End while. -Say "You got it!". +Say "Correct. Confirmation completed after {attempts} entries.". diff --git a/examples/hello.tell b/examples/hello.tell index 8a42ca3..afade28 100644 --- a/examples/hello.tell +++ b/examples/hello.tell @@ -1,4 +1,4 @@ -Note: Your first Tell program. - -Let name be "world". -Say "Hello, {name}!". +# A concise welcome message for a new project workspace. +Let colleague be "Avery". +Let workspace be "Customer Operations". +Say "Welcome, {colleague}. Your {workspace} workspace is ready.". diff --git a/examples/javascript_interop.tell b/examples/javascript_interop.tell index 6c0193b..a70bc31 100644 --- a/examples/javascript_interop.tell +++ b/examples/javascript_interop.tell @@ -1,9 +1,11 @@ -# Node.js must be installed and available on PATH. +# Requires Node.js on PATH and the node:path module. Use the JavaScript library called node:path as paths. -Let file be "/projects/tell/main.js". -Say paths.basename(file). -Say paths.extname(file). -# Named arguments are passed to JavaScript as a final options object. -Let formatted be paths.format(dir="/tmp", name="main", ext=".js"). -Say formatted. \ No newline at end of file +Let release_directory be "/srv/apps/atlas/releases/2.4.0". +Let manifest_path be "/srv/apps/atlas/releases/2.4.0/manifest.json". +Say "Release manifest: {paths.basename(manifest_path)}". +Say "File type: {paths.extname(manifest_path)}". + +# Named arguments are sent to JavaScript as a final options object. +Let generated_path be paths.format(dir=release_directory, name="manifest", ext=".json"). +Say "Generated path: {generated_path}". diff --git a/examples/language-core.tell b/examples/language-core.tell index 08606b8..e8c4983 100644 --- a/examples/language-core.tell +++ b/examples/language-core.tell @@ -1,15 +1,18 @@ -To greet with person and greeting: - Give back "{greeting}, {person}.". +# Demonstrates Unicode identifiers, named arguments, and short-circuit logic. +To format_status with owner and status: + Give back "{owner}: {status}.". End function. -Let constant hello_prefix as text be "Hello". -Let café as number be 2. +Let constant service_name as text be "Customer Portal". +Let évaluations as number be 2. + +# The second operand is intentionally unsafe; short-circuiting keeps it unevaluated. If false and (1 divided by 0 is equal to 0): Say "This branch should not run.". -Otherwise if café is equal to 2: - Say greet(person="Ada", greeting=hello_prefix). +Otherwise if évaluations is equal to 2: + Say format_status(owner="Customer Operations", status="Ready for review"). Otherwise: - Say "The value was unexpected.". + Say "The review count needs attention.". End if. -Say "Unicode value: {café}.". +Say "Service: {service_name}; completed evaluations: {évaluations}.". diff --git a/examples/module_helpers.tell b/examples/module_helpers.tell index 9533b90..8bd16dd 100644 --- a/examples/module_helpers.tell +++ b/examples/module_helpers.tell @@ -1,3 +1,4 @@ -To double(value): - Give back value times 2. +# Shared pricing calculation used by modules.tell. +To calculate_line_total(unit_rate, quantity): + Give back unit_rate times quantity. End function. diff --git a/examples/modules.tell b/examples/modules.tell index 5e0af5b..619f77e 100644 --- a/examples/modules.tell +++ b/examples/modules.tell @@ -1,2 +1,7 @@ -Use the module "module_helpers.tell" as helpers. -Say helpers.double(21). +# Reuse a pricing helper from a neighboring Tell module. +Use the module "module_helpers.tell" as pricing. + +Let hourly_rate be 125. +Let billable_hours be 6. +Let service_total be pricing.calculate_line_total(hourly_rate, billable_hours). +Say "Estimated service total: ${service_total}.". diff --git a/examples/python_interop.tell b/examples/python_interop.tell index 323f21e..67705ff 100644 --- a/examples/python_interop.tell +++ b/examples/python_interop.tell @@ -1,7 +1,7 @@ -# This example needs Python available to the runtime. +# Requires Python and the standard-library statistics module. Use the Python library called statistics as stats. -Let scores be [12, 18, 24, 30]. -Say "Mean: {stats.mean(scores)}". -Say "Population standard deviation: {stats.pstdev(scores)}". -Say "Named argument: {stats.fmean(data=scores)}". +Let weekly_ticket_counts be [42, 47, 51, 45, 55]. +Say "Weekly average: {stats.mean(weekly_ticket_counts)} tickets.". +Say "Population standard deviation: {stats.pstdev(weekly_ticket_counts)} tickets.". +Say "Named-argument average: {stats.fmean(data=weekly_ticket_counts)} tickets.". diff --git a/examples/sets.tell b/examples/sets.tell index 148a87a..fc8732d 100644 --- a/examples/sets.tell +++ b/examples/sets.tell @@ -1,14 +1,20 @@ -Let languages as set be {"Tell", "Go", "Python", "Tell"}. -Say languages. -Say "Go" is in languages. +# Set operations can help compare a planned rollout with approved regions. +Let approved_regions as set be {"ap-south-1", "eu-west-1", "us-east-1"}. +Let requested_regions as set be {"ap-south-1", "ca-central-1"}. -Let compiled_languages be union(languages, set(["C#", "Java"])). -Say compiled_languages. -Say intersection(languages, set(["Go", "Rust"])). -Say difference(languages, set(["Python"])). +Let all_reviewed_regions be union(approved_regions, requested_regions). +Let ready_regions be intersection(approved_regions, requested_regions). +Let regions_needing_approval be difference(requested_regions, approved_regions). +Let canada_in_review be "ca-central-1" is in all_reviewed_regions. +Let asia_approved be "ap-south-1" is in ready_regions. +Let canada_needs_approval be "ca-central-1" is in regions_needing_approval. -Add "C#" to languages. -Remove "Go" from languages. -For each language in languages: - Say language. -End loop. +Say "The requested rollout includes {len(requested_regions)} regions.". +Say "Canada is included in the review set: {canada_in_review}.". +Say "The rollout has an approved region: {asia_approved}.". +Say "A new approval is required for Canada: {canada_needs_approval}.". + +Add "ca-central-1" to approved_regions. +Remove "eu-west-1" from approved_regions. +Let canada_is_enabled be "ca-central-1" is in approved_regions. +Say "After the approval update, Canada is enabled: {canada_is_enabled}.". diff --git a/examples/tuples.tell b/examples/tuples.tell index a3a1183..7c748e4 100644 --- a/examples/tuples.tell +++ b/examples/tuples.tell @@ -1,12 +1,15 @@ -Let first, second be ("Ada", 42). -Say [first, second]. +# Tuples keep related release metadata together in a fixed order. +Let change_id, owning_team, priority be ("CHG-2048", "Data Services", 2). +Say "Change {change_id} is owned by {owning_team} at priority {priority}.". -Let values be (1, 2, 3). -Say values. -Say values[::-1]. -For each value in values: - Say value. +Let release_stages be ("draft", "review", "approved"). +Say "Planned stages: {release_stages}.". +Say "Reverse audit view: {release_stages[::-1]}.". + +For each stage in release_stages: + Say "Release stage: {stage}.". End loop. -Let label as tuple be tuple(["readable", "portable"]). -Say label plus ("language",). +Let sign_off_roles as tuple be tuple(["Security", "Operations", "Service owner"]). +Let complete_sign_off be sign_off_roles plus ("Release manager",). +Say "Required sign-offs: {complete_sign_off}.". diff --git a/native/internal/tell/tell_test.go b/native/internal/tell/tell_test.go index df5348c..1c006ba 100644 --- a/native/internal/tell/tell_test.go +++ b/native/internal/tell/tell_test.go @@ -182,7 +182,7 @@ func TestModuleExampleRuns(t *testing.T) { if err := RunWithIO(string(source), filename, bytes.NewReader(nil), &output); err != nil { t.Fatal(err) } - if got, want := output.String(), "42\n"; got != want { + if got, want := output.String(), "Estimated service total: $750.\n"; got != want { t.Fatalf("module example output = %q, want %q", got, want) } } diff --git a/tests/test_tell.py b/tests/test_tell.py index 0c33020..95b7b6c 100644 --- a/tests/test_tell.py +++ b/tests/test_tell.py @@ -340,7 +340,7 @@ def test_module_example_executes(self): output = io.StringIO() interpreter = Interpreter(output_fn=lambda text: output.write(text + "\n")) interpreter.run(filename.read_text(encoding="utf-8"), str(filename)) - self.assertEqual(output.getvalue(), "42\n") + self.assertEqual(output.getvalue(), "Estimated service total: $750.\n") def test_check_that_assertion_passes_and_fails(self): Interpreter().run("Check that 2 plus 2 is equal to 4.")