Add Part 1: Lexing

lib/generate/posts.ts

@@ -11,6 +11,8 @@ import layout from "../layout";
 async function generatePostFromFile(postPath: string, additionalMetadata: object = {}): Promise<Page> {
 	const page = await metadata.get(postPath);
 
+	(<PostMetadata>page.metadata).tagSlugs = (<PostMetadata>page.metadata).tags.map((tag) => slugify(tag));
+
 	for (const k in additionalMetadata) {
 		if (additionalMetadata.hasOwnProperty(k)) page.metadata[k] = additionalMetadata[k];
 	}

lib/generate/tags.ts

@@ -1,5 +1,6 @@
 import { Page, PostMetadata } from "../metadata";
 import generatePaginated from "./paginated";
+import slugify from "@sindresorhus/slugify";
 
 export default async function(posts: Page[]): Promise<Map<string, Page[]>> {
 	const taggedPosts = new Map<string, Page[]>();
@@ -15,7 +16,7 @@ export default async function(posts: Page[]): Promise<Map<string, Page[]>> {
 	}
 
 	taggedPosts.forEach((tagPosts, tag) => {
-		generatePaginated(tagPosts, `/${tag}/`, "site/tag.html.ejs", {
+		generatePaginated(tagPosts, `/${slugify(tag)}/`, "site/tag.html.ejs", {
 			tag
 		}, {
 			title: `${tag} posts`

lib/metadata.ts

@@ -17,11 +17,13 @@ export interface PostMetadata extends Metadata {
 	title: string;
 	slug: string;
 	tags: string[];
+	tagSlugs: string[];
 	date: string | Date;
 	readingTime?: number;
 	wordCount?: number;
 	excerpt?: string;
 	uuid: string;
+	preamble?: string;
 }
 
 export async function get(path: string): Promise<Page> {

site/css/main.scss

@@ -213,7 +213,7 @@ article {
 		h2 { font-size: 1.5rem; }
 		h3 { font-size: 1.4rem; }
 
-		hr.footnotes-sep {
+		hr {
 			border: none;
 			height: 1px;
 			background: var(--accent-color);

site/includes/article-meta.html.ejs

@@ -11,7 +11,7 @@
 	<% if (metadata.tags) { %>
 		in
 		<% for (let i = 0; i < metadata.tags.length; i++) { %>
-			<span itemprop="articleSection"><a href="/<%= metadata.tags[i] %>/" rel="tag"><%= metadata.tags[i] %></a></span><%= i < metadata.tags.length - 1 ? ", " : "" %>
+			<span itemprop="articleSection"><a href="/<%= metadata.tagSlugs[i] %>/" rel="tag"><%= metadata.tags[i] %></a></span><%= i < metadata.tags.length - 1 ? ", " : "" %>
 		<% } %>
 	<% } else if (metadata.series) { %>
 		in

site/layouts/article.html.ejs

@@ -9,6 +9,9 @@ metadata.layout = "default.html.ejs"
 	</h1>
 	<%- include("../includes/article-meta.html.ejs", { metadata }) %>
 	<div class="article-content" itemprop="articleBody">
+		<% if (metadata.preamble) { %>
+			<%- metadata.preamble %>
+		<% } %>
 		<%- content %>
 	</div>
     <details id="comments-container">

site/posts/2021-04-12-lets-build-a-programming-language.md

@@ -1,8 +1,8 @@
 ```
 metadata.title = "Let's Build a Programming Language: Part 0"
-metadata.tags = ["let's build a programming language", "rust"]
+metadata.tags = ["build a programming language", "rust"]
 metadata.date = "2021-04-12 17:27:42 -0400"
-metadata.shortDesc = ""
+metadata.shortDesc = "And learn Rust along the way."
 metadata.slug = "lets-build-a-programming-language"
 ```
 

site/posts/2021-04-13-lexing.md

@@ -0,0 +1,99 @@
+```
+metadata.title = "Part 1: Lexing"
+metadata.tags = ["build a programming language", "rust"]
+metadata.date = "2021-04-13 17:00:42 -0400"
+metadata.shortDesc = "Turning a string into a sequence of tokens."
+metadata.slug = "lexing"
+metadata.preamble = `<p style="font-style: italic;">This post is part of a <a href="/build-a-programming-language/" data-link="/build-a-programming-language/">series</a> about learning Rust and building a small programming language.</p><hr>`
+```
+
+The first part of the language I've built is the lexer. It takes the program text as input and produces a vector of tokens. Tokens are the individual units that the parser will work with, rather than it having to work directly with characters. A token could be a bunch of different things. It could be a literal value (like a number or string), or it could be an identifier, or a specific symbol (like a plus sign).
+
+<!-- excerpt-end -->
+
+I've decided to represent tokens themselves as an enum because there are a bunch of cases without any data (e.g., a plus sign is always just a plus sign) and some with (e.g., a number literal token has a value).
+
+When I was reading the [Rust book](https://doc.rust-lang.org/stable/book/), I was excited to see Rust enums have associated values. Enums with associated data is one of my favorite features of Swift, and I'm glad to see Rust has them too.
+
+```rust
+#[derive(Debug)]
+enum Token {
+	Integer(u64),
+	Plus,
+}
+```
+
+For now, I'm only starting with integer literals and the plus sign. More tokens will come once I've got basic lexing and parsing in place.
+
+Most of the work of turning a string into tokens is done in the *drumroll please...* `tokenize` function.
+
+It creates an initially empty vector of tokens, and starts iterating through characters in the string.
+
+Single character tokens like plus are the easiest to handle. If the current character matches that of a token, consume the character (by advancing the iterator) and add the appropriate token.
+
+```rust
+fn tokenize(s: &str) -> Vec<Token> {
+	let mut tokens: Vec<Token> = Vec::new();
+
+	let mut it = s.chars().peekable();
+	while let Some(c) = it.peek() {
+		if *c == '+' {
+			it.next();
+			tokens.push(Token::Plus);
+		}
+	}
+
+	tokens
+}
+```
+
+Already I've encountered a Rust thing. Inside the while loop, `c` is a reference to a char, so in order to check its value, you have to dereference it. I had expected that you'd be able to compare a value of some type to a reference of that same type (with the language deref'ing the reference automatically), but I can see how forcing the programmer to be explicit about it makes sense.
+
+Next, to parse numbers literals, I check if the current character is in the digit range:
+
+```rust
+const DIGITS: RangeInclusive<char> = '0'..='9';
+
+fn tokenize(s: &str) -> Vec<Token> {
+	// ...
+	while let Some(c) = it.peek() {
+		// ...
+		} else if DIGITS.contains(c) {
+			let n = parse_number(&mut it).unwrap();
+			tokens.push(Token::Integer(n));
+		}
+	}
+}
+```
+
+You may note that even though the integer token takes a signed integer, I'm totally ignoring the possibility of negative number literals. That's because they'll be implemented in the parser along with the unary minus operator.
+
+If the character is indeed a digit, a separate function is called to parse the entire number. This is the first thing that I've encountered for which mutable borrows are quite nice. The `parse_number` function operates on the same data as the `tokenize` function, it needs to start wherever `tokenize` left off, and it needs to tell `tokenize` how much it advanced by. Mutably borrowing the iterator has exactly these properties.
+
+```rust
+fn parse_number<T: Iterator<Item = char>>(it: &mut T) -> Option<i64> {
+	let digits = it.take_while(|c| DIGITS.contains(c));
+	let s: String = digits.collect();
+	s.parse().ok()
+}
+```
+
+Writing the declaration of `parse_number` was a bit rough, I'll admit. I haven't read the generics chapter of the book yet, so I stumbled through a number of compiler error messages (which are very detailed!) until I arrived at this. Having emerged victorious, what I ended up with makes sense though. The specific type of the iterator doesn't matter, but it still needs to be known at the call site during compilation.
+
+The actual implementation takes as many digits as there are from the iterator, turns them into a string, and parses it into an integer. It returns an optional because the `parse` method could fail if the string there were no digit characters at the beginning of the string (this will never happen in the one case I'm calling it, but in case it's reused in the future and I forget...).
+
+Lastly, the `tokenize` function also ignores whitespace just by calling `it.next()` whenever it encounters a whitespace char.
+
+And with that, we can tokenize simple inputs:
+
+```rust
+fn main() {
+	println!("tokens: {:#?}", tokenize("12 + 34"));
+}
+```
+
+```sh
+$ cargo run
+tokens: [Integer(12), Plus, Integer(34)]
+```
+