Skip to content

Commit 1da1327

Browse files
istatharistathar
authored
Initial README for compiler (#83)
Long overdue, add an initial _README_ file briefly explaining the project, describing the main subcommands of the command-line binary, and adding some example screenshots. Add some of the prototype files we've been using all along, and then update the golden tests to check the round-trip parsing and formatting of these files as well.
2 parents 5f27f54 + 7906e82 commit 1da1327

File tree

11 files changed

+666
-5
lines changed

11 files changed

+666
-5
lines changed

‎README.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Technique
2+
3+
This is the Technique Procedure Language, a programming language for
4+
describing procedures in a structured but human-readable form. You can
5+
consider it a domain-specific language (DSL) for writing procedures and
6+
checklists.
7+
8+
This language design has evolved over a long period, 20+ years, starting with
9+
on-paper procedures for systems operations tasks, and then going through
10+
different iterations of program and approach. The current version is Technique
11+
v1, written in Rust.
12+
13+
The Technique language allows you to write instructions to be read and
14+
followed other humans. As a result, Technique doesn't look much like
15+
programming code, but it is nevertheless a formally defined specification for
16+
writing procedures and clear rules for executing them and recording their
17+
outcomes.
18+
19+
## Usage
20+
21+
The _technique_ program has three subcommands:
22+
23+
- _check_ \
24+
Validate the syntax, structure, and types in a Technique document.
25+
26+
- _format_ \
27+
Format the code in the given Technique document, embellished with ANSI
28+
syntax highlighting if run in a terminal.
29+
30+
- _render_ \
31+
Render the Technique document into a printable PDF. This use the Typst
32+
typestting language and so requires the _typst_ compiler be installed and on
33+
`PATH`.
34+
35+
## Contents
36+
37+
This repository contains the _technique_ binary, which is the compiler for
38+
Technique v1, along with a code formatter, and machinery to render procedures
39+
as PDFs. Syntax highlighting is available for Vim, the Zed Editor, Sublime
40+
Text, and the Typst typesetter. There's a language server, and an extension
41+
for Zed, with VS Code and NeoVim on the way.
42+
43+
- Syntax checking, code formatter, renderer (this repository) \
44+
<https://github.com/technique-lang/technique>
45+
- Formal specification \
46+
<https://github.com/technique-lang/specification>
47+
- Zed Editor support \
48+
<https://github.com/technique-lang/extension.zed>
49+
- Tree Sitter grammar (for syntax highlighting) \
50+
<https://github.com/technique-lang/tree-sitter-technique>
51+
- Typst and Vim support \
52+
<https://github.com/technique-lang/highlighting>
53+
54+
## Examples
55+
56+
To give a sense of the flavour of the language, here are a small selection of
57+
Technique source files rendered to PDFs using the _technique render_ command.
58+
59+
### Systems and Operations
60+
61+
One of the original use cases behind this work was wanting to document the
62+
procedures used in systems administration and network operations. This example
63+
shows a simple list of such tasks:
64+
65+
<a href="tests/samples/LocalNetwork.tq">
66+
<img width=613 src="examples/screenshots/LocalNetwork.png">
67+
</a>
68+
69+
### Recipes
70+
71+
Preparing a meal during the holidays is also a list of tasks, but often more
72+
than one person needs to do things concurrently:
73+
74+
<a href="examples/prototype/ChristmasTurkey.tq">
75+
<img width=608 src="examples/screenshots/ChristmasTurkey.png">
76+
</a>
77+
78+
79+
### Instructions
80+
81+
This from a set of instructions guiding staff of what to do when an incident
82+
occurs:
83+
84+
<a href="examples/prototype/DontPanic.tq">
85+
<img width=593 src="examples/screenshots/DontPanic.png">
86+
</a>
87+
88+
### Larger processes
89+
90+
Finally, an example showing using Technique to describe a much larger
91+
procedure, in this case the entire process of doing systems engineering on a
92+
software project. This pushes the limits of what the language is for, but
93+
nevertheless illustrates that Technqiue can be used for very large structures
94+
as well as very detailed ones:
95+
96+
<a href="examples/prototype/SystemsEngineeringProcess.tq">
97+
<img width=600 src="examples/screenshots/SystemsEngineeringProcess.png">
98+
</a>
99+
100+
Detailed examples can be found in the _examples/_ and _tests/_ directories.
101+
Documents written in Technique have file extension _\*.tq_.

‎examples/prototype/ChristmasTurkey.tq‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
% technique v1
2+
! Proprietary; © 2002-2019 Andrew Cowie
3+
4+
christmas_dinner : Context -> Dinner
5+
6+
# Christmas Dinner
7+
8+
Recipe for a classic Christmas dinner. It is probably worth noting that this
9+
can be followed on most any high holiday. The only things you really need are
10+
patience, guests, and a turkey.
11+
12+
1. Assemble ingredients <assemble_ingredients> ~ ingredients
13+
2. Prepare the meal <prepare_meal>(ingredients) ~ meal
14+
3. Serve dinner <serve_dinner>(meal) ~ dishes
15+
4. Clean up after <cleanup_after>(dishes)
16+
17+
assemble_ingredients : () -> Ingredients
18+
19+
# Shopping List
20+
21+
Assembling all necessary ingredients from various sources.
22+
23+
@chef
24+
1. Get turkey from butcher { <turkey> ~ t }
25+
2. Get stuffing ingredients { <stuffing> ~ s }
26+
3. Get breadsauce ingredients { <breadsauce> ~ b }
27+
28+
turkey : () -> Ingredients
29+
30+
# Turkey
31+
32+
For some reason people seem to think that they need an enormous bird. Don't
33+
worry even if you are expecting a large party; if you've got lots of relatives
34+
you can just leave out a few plates of cheese and crackers and they'll be full
35+
long before dinner is served.
36+
37+
^butcher
38+
- Buy turkey
39+
{
40+
[
41+
"Turkey" = 4 ± 1 kg
42+
"Bacon" = 2 pieces
43+
]
44+
}
45+
46+
stuffing : () -> Ingredients
47+
48+
# Stuffing
49+
50+
Stuffing a bird actually makes it take longer to cook, but doing so adds
51+
aroma, flavour, and helps preserve moisture and keeps the turkey tender.
52+
53+
^store
54+
- Get seasoning ingredients
55+
{
56+
[
57+
"Salt" = 1 teaspoon
58+
"Pepper" = 1 teaspoon
59+
]
60+
}
61+
62+
^grocer
63+
- Get vegetables
64+
{
65+
[
66+
"Carrots" = 1 each
67+
"Celery" = 0.5 stalk
68+
]
69+
}
70+
71+
^bakery
72+
- Get bread
73+
{
74+
[
75+
"Bread" = 2 slices
76+
]
77+
}
78+
79+
breadsauce : () -> Ingredients
80+
81+
# Breadsauce
82+
83+
This ancient recipe from Northern Yorkshire calls for ...
84+
85+
^bakery
86+
- Get bread
87+
{
88+
[
89+
"Bread" = 4 slices
90+
]
91+
}
92+
93+
^store
94+
- Get spices and milk
95+
{
96+
[
97+
"Salt" = 1 teaspoon
98+
"Pepper" = 1 teaspoon
99+
"Cloves" = 4 teaspoons
100+
"Milk" = 100 mL
101+
]
102+
}
103+
104+
^grocer
105+
- Get onion
106+
{
107+
[
108+
"Brown Onion" = 0.5 bulb
109+
]
110+
}
111+
112+
prepare_meal(i) : Ingredients -> Meal
113+
114+
# Prepare Meal
115+
116+
Coordinating the preparation of all meal components.
117+
118+
@chef
119+
1. Roast the turkey { <roast_turkey>(i) ~ turkey }
120+
2. Roast potatoes { <roast_potatoes>(i) ~ potatoes }
121+
3. Make breadsauce { <make_breadsauce>(i) ~ sauce }
122+
4. Prepare vegetables { <prepare_vegetables>(i) ~ raw }
123+
5. Make gravy { <make_gravy>(i) ~ gravy }
124+
6. Wait for cooking { timer(3 hr) ~ t1 }
125+
7. Cook vegetables { <cook_vegetables>(raw) ~ (veggies, water) }
126+
8. Combine gravy with vegetable water { <combine>(gravy, water) ~ gravy }
127+
9. Check turkey temperature { <probe_bird_temperature>(turkey) ~ temp }
128+
{
129+
[
130+
"Final Temperature" = temp
131+
]
132+
}
133+
134+
roast_turkey(i) : Ingredients -> Turkey
135+
136+
# Roast Turkey
137+
138+
@chef
139+
1. Set oven temperature { <oven>(180 °C) ~ temp }
140+
2. Place bacon strips onto bird
141+
3. Put bird into oven
142+
4. Set timer for roasting { timer(3 h) ~ t }
143+
5. Record temperature
144+
{
145+
[
146+
"Roast temperature" = temp
147+
]
148+
}
149+
150+
@assistant
151+
- Set the table
152+
153+
cook_vegetables(veg) : VegetablesPrepared -> VegetablesCooked, VegetableWater
154+
155+
# Cook Vegetables
156+
157+
@chef
158+
1. Boil water
159+
2. Dunk greens in water
160+
161+
combine(g, w) : Gravy, VegetableWater -> Gravy
162+
163+
# Pour the vegetable water into the gravy
164+
165+
@chef
166+
- Combine gravy and vegetable water
167+
168+
serve_dinner(m) : Meal -> DirtyDishes
169+
170+
# Serve dinner and enjoy
171+
172+
cleanup_after(d) : DirtyDishes -> ()
173+
174+
# Cleanup
175+
176+
No one likes cleaning up. As far as I can tell, the only real justification
177+
for having children is to help with doing the dishes on festive occasions.
178+
Certainly I always hated my Aunt at holidays for making me dry dishes with a
179+
dish towel when they would perfectly well air dry by themselves.
180+
181+
@*
182+
1. Turn off oven { <oven>(0 °C) }
183+
2. Put knives away { <knives_away> }
184+
3. Turn lights out { <lights_out> }
185+
186+
oven(temp) : Temperature -> ()
187+
188+
# Set oven temperature
189+
190+
@chef
191+
- Set temperature to { "oven at { temp }" }
192+
193+
knives_away :
194+
195+
# Put knives away
196+
197+
@*
198+
1. Place knives in safe place
199+
2. Start dishwasher

0 commit comments

Comments
 (0)