The iterator pattern is nice because it gives the caller a simple flat-looking looping mechanism to traverse data entries. Consider the following pseudocode for traversing a tree depth-first.

const tree = {
  id: 1,
  left: {
    id: 2,
    left: { id: 3, left: null, right: null }
    right: null,
  },
  right: {
    id: 4,
    left: {
      id: 5,
      left: null,
      right: { id: 6, left: null, right: null },
    },
    right: {
      id: 7,
      left: null,
      right: { id: 8, left: null, right: null },
    }
  }
};

traverse(tree, onEmit);

function onEmit(node) {
  console.log(node.id);
}

function traverse(node, onEmit) {
  if (node == null) return;
  
  onEmit(node);
  
  if (node.left) traverse(node.left, onEmit);
  if (node.right) traverse(node.right, onEmit);
}

The program above takes a recursive approach to traversing a tree structure. While this may not be ideal in situations with very large tree structures, the program would print the following output when run:

1
2
3
4
5
6
7
8

Consider instead a breadth-first approach to traversing a tree:

function traverse(node, onEmit) {
  if (node == null) return;
  
  emit(node, onEmit);
  descend(node, onEmit);
}

function emit(node, onEmit) {
  if (node) onEmit(node);
  if (node.left) onEmit(node.left);
  if (node.right) onEmit(node.right);
}

function descend(node, onEmit) {
  traverse(node.left, onEmit);
  traverse(node.right, onEmit);
}

Note that I actually think the logic above is wrong.

---

Let's take the depth-first example and turn it into an iterator.

An iterator is an object with a next method that will return the following node in the tree. Once there are no more nodes, the next method will return null.

Let's look at the depth-first example again.

function onEmit(node) {
  console.log(node.id);
}

function traverse(node, onEmit) {
  if (node == null) return;
  
  onEmit(node);
  
  if (node.left) traverse(node.left, onEmit);
  if (node.right) traverse(node.right, onEmit);
}

Let's try to first model the recursion in an iterative manner.

function traverse(node, onEmit) {
  if (node == null) return;
  
  onEmit(node);
  
  // This should be represented by some data structure
  if (node.left) traverse(node.left, onEmit);
  // This should be represented by some data structure
  if (node.right) traverse(node.right, onEmit);
}

Let's think of the steps that are executed and see how we can decompose this recursive function into an iterative one.

Here's our example tree again:

const tree = {
  id: 1,
  left: {
    id: 2,
    left: { id: 3, left: null, right: null }
    right: null,
  },
  right: {
    id: 4,
    left: {
      id: 5,
      left: null,
      right: { id: 6, left: null, right: null },
    },
    right: {
      id: 7,
      left: null,
      right: { id: 8, left: null, right: null },
    }
  }
};

• Call traverse(tree, onEmit)
• node = tree
• Check if node is null - it's not, so continue
• emit node (1)
• Check if node.left is null - it's not, so let's traverse
• prev = node
• node = node.left
• check if node.left is null - it's not, so let's traverse **

** At this point, we realize that we're checking if node.left and node.right are null before we traverse. Then, we check again at the start of traverse. Let's just do it at the start of traverse only.

function traverse(node, onEmit) {
  if (node == null) return;
  
  onEmit(node);
  
  traverse(node.left, onEmit);
  traverse(node.right, onEmit);
}

Let's start again.

• Call traverse(tree, onEmit)
• node = tree(1)
• Check if node is null - it's not, so continue
• emit node (1)
• Check if node(1).left is null - it's not, so let's traverse
• prev = node(1)
• node = node(1).left(2)
• Check if node is null - it's not, so continue
• emit node (2)
• prev2 = node(2)
• node = node(2).left(3)
• Check if node is null - it's not, so continue
• emit node (3)
• prev3 = node(3)
• node = node(3).left(null)
• Check if node is null - It is, so skip this
• node = prev3(3)
• node = node(3).right(null)
• Check if node is null - It is, so skip this
• node = prev3(3)
• We've checked both prev3 left and right, so go back higher
• prev3 = empty
• node = prev2(2)
• node = node(2).right(null)
• Check if node is null - it is, so skip this
• node = prev2(2)
• We've checked both prev2 left and right, so go back
• prev2 = empty
• node = prev(1)
• node = node(1).right(4)

---

I think we need to come up with a max

Musings on a templating language

A templating language can be boiled down to glorified string replacement.

Consider a fictional company called Widget Corporation. They operate an online store and have an email system in place where they can contact their users to encourage purchases. They would like to remind customers who add items to their cart but don't complete the payment process to continue the flow and result in a purchase. They believe that a personalized email increases conversion rates. Here's an email that they send out to a fictional customer named Bob.

Hello, Bob!

You added 2 items to your cart. Still need time to think?

Let us help with that.

For the next 24 hours only, use coupon code BOB<3WIDGET10 to get 10% off your order (up to $50).

