Rust Koans​​​​​

[DanielKeep]

Obstacles

For the eighth day in a row, Neophyte Col found himself standing before the Two Great Guards of the temple. They stood before the large entrance of the temple, clad in simple robes. Nevertheless, they were imposing, and feared. He strode toward the first guard, confident, and handed the parchment bearing his program.

The First Guard read through it carefully. This step was but a formality; yesterday, he had only failed to gain the assent of the Second Guard. He was certain he had addressed all outstanding complaints.

The First Guard handed the parchment back to Col. Then, in a blinding motion, slapped Col across the face with his bare hand. In a measured voice, the First Guard spoke to him: "mismatched types: expected &Target, found &<T as Deref>::Target", then fell silent.

Col took his parchment and retreated back to a nearby bench, close to tears. Eight days. It was not as though his program was particularly complicated, and yet he could not convince the Two Great Guards to permit him entry to the temple. He had not had this much difficulty at other temples!

At another bench, he saw a fellow neophyte. They had spoken two days previous, when he had learned his compatriot had been toiling outside the temple for close to two weeks to get his program accepted.

It was the guard's fault. Col knew his program would work as intended. All they ever seemed to do was pick on minor errors, denying him for the most petty of reasons. They were looking for reasons to deny him entry; that was it!

He was beginning to seethe with resentment.

Thereupon, he noticed a monk speaking to the other neophyte. The conversation seemed quite animated when, all of a sudden, the neophyte whooped, leapt up, and rushed toward the temple. As he ran, he seemed to be frantically modifying his program.

However, rather than face the Two Great Guards, he instead walked over to a small, dingy part of the wall. To Col's surprise, the wall opened into what appeared to be a secret entrance. The neophyte passed through, and was gone from sight.

Col sat stunned. A secret entrance? Then... then the Two Great Guards might merely be a prank! Something the other monks put neophyte through to teach them humility. Or... resilience. Or... or... perhaps it was just to laugh at them secretly.

"Do you wish to know what I said to him?" a voice asked. Col turned to see the monk standing beside his bench. "You told him there was another way in, did you not?"

"Yes," she replied. "I told him of the unsafe door."

"unsafe?" Col asked.

"Indeed. It is a secret known to those who have studied long and hard at the temple. In truth, one can overcome many of the obstacles posed in writing one's program through the use of the unsafe arts, as spoken of in the Rustonomicon."

"Are they powerful?" Col asked in wonder.

"Immensely powerful. With transmute, one can simply re-assign the type of a value, or extend the lifetime of a pointer. One can even summon pointers from the air itself, or data from nothingness."

Col felt he finally understood how the temple worked. It was this "unsafe" magic that the monks used! However...

"Then, why are the Two Great Guards employed if one can simply walk through the unsafe door to reach the temple? Why not..."

At that moment, a blood-curdling scream was heard from within the temple. It echoed across the courtyard before ending suddenly.

Silence descended. No one moved. No one spoke. The wind stilled. Even the birds halted their singing.

Col could feel his heart pounding in his ears.

"They are there," the monk said, breaking the spell, "to protect you from the temple, and what lies within."

Col turned to gaze once more at the hidden doorway. "Then why does that door exist?"

"Because, even they are not infallible. Some times, one must face peril alone." She sighed. "But not all are so brave or skilled."

With that, the monk took a sheet of parchment from her cloak and walked toward the Two Great Guards. The First Guard read her program and nodded. The Second Guard read her program, handed it back, and then struck her across the face.

"Borrowed value does not live long enough."

The monk, rubbing her face, walked back and sat down on one of the benches, muttering curses.

At that moment, Col was enlightened.

[DanielKeep]

Behavioural Modelling

