Raku Behind the Docs

Before you start

1. 0How to Read This Book5 corners

   A corner is one behaviour, stated as a claim and shown by the smallest program that proves it.

Reading the code

How the compiler decides what a line means: which operator takes the operand, what a quote does to its text, how whitespace changes a parse, and what happens to a value nobody uses.

1. 1Who Takes the Operand30 corners

   Precedence decides which of two neighbouring operators gets the operand between them; associativity decides what happens when they are on the same level.

2. 2Quotes and Interpolation37 corners

   Which backslashes, variables, brackets and braces mean something inside each of Raku's quoting forms, and what word lists, heredocs and shell quotes hand back.

3. 3Whitespace, Terms and Blocks28 corners

   Where a space, a newline or a brace changes what the parser sees, from subscripts that must touch their term to blocks that turn out to be hashes.

4. 4Values Nobody Uses26 corners

   A value that nothing uses is sunk; the compiler warns about the useless ones, and at run time a sunk Failure, a failed Proc and a Seq each do something of their own.

5. 5Containers and Binding34 corners

   Assignment copies a value into a container, binding shares the container itself, and itemization wraps a value in one; together they decide what is copied, what is shared and what counts as a single item.

Nothing and numbers

Undefined values, the numeric tower and strings: the values every program starts from, and the edges where they surprise.

1. 6Nil, Any and the Undefined42 corners

   Nil is the absence of a value and answers almost any question with itself, while Any, the parent of nearly every class, lets a single value or a type object act as a list of one element.

2. 7Numbers55 corners

   Four kinds of real number, Int, Rat, FatRat and Num, each with its own rules for combining, printing, comparing, rounding and failing, and a handful of results that look unintended.

3. 8Strings81 corners

   How a Str counts, cuts, searches and compares its graphemes, how text becomes a number or an allomorph that is both, and where Rakudo's string methods stop doing what their names promise.

Collections

Lists, arrays, hashes, ranges, sequences, sets and buffers: what each container holds, when it is lazy, and what an empty one answers.

1. 9Lists, Arrays, Seqs and Slips60 corners

   A List is immutable, an Array keeps a container per element, a Seq can be read only once and a Slip dissolves into its neighbours; the single-argument rule, holes and laziness decide the rest.

2. 10Hashes, Maps and Pairs43 corners

   A hash turns its keys into strings unless told otherwise, keeps its pairs in no order, answers questions through subscript adverbs, and is filled from and read back as Pairs, which have rules of their own.

3. 11Ranges42 corners

   A Range is two endpoints and two flags, and almost everything it does, from counting and smartmatching to arithmetic and printing, is worked out from those four facts rather than from its elements.

4. 12The Sequence Operator35 corners

   How ... turns a few seeds and an endpoint into a sequence, deducing a step or calling a generator, and the places where its endpoint, its seeds and its chains behave unlike the examples suggest.

5. 13Sets, Bags and Mixes62 corners

   A Set, a Bag and a Mix weigh their elements as a truth value, a count and a real number; elements are compared by identity, the hash forms can change, and every set operator picks its result type from the richer of its operands.

6. 14Blobs and Bufs59 corners

   A Blob is an immutable run of native integers and a Buf a mutable one; they index like arrays but are neither lists nor strings, compare and print in their own way, and carry the encoders, decoders and binary readers.

Code

Signatures, exceptions, regexes and grammars: the behaviour of the code you write rather than the data it handles.

1. 15Signatures and Introspection89 corners

   A signature decides which arguments a call accepts and how each one is bound, multi dispatch picks the narrowest signature, and every code object, signature, parameter and attribute can be asked what it is.

2. 16Exceptions and Failures59 corners

   How Raku throws, catches, resumes and reports an exception, how a Failure holds one back until somebody looks, and what $!, CATCH, CONTROL and the phasers see on the way.

3. 17Regexes and Grammars67 corners

   Which alternative a regex takes and what it runs again when it backtracks, where captures land, what a Match and $/ hold and in which scope, what the adverbs of .match count, and in what order a grammar calls its actions.

Time and the outside world

Dates, files and processes: the parts of Raku that talk to the machine.

1. 18Dates and Times63 corners

   An Instant counts atomic seconds with the leap seconds in them, a Date is a numbered day with a calendar on top, and a DateTime is a wall clock in a zone; the surprises lie where the three meet, and where a comparison falls back to text.

2. 19Files and Paths57 corners

   An IO::Path is text until something touches the disk; from there each file operation either fails or throws by its own rule, and handles translate newlines, share one position and keep their own separators.

3. 20Processes34 corners

   run and shell wait for a program and return a Proc that holds its status and pipes; Proc::Async reports through supplies and promises, whose rules decide when output arrives and whether the program is ever seen to end.

Concurrency

Promises, locks, supplies: what runs when, and in which order the events arrive.

1. 21Promises, Locks and Awaiting45 corners

   What keeps and breaks a Promise, what start, then and await hand on and throw, how Channels, locks and semaphores behave between threads, and what sleep answers.

2. 22Supplies67 corners

   How a Supply delivers its values, its done and its quit to each tap, what supply and react blocks do with whenever, QUIT, LAST and CLOSE, and where Rakudo's Supply methods break their own rules.

Appendices

Reference material gathered from the chapters.

1. APossible Bugs69 corners

   Every behaviour the chapters mark as a possible bug, with the evidence that makes it look unintended and the smallest program that shows it.

2. BWriting a Probe20 corners

   The ways a small test program measures something other than what its author meant, and how to write one whose output can be trusted.

Back matter

1. Colophon

   Who wrote this book, from what, and how every output in it is checked.