Visit the web store and act now ->

Don't miss out on this exclusive deal!

Widget Corporation Loyalty Team

The company has an employee diligently inspecting abandoned carts in the admin dashboard. When they find one, they inspect available offers, draft an email including the details, and send it onto the customer. To save time, they have a document with all of the boilerplate so they just need to replace specific sections with the customer's name, their cart deals, and the coupon data. Here's what that looks like:

Hello, {customer_name}!

You added {cart_num_items} items to your cart. Still need time to think?

Let us help with that.

{unique_offer}

Visit the web store and act now ->

Don't miss out on this exclusive deal!

Widget Corporation Loyalty Team

Here's some beginner-friendly advice on how to structure your Zig program to keep it readable and maintainable.

pub fn main() !void {
  const stdout = std.io.getStdOut().writer();
  
  try stdout.print("Hello, world!\n", .{});
}

const std = @import("std");

The main function of a program is the entrypoint. The code section above illustrates some minimal "Hello world" program, which prints the text "Hello, world!" to the console and then exits.

In Zig, your entrypoint will be responsible for bootstrapping your entire program. It should set up a program-wide allocator, parse command line arguments, and read environment configuration. Then, it should invoke your "real" program logic while providing it this information.

In pseudocode, your main function will look like the following.

main() {
  const allocator = setupAllocator();
  const cli_args = parseCliArgs();
  const env_data = queryEnvData();
  
  const config = .{ cli_args, env_data };
  
  runProgram(allocator, config);
}

To set up the allocator, use the standard library's DebugAllocator.

var gpa: DebugAllocator(.{}) = .init;
defer _ = gpa.deinit();
const allocator = gpa.allocator();

Then, to parse cli args, use the standard library's ArgIterator.

var args = try std.process.argsWithAllocator(allocator);
defer args.deinit();

// skip exe name
_ = args.next();

// todo: actual arg parsing logic...

Then, to query env data, use getEnvVarOwned.

const host = try std.process.getEnvVarOwned(allocator, "APP_HOST");
// ...

Here's how you can find all the target triples that your version of Zig supports.