Upon a warm autumn day, Brother Farbold was walking through the Gardens of Abstraction near the recently opened Temple of Rust. He passed many curious and elaborate displays of complex abstractions, when he chanced upon a monk toiling away at her own display. Her robes identified her as a neophyte, though her creased, worn hands spoke of many, many years of experience. Around her were scatted dozens of white stones of all shapes and sizes along with several different rakes. Attached to each was a single, small, paper label with a word written on it.

Intrigued, he walked closer.

"Ho!" he said, "what is your name?"

"I am Neophyte Maran."

"What problem are you working on, if I might enquire?"

"I am attempting to translate a previous design that it might be suitable for the temple," the neophyte replied, concentrating on a large sheet of paper covered with sketches of boxes, connected by many lines and arrows.

"I see many labels; what are those for?"

"They define the class of each object."

Brother Farbold paused. "What are classes?"

The neophyte gave him a look of confusion. "You do not know what classes are?"

"No," he replied. "I have heard such a phrase carried on the wind from far away, but in this place, we do not use it."

"Ah, I see," said Maran. "In the temple where I came from, we use classes to define all the properties and behaviours of a thing, that many may share a single definition."

"A useful device, then. In such a scheme, as a simple gardener, I would have a tend behaviour, then?"

The neophyte nodded and picked up a small rock. "This is a Rock," she said, showing Brother Farbold the label. "It has no methods, for all it does is lie on the ground until operated on, but it has properties such as weight and volume."

"So a rock cannot do anything at all?"

"Nothing. Unlike this Rake, which possesses the ability to rake one or more Rocks. This allows me to model a garden and its evolution in its entirety."

"Indeed? This simple model allows you to capture all possible interactions, then?"

"Yes!" exclaimed Neophyte Maran proudly. "I have used this for many years with great success."

"But what if the rock wishes to roll, or shine, or talk? Classes sound restrictive; I prefer to define smaller behaviours, that each thing may pick and choose what it wishes to do."

The neophyte scoffed. "An object can do only that which it was designed to do, nothing more. You said you were a gardener; are you tasked to instruct new students, or to cook meals?"

"I am not; I am tasked with gardening."

"With classes, such is expressed by your class at design-time. As such, there can never be any confusion! To change behaviours is to change the design of the system!"

"Facinating," said Farbold, nodding. The neophyte turned back to her work.

"I must admit I am having trouble finding how to express this concept in a way that the temple will approve of, but I am su--" the neophyte was interrupted when one of the smaller white rocks struck her head.

Holding her head, Maran turned around. "Did you throw a rock at me?" she demanded.

"Me?" said Brother Farbold. "Of course not. I am but a simple Gardener; I know nothing of throwing Rocks."

"The rock could not have thrown itself!"

"And yet, your design does not allow for such a thing to have happened. Surely, you must be mistaken: no rock was thrown."

Neophyte Maran grumbled and turned back to her sketches.

A moment later, she flinched away as a long wooden pole struck her arm. "Did you...?"

"A Rake can only rake Rocks; it cannot "hit Neophytes". You must be imagining things.

"But you..."

"Ho! Brother Farbold!" another monk cried from the other end of the garden. "Brother Schieb has taken ill; would you be so kind as to cook the evening meal in his stead?"

"I would be happy to, Sister Doure; I am just now finishing my instruction of this neophyte."

At that moment, Maran was enlightened.

[DanielKeep]

Perfection

Sister Kiyou shuffled nervously under the gaze of the one the Abbott had called "The Master Architect"; a monk called Master Torand. "As promised, I presented my completed design to him the day before the new moon, along with the three hundred and sixty one pages of extensive documentation explaining all ways in which the interface could correctly and incorrectly be used," she concluded. "I was particularly proud of the documentation. I went to great pains to ensure that all possible incompatibilities and failure cases were enumerated in detail, but the Abbott did not seem over pleased."

"And then?" asked Torand.

"He said, 'you have toiled long and hard to complete this, but now I would have you work a while with The Master Architect. Perhaps something will be learned.' Thus, I came here," she finished.

