╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                              ║
║                         The Blog at Unlimited Pizza                          ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝
┌──────────────────────────────────────────────────────────────────────────────┐
│                       Written by Rubén Beltrán del Río                       │
└──────────────────────────────────────────────────────────────────────────────┘


# API Notation Updates

A few years ago I created an API notation to use with software specification documents: Back then I was working in a team that relied heavily on software specifications, and we were maintaining projects in objective-c, ruby, and javascript, so the notation emerged out of the need to communicate the public APIs in a way that was generic enough to make implementation in any language simple, while concise enough to avoid integration issues.

For example, I could use it to describe the library I use to build this blog[1]

```
// Library to generate an ephemeral html blog with a gemini archive
Blog
  -max_posts <Int>
  -posts_directory <String>
  -archive_directory <String>
  -static_directory <String>
  -templates_directory <String>
  -remote_config <String>
  #add(post_location <String>) => Promise<Void>
  #update(post_location <String>) => Promise<Void>
  #publish(host <String>) => Promise<Void>
  #publish_archive(host <String>) => Promise<Void>
  #add_remote(remote <String>) => Promise<Void>
  #remove_remote() => Promise<Void>
  #sync_down() => Promise<Void>
  #sync_up() => Promise<Void>
  #generate() => Promise<Void>
```

=> https://git.sr.ht/~rbdr/blog/tree/main/item/lib/blog.js [1] A Javascript implementation of that API

I had been using it unchanged for almost ten years, but recently decided to drop a specific symbol for callbacks, and instead add a "Throws" symbol #>. You can see the definition here, or in its home page[2]

```
// Anything after two forward slashes is a comment
NameOfClass.WithPossibleNamespace
   + class property
   - instance property
  ~> listened events (socket)
  +> listened events (class/module)
  -> listened events (instance)
  <~ dispatched events (socket)
  <+ dispatched events(class/module)
  <- dispatched events (instance)
  :: class method
   # instance method

Other symbols
  => returns
  #> throws
[xx] optional
<data type>

Recommended order: class first, then sockets, then instance. Internally:
Properties, events, methods.
```

One of the patterns that I started using for functions is to instead define the whole function signature as part of the type definition. So for example, if you have a method that receives a function as an argument, you could write the following:

```
GenericManipulator
  #manipulate<T>(input T, manipulator<T>(input T, options <ManipulationOptions>) => T #> ManipulationError) => T #> ManipulationError
```

I've found this pattern covers most cases where I need to pass a function.

In slightly related news, since I've recently moved fully to using `neovim`, I've also created a tree-sitter parser[3] that you can use as a neovim plugin. It was really fun to learn, but the documentations was clear and easy to follow. A bit less easy to follow was how to get the syntax highlighting to actually work with neovim, but it ended up working.

=> https://www.unlimited.pizza/api.html [2] API definition
=> https://git.sr.ht/~rbdr/tree-sitter-api-notation [3] tree-sitter parser and neovim plugin.

If you use other editors, there's older versions of the plugin available for vim[4], vscode[5], and TextMate / Sublime Text[6]. They don't support the #> throws notation.

=> https://git.sr.ht/~rbdr/api-notation.vim [4] Syntax for vim
=> https://git.sr.ht/~rbdr/api-notation.vscode [5] Syntax for vscode
=> https://git.sr.ht/~rbdr/api-notation.tmLanguage [6] Syntax for TextMate and Sublime text

■──────────────────────────────────────────────────────────────────────────────■

# Link: The first conformant M1 GPU driver

=> https://rosenzweig.io/blog/first-conformant-m1-gpu-driver.html The first conformant M1 GPU driver
> Conformant OpenGL® ES 3.1 drivers are now available for M1- and M2-family GPUs. 

> To become conformant, an “implementation” must pass the official conformance test suite, designed to verify every feature in the specification. The test results are submitted to Khronos, the standards body. After a 30-day review period, if no issues are found, the implementation becomes conformant. The Khronos website lists all conformant implementations, including our drivers for the M1, M1 Pro/Max/Ultra, M2, and M2 Pro/Max. 

The work the Asahi team is doing is simply incredible! I’ve been using the arch based flavor for a while now, and it’s been a great experience. I replaced i3 with sway now that hardware acceleration is working properly and it’s very smooth. Linux is blazing fast in Apple Silicon machines.

I know there’s still a lot of work to do, and I’m very thankful to the Asahi team for all of the effort. Can’t wait to see how it continues!

If you haven’t tried it, I recommend you give it a go!
■──────────────────────────────────────────────────────────────────────────────■

# Link: 🏕️ DWeb debrief: 10 new apps for groups & communities.

=> https://newpublic.substack.com/p/dweb-debrief-10-new-apps-for-groups 🏕️ DWeb debrief: 10 new apps for groups & communities.
I love seeing how different apps are approaching community building, and this list is great!

> Hylo is an up & coming community platform with a powerful ‘holonic’ structure that enables coordination within and across groups. It’s run as a non-profit so they don’t have built-in incentives to design for addiction, and their code base is fully open-source.

I like the idea of having communities that can then share and connect with a larger group. It's unfortunate that it's not decentralized like some of the ones below, but it also looks more mature.

> Futureproof, Neighbourhoods, and We are three separate projects building decentralized community platforms with high levels of community-control and modularity.

I was unaware of Holochain[1] but it's interesting, it reminds me of scuttlebutt but with more of a focus on giving non-tech folks the benefit of a distributed environment. I tried setting up a group with We and it seems simple enough: not many applets yet, but already I can see why I'd rather use a tool like this to organize, rather than a cloud-hosted service.

=> https://www.holochain.org/ [1] Holochain

> Group Income is a brand new product from the non-profit OkTurtles that makes it easy for groups of friends & communities to create a basic income for themselves among one another. [2]

This is a really cool idea! It seems a bit sparse in details as it's being built up, but I'll keep an eye on this, as it has a lot of potential to change how groups of friends can organize and create a better economic safety net.

=> https://groupincome.org/ [2] Group Income

There's a few other good projects in the post, but I still have to go through them and try the services. Definitely check them all out!
■──────────────────────────────────────────────────────────────────────────────■