Note that target triples will become target quadruples in an upcoming enhancement to the compiler. Follow the GitHub issue, [RFC/Proposal: Turning Zig target triples into quadruples](https://github.com/ziglang/zig/issues/20690).

Stories...

Inside a building in the neighbourhood of Coti at sunrise, Cody opened their eyes to a splitting headache. They spent the morning together, pushing against each other between modes of action. Cody needed to get to work on time because they'd been late a fair number of times recently. No one's said anything, but they want to get ahead of the issue and leave it in the past as transient, silent observation. Before long it'd grow to rumour then threat then disciplinary action. Not that Cody needed the stick, it's just that the thought of the whole situation gave them anxiety. So they forgot about it over drinks with friends. Clearly it didn't want to be forgotten and manifested itself as this headache, growing from subtle nag to dull throb.

Inside a building in the neighbourhood of Coti at sunrise, I opened my eyes to a splitting headache. We spent the morning together, pushing against each other between modes of action. I needed to get to work on time because I'd been late a fair number of times recently. No one's said anything yet, but I want to get ahead of the issue and leave it in the past as transient, silent observation. Unchecked, it'd grow to rumour then threat then disciplinary action. Not that I need the stick, it's just the thought of the whole situation fills my mental pool with a haze. So I forgot about it over drinks with friends. Clearly it didn't want to be forgotten, however, and manifested itself as this headache, growing from subtle nag to dull throb.

Sunrise -> Neighbourhood -> Building

Sunrise -> Cody

Headache -> Cody

Cody -> Headache

Headache -> Inaction

Cody -> Action

Cody -> Late -> Past

Cody -> On time -> Future

...

A software designer is burdened with the task of creating divisions in functionality between projects. If you were to make kitchen implements, you wouldn't make a bowl that is also a spoon. Each implement has its own function. However, if you were to attach a handle to the edge of a bowl, is it now a spoon? Then, if you were to scale up the spoon until the round end of the utensil is as big as a bowl, how different are the two? In fact, the round end of the spoon is called a bowl. It seems as if it's a matter of scale or perspective which informs us to make distinctions between the physical tools in our lives. How can we apply similar principles to software design to allow us to make informed divisions with respect to the software tools that we create?

I'm building a static site generator with JS component support, all in a single binary. It uses markdown for content, mustache for templating, and an embedded Javascript runtime to render components, which are essentially templating partials which can emit CSS and JS for dynamic content

On my recent job search I've come across quite a few postings with Go as their primary programming language. I believe that I can learn it on the job but I would rather give potential employers more confidence when it comes to my knowledge of Go. Also, I've always been interested in Go but never required to write it.

These are some of my jots of note when it comes to learning Go. This list is only beginning. I'll add here over time as I go along.

• Immediately useful commands of note are go mod init, go run, go help, and go mod tidy
• Help documentation for any command is available with go help
• You can search for Go modules at https://pkg.go.dev
• Go discovers module requirements depending on usage in source code when you run go mod tidy
• In addition to fetching required modules and updating go.mod, the mod tidy command will also remove any unused modules from go.mod
• Alternatively, you can use go get to fetch a particular module, but this should be used primarily for upgrading, downgrading, or removing existing modules
• If you do hand-modify your go.mod file, you can use go mod edit -fmt to ensure it has the proper formatting
• Go is opinionated when it comes to formatting, so there are specific conventions to follow
• By convention, "Exported names" are those beginning with a capital letter, so a function named Hello is exported (i.e. callable by external packages) while a function named hello is not
• When the := operator is used to declare and initialize a variable, its type is infered from the value on the right-hand side
• Go distinguishes a package as a "main package" if it contains a Go source file with package main at the start of the file
• You can use go mod edit to add a replace in your go.mod to point dependencies to packages on the local filesystem (this action should usually be followed by go mod tidy)
• You can use Go's Multiple return values feature to implement error handling
• The standard library's log.Fatal "is equivalent to Print followed by a call to os.Exit(1)" (see https://pkg.go.dev/log#Fatal)

The site https://pkg.go.dev has no API to search packages, but you can still achieve command-line package search by scraping the results from the search page.

Along with curl and tools from html-xml-utils, you can look up packages on the Go packages website:

read -p 'Search go packages: ' query && curl --get --data-urlencode "q=$query" "https://pkg.go.dev/search" | hxnormalize -x | hxselect -c -s '\n' '.SearchSnippet-synopsis, .SearchSnippet-header-path'

Alternatively, you can add this bash function to your profile and invoke it like gopkg <query>:

function gopkg {
  if [[ $# -ne 1 ]]; then
    echo "Usage: gopkg <query>"
    return 1
  fi
  
  curl --get --data-urlencode "q=$1" "https://pkg.go.dev/search" | hxnormalize -x | hxselect -c -s '\n' '.SearchSnippet-synopsis, .SearchSnippet-header-path'
}

While out suit shopping, a clerk helped us choose ties to match our suits. He provided excellent colour combination suggestions. I complimented him and asked him what his approach was. He told me he was simply choosing complementary colours, like on the colour wheel. It's important for his line of work (selling suits) to have expertise in at least basic colour theory in order to create objectively good colour combinations on the fly.

How about you? In your line of work, what do you think is important to know?

In a blog post by Jim Nielson titled Building Websites with Lots of Little HTML Pages, the author lists a few techniques where a developer might be able to use CSS page transitions and HTML pages over JS client-side operations. This isn't 100% true - there's still some JavaScript, but there are still some key takeaways.

In the first example, of allowing the user to switch between Latest, Trending, and Hacker News Hits filters for his blog posts, he opts for generating static HTML pages for each of these. It's a fairly trivial approach, but he makes use of CSS page transitions to make it feel like client-side navigation (on supported browsers), which is pretty interesting.

The second example was about how to handle the opening and closing of the nav menu via a hamburger icon. Traditionally, there would be some chunk of HTML inside the document that's hidden on the page or synthesized via JS that would become visible when the user clicks on the open icon or invisible once the user clicks on the close icon. A JS strategy that's fairly common is to add/remove a class name for this hidden menu and let the CSS styles do the work. A no-JS strategy that I've also seen (and employed) is by employing the Checkbox Hack, where you use an html label, input[type="checkbox"], and the CSS :checked property combined with the sibling selector to hide/show the mobile menu when the checkbox changes state. It's a neat trick and lets you achieve that client-side interaction without JS. The approach in this blog post is neither of those and is more similar to something like HTMX, where the user action would instead request an HTML blob that gets injected into the page. In this blog post, the user's click instead initiates a document request like normal and presents to the user a page which contains the mobile navigation. It's pretty simple in concept and is also easy to understand.

The neat trick about the HTML page nav menu is that the close button on this page uses a bit of JS to improve the user experience. This is the opening tag:

<a href="/" onclick="return document.referrer?history.back():window.location.href=&quot;/&quot;,!1" aria-label="Close menu (back)">...</a>

Notice the onclick attribute which makes this link act like the browser's back button if there's any history, but otherwise sends them back to the home page. If JS isn't enabled, it just acts like a normal link. The beauty of this is that a backwards page navigation doesn't perform another HTTP request, so although it still technically uses JS, it lets the browser take care of the job of presenting the previous page, rather than putting that task on whatever client-side solution is present (even though toggling a class on a hidden element is already pretty simple to maintain). To me, this is the perfect example of "graceful degradation" and it's the kind of web magic that makes you feel like elegant solutions are right there waiting to be discovered.