Master Torand nodded in understanding. He clearly seemed to know what this was about. "The Abbott has asked me to design a new pagoda for the temple grounds, that the temple's knowledge might be given a fitting home. Before I begin construction, I must ensure the design is perfect. As such, I shall send the Abbott a model; both that he might inspect it, but also to determine if the design is sound."

Kiyou nodded, for this sounded eminently sensible.

"As it happens, I have prepared just such a model. It is over there," the master said, indicating a table in the corner of the room. Kiyou walked to it and found it covered in hundreds of tiny, loose pieces of delicately carved and painted wood.

"This is... can it truly be called a model when it lies unassembled?"

"A fair point, sister. It shall be your task to assemble the model."

"My—?"

"I have laboured for many days with little rest; I believe I shall walk through the gardens to clear my mind. No doubt a talented nun such as yourself shall have no trouble in completing this final formality."

"Master, I am an architect of algorithms, not buildings; I know little of wood and stone."

"There is much to learn, but fortunately, I already know all that need be known for this task, and have built the pieces for you."

"But I do not... in truth, I have but a vague notion of what a pagoda is meant to look like!"

"This should present no difficulty for one of your ability." With that, Master Torand left Kiyou alone in the workshop with the pile of model parts.

Kiyou was dismayed. There was no way she could assemble the model without even knowing what it was meant to look like! Schematics, a blueprint, some general outline... how could a supposed master expect her to construct something so complex without any guidance?

For some time, Kiyou simply stared at the jumble of wooden pieces. Carelessly, she began to examine the pieces. She became fascinated by how many different and unique parts there appeared to be. Even something as simple as the tiny wooden beams appeared to have many slightly different variants. One might have a square joint at one end, the next would be circular. Another would end in a hexagonal shape.

On a whim, she took two likely looking wooden tiles, and found they would not fit together. Putting one down, she tried the next. And the next. And the next. Finally, she found a second piece that would fit.

She now had two tiles. And so, she searched for a third.

Then a fourth.

Then a fifth.

With each step, she found but a single piece that would fit in place. In short order, she realised she had constructed what appeared to be a small floor. The floor had several holes for other pieces to fit. Careful searching of the pile revealed just five beams that would fit. Thus, she put them together.

On and on this went, as the sun crossed the sky outside. The pagoda grew higher and higher, seemingly of its own volition. Floors assembled, walls attached, tiles locked into place. Kiyou felt she had no control over how the model was coming together: it was as though the model knew what shape it needed to be and would not allow her any freedom.

When the sun was hanging low in the sky, Kiyou found the model complete. Every piece had been used. The structure was sound. It was tall, with elegantly curved roofs. Even though she did not understand how it had been done, Master Torand had somehow built a stable and beautiful model of a pagoda though he had not been present for its assembly.

At that moment, Kiyou was enlightened.

"Ah, just in time for me to return from my walk."

Kiyou did not turn to face him. "I trust your exercise was refreshing?"

"Indeed. Now, I would like you to deliver the model to the Abbott, and tell him what has been learned."

---

"Whereupon, I returned here," she finished, showing the Abbott the completed model.

The Abbott frowned. "And," he asked, "what was learned?"

"I was wrong to be proud of my documentation. Though it came from great effort and care, I should have used that effort to make the interface itself better. I should have endeavoured to make an interface that did not require three hundred pages of explanation. One where the types themselves guide the programmer in their use.

"A perfect interface is one which is impossible to use incorrectly, even by accident."

The Abbott sighed. "I suppose it cannot be helped. Come, let us put it with the others."

Confused, Kiyou followed the Abbott as he led her through the winding corridors of the temple. At last, they came to a long hall with several shelves along each wall.

Each shelf was covered in dozens upon dozens of little model pagodas, each slightly different to the last. Walking to the very end of the room, past the array of little structures, the Abbott indicated an empty place on a shelf, into which Kiyou set her model.

This was a lesson taught and learned many times over, it seemed.

