Merge pull request 'tampio_examples' (#4) from tampio_examples into main

Reviewed-on: http://localhost:44481/katariina-jarvenmaki/Tampiorama/pulls/4

README.md

@@ -17,14 +17,21 @@ make
 Then serve locally and open in your browser:
 
 ```sh
-python3 -m http.server 9994 --directory examples/basics
+python3 -m http.server 9994 --directory examples
 ```
 
+Open `http://localhost:9994/basics/index.html` for the full example index, or go directly:
+
 | URL | What it does |
 |-----|-------------|
-| `http://localhost:9994/hello.html` | Alerts "Hei maailma!" on load |
-| `http://localhost:9994/factorial.html` | Prompts for n, displays n! |
-| `http://localhost:9994/fibonacci.html` | Prompts for n, displays fib(n) |
+| `http://localhost:9994/basics/hello.html` | Alerts "Hei maailma!" on load |
+| `http://localhost:9994/basics/factorial.html` | Prompts for n, displays n! |
+| `http://localhost:9994/basics/fibonacci.html` | Prompts for n, displays fib(n) |
+| `http://localhost:9994/data-structures/lista.html` | List sorted ascending and descending |
+| `http://localhost:9994/data-structures/vektori.html` | Custom class, Euclidean length of [3,4] = 5 |
+| `http://localhost:9994/strings/merkkijono.html` | String length, concat, trim, split |
+| `http://localhost:9994/async/nappi.html` | Click handlers, mutable counter |
+| `http://localhost:9994/program/kasvutaulukko.html` | Factorial + Fibonacci table, interactive prompt |
 
 ## What is Tampio?
 
@@ -46,10 +53,10 @@ See [`docs/cheatsheet.md`](docs/cheatsheet.md) for a map of Finnish grammatical
 | Directory | Contents |
 |-----------|----------|
 | `examples/basics/` | Hello world, factorial, Fibonacci |
-| `examples/data-structures/` | Lists, maps |
-| `examples/strings/` | String manipulation |
-| `examples/async/` | Promise / async usage |
-| `examples/program/` | A small complete program |
+| `examples/data-structures/` | Built-in list operations, custom class |
+| `examples/strings/` | String length, concat, trim, split |
+| `examples/async/` | DOM click handlers, mutable state |
+| `examples/program/` | Capstone combining recursion, lists, and click events |
 
 ## Local Setup (without Docker)
 

examples/async/nappi.itp

@@ -0,0 +1,29 @@
+# Nappi — DOM Events and State in Tampio
+#
+# Tampio handles async interactions through DOM event handlers.
+# The key pattern is "X:tä painettaessa käyköön niin, että ..."
+# which attaches a click handler to a button element.
+#
+# State is stored in a "muuttuja" (variable object with an "arvo" field).
+# "kasvatetaan yhdellä" increments the stored value in place.
+# "näytetään käyttäjälle" writes the current value to the page output.
+#
+# DOM utilities:
+#   etsii elementin nimellä "id" tuloksenaan X  = document.getElementById
+#   kirjoitetaan koodi "html"                    = element.innerHTML =
+#   pyyhitään                                    = element.innerHTML = ""
+
+# Global counter — persists across button clicks
+Olkoon kiva laskuri uusi muuttuja, jonka arvo on nolla.
+
+Kun nykyinen sivu avautuu,
+	nykyinen sivu etsii elementin nimellä "output" tuloksenaan kiva alue,
+	kivalle alueelle kirjoitetaan koodi "<p><button id='natti'>+1</button> <button id='hieno'>+10</button></p>",
+	nykyinen sivu etsii elementin nimellä "natti" tuloksenaan nätti nappi,
+	nykyinen sivu etsii elementin nimellä "hieno" tuloksenaan hieno nappi,
+	nättiä nappia painettaessa käyköön niin, että
+			kivan laskurin arvoa kasvatetaan yhdellä
+		ja	kivan laskurin arvo näytetään käyttäjälle
+ja	hienoa nappia painettaessa käyköön niin, että
+			kivan laskurin arvoa kasvatetaan kymmenellä
+		ja	kivan laskurin arvo näytetään käyttäjälle.

examples/basics/index.itp

@@ -26,9 +26,29 @@
 # Addition uses illative case: lisättynä kaniin
 # n-2 computed by chaining: edeltäjän edeltäjä
 
+# Lista — List Operations
+#
+# Built-in lista type: size, first element, iteration,
+# ascending and descending sort.
+
+# Vektori — Custom Class
+#
+# User-defined class with fields and recursive methods.
+# Euclidean length of vector [3,4] = 5.
+
+# Merkkijono — Strings
+#
+# Length, concatenation, trim, and comma-split.
+
+# Nappi — DOM Events
+#
+# Click handlers with "X:tä painettaessa käyköön niin, että".
+# Mutable counter state persists across button clicks.
+
 Kun nykyinen sivu avautuu,
 	nykyinen sivu näyttää tekstin "<h1>Tampiorama</h1>",
 	nykyinen sivu näyttää tekstin "<p>Annotated examples for <a href='https://github.com/fergusq/tampio'>Tampio</a>, a natural-language OOP language using Finnish grammar that compiles to JavaScript.</p>",
+	nykyinen sivu näyttää tekstin "<h2>Basics</h2>",
 	nykyinen sivu näyttää tekstin "<h3><a href='hello.html'>Hei maailma →</a></h3>",
 	nykyinen sivu näyttää tekstin "<p>Hello world. Page-load entry point, browser alert.</p>",
 	nykyinen sivu näyttää tekstin "<p><em>Open the page — it will alert 'Hei maailma!' immediately.</em></p>",
@@ -36,5 +56,24 @@ Kun nykyinen sivu avautuu,
 	nykyinen sivu näyttää tekstin "<p>Recursive factorial. Ternary branching, adessive multiplication.</p>",
 	nykyinen sivu näyttää tekstin "<p><em>Open the page — enter a number when prompted, e.g. 5, and see 120.</em></p>",
 	nykyinen sivu näyttää tekstin "<h3><a href='fibonacci.html'>Fibonacci-kani →</a></h3>",
-	nykyinen sivu näyttää tekstin "<p>Recursive Fibonacci. Illative addition, predecessor chaining.</p>"
-ja	nykyinen sivu näyttää tekstin "<p><em>Open the page — enter a number when prompted, e.g. 10, and see 55.</em></p>".
+	nykyinen sivu näyttää tekstin "<p>Recursive Fibonacci. Illative addition, predecessor chaining.</p>",
+	nykyinen sivu näyttää tekstin "<p><em>Open the page — enter a number when prompted, e.g. 10, and see 55.</em></p>",
+	nykyinen sivu näyttää tekstin "<h2>Data Structures</h2>",
+	nykyinen sivu näyttää tekstin "<h3><a href='../data-structures/lista.html'>Lista →</a></h3>",
+	nykyinen sivu näyttää tekstin "<p>Built-in list: size, first element, ascending and descending sort.</p>",
+	nykyinen sivu näyttää tekstin "<p><em>Open the page — see the list [3,1,4,1,5] sorted both ways.</em></p>",
+	nykyinen sivu näyttää tekstin "<h3><a href='../data-structures/vektori.html'>Vektori →</a></h3>",
+	nykyinen sivu näyttää tekstin "<p>Custom class with fields and recursive methods. Euclidean length of [3,4] = 5.</p>",
+	nykyinen sivu näyttää tekstin "<p><em>Open the page — see dimension, sum, and Euclidean length of vector [3,4].</em></p>",
+	nykyinen sivu näyttää tekstin "<h2>Strings</h2>",
+	nykyinen sivu näyttää tekstin "<h3><a href='../strings/merkkijono.html'>Merkkijono →</a></h3>",
+	nykyinen sivu näyttää tekstin "<p>String length, concatenation, trim, and comma-split iteration.</p>",
+	nykyinen sivu näyttää tekstin "<p><em>Open the page — see string ops applied to 'Hei, Tampio!'.</em></p>",
+	nykyinen sivu näyttää tekstin "<h2>Async / Events</h2>",
+	nykyinen sivu näyttää tekstin "<h3><a href='../async/nappi.html'>Nappi →</a></h3>",
+	nykyinen sivu näyttää tekstin "<p>DOM click handlers. Mutable counter state persists across button clicks.</p>",
+	nykyinen sivu näyttää tekstin "<p><em>Open the page — click +1 or +10 and watch the counter update.</em></p>",
+	nykyinen sivu näyttää tekstin "<h2>Program</h2>",
+	nykyinen sivu näyttää tekstin "<h3><a href='../program/kasvutaulukko.html'>Kasvutaulukko →</a></h3>",
+	nykyinen sivu näyttää tekstin "<p>Capstone: recursive functions, list iteration, and a click handler together.</p>"
+ja	nykyinen sivu näyttää tekstin "<p><em>Open the page — see factorial and Fibonacci for n=1..7, then enter any n for both values.</em></p>".

examples/data-structures/lista.itp

@@ -0,0 +1,37 @@
+# Lista — List Operations in Tampio
+#
+# "lista" is Tampio's built-in ordered collection type.
+# Its internal field "alkio" holds the elements as an array.
+#
+# Key methods:
+#   koko              = size of the list
+#   ensimmäinen alkio = first element (ordinal subscript)
+#   jokainen alkio    = iterate all elements (like forEach)
+#   järjestetään      = sort ascending in place
+#   järjestetään laskevaan suuruusjärjestykseen = sort descending
+
+# Initialize with the first five digits of pi: 3, 1, 4, 1, 5
+# "jonka alkioita ovat" = "whose elements are" (partitive plural)
+# "eikä muuta" closes a single-item or final-item list
+
+Olkoon kiva lista uusi lista, jonka alkioita ovat kolme, yksi, neljä, yksi ja viisi eikä muuta.
+
+# "jokainen alkio" in array subscript position = forEach
+# "koko" = length, "ensimmäinen alkio" = first element
+
+Kun nykyinen sivu avautuu,
+	nykyinen sivu näyttää tekstin "<p>Lista: ",
+	nykyinen sivu näyttää kivan listan jokaisen alkion,
+	nykyinen sivu näyttää tekstin "</p><p>Koko: ",
+	nykyinen sivu näyttää kivan listan koon,
+	nykyinen sivu näyttää tekstin "</p><p>Ensimmäinen alkio: ",
+	nykyinen sivu näyttää kivan listan ensimmäisen alkion,
+	nykyinen sivu näyttää tekstin "</p>",
+	kiva lista järjestetään,
+	nykyinen sivu näyttää tekstin "<p>Nousevassa järjestyksessä: ",
+	nykyinen sivu näyttää kivan listan jokaisen alkion,
+	nykyinen sivu näyttää tekstin "</p>",
+	kiva lista järjestetään laskevaan suuruusjärjestykseen,
+	nykyinen sivu näyttää tekstin "<p>Laskevassa järjestyksessä: ",
+	nykyinen sivu näyttää kivan listan jokaisen alkion
+ja	nykyinen sivu näyttää tekstin "</p>".

examples/data-structures/vektori.itp

@@ -0,0 +1,60 @@
+# Vektori — Custom Data Structure in Tampio
+#
+# Defines a "vektori" (vector) class with fields and computed methods.
+# This example shows Tampio's OOP model:
+#   class declaration  → "[name/adessive] on [fields]"
+#   field access       → "[object/genitive] [field]"  (same syntax as function call)
+#   recursive methods  → ternary base case + recursive step
+#
+# Using vector [3, 4] — its Euclidean length is exactly 5 (3-4-5 right triangle).
+
+# Class declaration: adessive case marks the class name
+# "komponentit" is plural → stored as an array
+
+Vektorilla on komponentit.
+
+# "dimensio" = number of components
+# "sen" = genitive of "se" (the unnamed parameter = self)
+# "komponenttien määrä" = count of the elements array
+
+Vektorin dimensio on sen komponenttien määrä.
+
+# "pää" = head (first element)
+# "häntä" = tail (new vektori from index 2 onward)
+# "toisesta alkaen" = slice starting from the second element
+
+Vektorin pää on sen ensimmäinen komponentti.
+Vektorin häntä on uusi vektori, jonka komponentit ovat sen komponentit toisesta alkaen.
+
+# Recursive sum: base case 0 when empty, otherwise head + tail's sum
+# "lisättynä ... summaan" = added to ... sum (illative case)
+
+Vektorin summa on
+	riippuen siitä, onko sen dimensio nolla,
+	joko nolla
+	tai sen pää lisättynä sen hännän summaan.
+
+# Euclidean length: sqrt(x1^2 + x2^2 + ...)
+# "toinen potenssi" = squared (array subscript syntax: potenssi[2])
+# Operator chain without separator = innermost grouping:
+#   (head^2 + tail.length^2).sqrt()
+
+Vektorin pituus on
+	riippuen siitä, onko sen dimensio nolla,
+	joko nolla
+	tai sen pään toisen potenssin
+			lisättynä sen hännän pituuden toiseen potenssiin
+		neliöjuuri.
+
+# Vector [3, 4]: sum = 7, length = sqrt(9+16) = 5
+
+Olkoon kiva vektori uusi vektori, jonka komponentteja ovat kolme ja neljä eikä muuta.
+
+Kun nykyinen sivu avautuu,
+	nykyinen sivu näyttää tekstin "<p>Dimensio: ",
+	nykyinen sivu näyttää kivan vektorin dimension,
+	nykyinen sivu näyttää tekstin "</p><p>Summa: ",
+	nykyinen sivu näyttää kivan vektorin summan,
+	nykyinen sivu näyttää tekstin "</p><p>Pituus (3-4-5 kolmio → 5): ",
+	nykyinen sivu näyttää kivan vektorin pituuden
+ja	nykyinen sivu näyttää tekstin "</p>".

examples/program/kasvutaulukko.itp

@@ -0,0 +1,55 @@
+# Kasvutaulukko — Growth Comparison
+#
+# Combines recursive methods, list iteration, and a click handler
+# in a single program.
+#
+# Page load: computes factorial and Fibonacci for n = 1..7 by
+# iterating the same lista twice — once with kertoma, once with kani.
+#
+# Button: prompts for any n, then shows its factorial and Fibonacci
+# as two sequential alerts.
+#
+# Concepts in use:
+#   kertoma        — recursive factorial  (from basics/factorial.itp)
+#   kani           — recursive Fibonacci  (from basics/fibonacci.itp)
+#   lista          — built-in list type   (from data-structures/lista.itp)
+#   jokainen alkio — forEach iterator     (from data-structures/lista.itp)
+#   käyköön niin, että — click handler   (from async/nappi.itp)
+
+# --- Recursive definitions ---
+
+Pienen luvun kertoma on
+	riippuen siitä, onko se pienempi tai yhtä suuri kuin yksi,
+	joko yksi
+	tai pieni luku kerrottuna pienen luvun edeltäjän kertomalla.
+
+Luvun edeltäjä on se vähennettynä yhdellä.
+
+Pienen luvun kani on
+	riippuen siitä, onko se pienempi tai yhtä suuri kuin yksi,
+	joko pieni luku
+	tai pienen luvun edeltäjän kani lisättynä pienen luvun edeltäjän edeltäjän kaniin.
+
+# --- Data ---
+
+# n = 1 .. 7
+Olkoon kiva lista uusi lista, jonka alkioita ovat yksi, kaksi, kolme, neljä, viisi, kuusi ja seitsemän eikä muuta.
+
+# Mutable variable for the interactive prompt
+Olkoon pieni muuttuja uusi muuttuja, jonka arvo on nolla.
+
+# --- Page ---
+
+Kun nykyinen sivu avautuu,
+	nykyinen sivu näyttää tekstin "<h2>Kertoma (n!)</h2><p>",
+	nykyinen sivu näyttää kivan listan jokaisen alkion kertoman,
+	nykyinen sivu näyttää tekstin "</p><h2>Fibonacci-kani (fib(n))</h2><p>",
+	nykyinen sivu näyttää kivan listan jokaisen alkion kanin,
+	nykyinen sivu näyttää tekstin "</p>",
+	nykyinen sivu etsii elementin nimellä "output" tuloksenaan kiva alue,
+	kivalle alueelle kirjoitetaan koodi "<h2>Kokeile itse</h2><p><button id='laske'>Syötä luku →</button></p>",
+	nykyinen sivu etsii elementin nimellä "laske" tuloksenaan nätti nappi
+ja	nättiä nappia painettaessa käyköön niin, että
+			pieneen muuttujaan luetaan luku,
+			pienen muuttujan arvon kertoma näytetään käyttäjälle
+		ja	pienen muuttujan arvon kani näytetään käyttäjälle.

examples/strings/merkkijono.itp

@@ -0,0 +1,30 @@
+# Merkkijono — String Operations in Tampio
+#
+# String literals require a case-marking noun before the quotes.
+# The noun must match the grammatical case of the expression:
+#   nominative:  teksti "..."  or  lause "..."
+#   genitive:    tekstin "..."
+#   illative:    tekstiin "..."
+#
+# "pituus"           = length
+# "yhdistettynä ... tekstiin X" = concat — illative case (like lisättynä for +)
+# "siistittynä"      = trim (essive function: merkkijono siistittynä)
+# "kenttä"           = split by comma → array, iterate with "jokainen kenttä"
+
+# Variables must be adjective + noun
+Olkoon mukava merkkijono teksti "Hei, Tampio!".
+Olkoon pitkä merkkijono teksti "omena,banaani,kiivi".
+Olkoon ylimääräinen merkkijono teksti "   välilyönnit poistuvat   ".
+
+Kun nykyinen sivu avautuu,
+	nykyinen sivu näyttää tekstin "<p>Merkkijono: ",
+	nykyinen sivu näyttää mukavan merkkijonon,
+	nykyinen sivu näyttää tekstin "</p><p>Pituus: ",
+	nykyinen sivu näyttää mukavan merkkijonon pituuden,
+	nykyinen sivu näyttää tekstin "</p><p>Yhdistetty: ",
+	nykyinen sivu näyttää mukavan merkkijonon yhdistettynä tekstiin " Vuosi 2026.",
+	nykyinen sivu näyttää tekstin "</p><p>Siistitty: '",
+	nykyinen sivu näyttää ylimääräinen merkkijono siistittynä,
+	nykyinen sivu näyttää tekstin "'</p><p>Hedelmät (pilkulla erotettu): ",
+	nykyinen sivu näyttää pitkän merkkijonon jokaisen kentän
+ja	nykyinen sivu näyttää tekstin "</p>".