Þ   briarpig  » thorn  » demos

     This demo department collects pages about using þ to implement specific kinds of tasks, presented as a story with occasional bits using fictional developers, featuring Wil as the author persona.

     The actual source code for þ is developed in this way, interleaved with docs explaining what code does.

     A main idea of demos is simply trying code involved, to see if the results suit desired behavior, with an empirical focus.

     To some folks, perhaps none of the demos qualify for the term demo as it is most often used by industry folks: as a word meaning "exercise the user interface of software."

     Little code you find here has a user interface, unless you count debug printing. Local use of demo means "show more and define less." Design in a vacuum is second class. Ways to get specific desired effects have priority. So þ demos pursue code as exploring "suppose you want to do xyz..."

     Notably absent is a unified view of the world besides internal consistency and practical technique which assumes there is no need to ever look at how anyone else does things. As a side effect, code can be grasped locally with a near horizon.

     You can see the menu at the top of the right column, with mirrored nav links in the far right sidebar under the image. Both these appear on all demo pages.

     The todo page describes state of completion for all demo pages, as well as overview for order and relation of topics — Wil offers remarks on topic choice and relevance.

     Toy language related demos under mu appear under toy, which serves the same role as this page, but for toy language specific code. The þ runtime includes language support without clear boundary for one purpose and another. (Names of þ classes reserve some primitive symbol conventions for VM runtime purposes; but these are usually consistent with other uses. For example, the letter p means pointer most often — even for iterators which resemble pointers; but yp is the peg primitive pointer type for slots in gc memory.)

     Here's an example demo featuring a comment figure shown on the style page. This demo explains what the type yv means in the course of showing how to intersect two of them:

     Wil's yv::vintersect() test is just main() returning the value from a test method counting errors, so zero is success.

     First Wil writes a test case that fails on purpose, to see what an error case looks like in output:

     When this executes, the following output appears:

     Wil's final yv_vintersect_test() looks like this:

     thorn: todo, names, fd, iovec, assert, log, run, hex, crc, buf, in, out, quote, escape, compare, file, deck, cow, arc, blob, tree, slice, rand, time, stat, hash, heap, node, primes, page, book, pile, stack, atomic, lock, mutex, thread, map, meter, list, iter, ctype

     (mu: toy, peg, imm, tag, box, symbol, token, number, bigint, class, method, reader, writer, eval, env, vm, gc, world, pcode, compiler, asm, lathe, lisp, smalltalk, design, weight, jar, card, harp, debug, profile)

     Some demos are stubs: todo is a demo guide. See toy for mu updates on language pages; names introduces naming schemes.

     Besides the menu, all the rest of this page is a sample demo. Instead of explaining demos or filling the page with drivel, an actual demo seemed more in the spirit of showing first.

     Here we explain the meaning of yv — a vector of bytes like an iovec — by showing how we can find the intersection of any two ranges of memory (assuming a 32-bit address space here). See code in the left column for reference.

     Note u8 and n32 are defined on the types page.

     The yv api used in the left column is this:

     Now let's comment from Wil's view. Wil calls yv a run of bytes. (A run is a contiguous sequence of items.) Wil wants to intersect two runs when (for example) generating a slice from a yv run given an offset and length.

     On yv::vintersect()'s first line, Wil didn't use yv's empty constructor though it would have worked. Wil thinks passing explicit values is better for readability.

     If either this or input alt has zero length, the intersection is empty. Otherwise Wil renames the two yv instances as the earlier lo or later hi instance, depending on which begins first in memory.

     If start of later run (c) begins at or after end of earlier run (b) there's no overlap and the result is empty.

     Otherwise Wil figures a non-empty intersection must exist and start with c (the later run's start). The end of the intersection is the end of either run, whichever comes first. And length is distance from end to start.

     To test yv::vintersect(), Wil compares result values with expected values, so a boolean test for equality is needed. This can be done several ways, but let's pick an easy one. This version of yv equality assumes address v_p can be used if v_n is nonzero and you compare instances, implying access is okay.

     We assume yv's api is a union of all methods we use.

     General yv comparison occurs in another demo. This is enough to test for equality of octet sequences.

     Another demo features Wil's yv hexdump code with ascii annotation. This demo doesn't need that — just simple printing. The test for intersection works on any bytes, so Wil simply uses "%.*s" format in fprintf() to print strings of known size which are not necessarily nil terminated.

     (Note Wil often uses fprintf() for minimal code above the standard C library. The fewer moving parts the better.)

     Wil puts most code in a C++ namespace, so all þ code is current inside the mu namespace, but the demo doesn't show this. And Wil uses the following directive to avoid any need to write mu::yv instead of simply yv as shown.

     But it's best to think of mu::yv as the actual class name.

     Wil likes to walk through test executables under gdb to see pieces of memory contain values he expects. In his way, Wil can step through the intersection code as many times as he needs to feel code is bullet proof for his purposes.

     Demos far down the road will include interactive testing, so Wil can play with code interfaces without first committing to a specific static code path to run under gdb. But those demos will first require the demos building a toy language for interactive tests.

     (Dynamic scripting languages like Python also work for that purpose, though it would involve layers of code Wil has little control over. And it goes against the grain of an aim to build our own toy language here after basic stuff is demonstrated.)

     To be consistent, all the tests compare two runs with veq(), even when a simpler test for is-empty could be done. This makes it clear what to pass into a function reporting failure.

     But this might be a good place to show a conversion to boolean for yv using an operator, because it creates an opportunity to discuss failings of operators due to ambiguous interpretation.

     The earlier definition of veq() considers all yv instances with zero length v_n equivalent: so v_p doesn't matter when v_n is zero. But the definition of vempty() and operator bool() look at v_p as well. Why is that? It depends on what you mean by "empty."

     With respect to yv, Wil wants empty to mean "don't try to use the bytes referenced" either because there are none, or because the pointer is nil. But this makes veq() and vempty() at odds. But Wil never wants to compare bytes located at address zero, so the difference in behavior doesn't arise.

     Sometimes Wil has a use for zero-sized yv instances using specific non-nil v_p values. For example, when parsing content, a zero-sized yv can still point to where text might be located if present, even when actual length is zero (say, the value of an empty URL query parameter in an HTTP header). So this means one "empty" yv is not identical to every other, since an empty sequence can occur at different points in memory; yv just describes memory spans, not content.

     Dex noticed Wil used const yv& everywhere in the demo, and never yv const&, so this was his big chance to imply Wil didn't know the alternative by bringing it up first.

     "I think veq(yv const&) is better style," Dex observed.

     "I also use that syntax more myself," Wil nodded. "But many folks haven't seen it and think it looks weird."

     "But now's your chance to push a style," Dex urged.

     "Shut up, Dex," Ira warned.