"It is a valuable lesson for you to have learned, but that was not why I sent you to see Master Torand."

"Ho?"

"Indeed not. Master Torand was asked to construct a pagoda for this temple some eight years ago. Each time he completes a design, he withdraws it again, claiming it to not yet be perfect." He sighed again.

"I was rather hoping you might teach him the value of pragmatism and compromising perfection for the sake of completion. Even an ugly, rickety shed would be more useful than a hypothetical, flawless pagoda."

At that moment, Kiyou was enlightened.

[DanielKeep]

Puom

Neophyte Col came to Master Tuor one day and said: "I have almost finished a program in which I see repeated patterns of code. The patterns are not regular enough to be abstracted by functions or traits. I have a mind to use macros, but am unsure of how to proceed."

Master Tuor considered this. "I believe I know who can help you find clarity. Come."

Together, they walked away from the main temple and past the gardens. On the periphery of the grounds, they came across a strange building. Each plank of wood, each panel, tile, window; all were unique in shape, size, colour, texture, material... "What is this place?" asked the neophyte.

"It is where the Clan of the Falling Snowflake practice the art of Syntactic Abstraction. They abhor repetition above all else." Col nodded as they entered.

Inside, the building was just as relentlessly unique. No two doors were the same shape or size. Each candle and its perch were designed and coloured a different way. Col began to feel dizzy.

Even the monks themselves exemplified this approach. Rather than the plain, dark brown robes the other monks wore, each monk of the Falling Snowflake wore a haphazard collection of materials and colours. Col wondered if perhaps a great storm had swept up a cloth merchant's wares and deposited them on these unsuspecting monks.

His eyes were then caught by the walls. They were covered with programs that seemed to be in some strange language as he might expect from the Temple of APL... but here and there he caught glimpses of familiar syntax, though they made little sense.

The monks' speech was strange as well. Col observed several groups standing silently, staring at each other. He began to wonder if perhaps they were forbidden to speak at all, when he heard an outburst from one group:

"Sie durm! Wik puom, eeis."

With that, the monks standing in the group nodded at one another and walked away.

"Master..." Col began.

"As I said, they abhor repetition. As such, they abhor our language, filled as it is with redundancy, not to mention inaccuracy. Instead, they use their own tongue which is both perfectly precise, and perfectly optimal. They say what they mean and nothing else."

"But they are so quiet, otherwise."

Master Tuor nodded. "Do you think it easy to decide what one wishes to say, with utter and complete precision, before speaking a word?"

As they passed through a tiny, five-sided doorway, they came upon a monk dressed in cloth dyed in a thousand shades of dark grey. Wrapped around the robes was a mesmerising pattern in white thread that seemed to spiral forever away into the cloth; an infinite, curving beast made of straight lines and squares.

"Neophyte, this is Master Quoem, head of the Clan of the Falling Snowflake." The monk nodded in greeting. "Tell him of your problem."

Col took a breath. "I have nearly completed a program in which I see much repetition.

"In some cases, the logic must call different functions, though all around it remains unchanged. In others, different types implement similar methods, yet they cannot be unified by traits.

"I have been told that macros may be a solution to my problem. What would you advise?"

Master Quoem was silent. For many long minutes, he stared intently at Col. It went on for so long that Col began to shuffle nervously under the master's gaze, uncertain if he had somehow offended him.

The master, Col noticed, had slightly odd eyebrows...

Finally, Master Quoem spoke thus:

"Fheiq kah, puom."

Then he nodded at Col, turned, and walked away.

"Thank you for your counsel, Master Quoem," said Master Tuor as he guided Col back the way they came.

As they walked, Col tried to understand what had happened. Stepping back out into the sunlight, he came to a conclusion.

"Did speaking to Master Quoem help you find your answer?" Master Tuor asked him.

"Yes," replied Col. "I have finished my program."

Master Tuor nodded; the neophyte had been enlightened.