--- /dev/null
+# 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
--- /dev/null
+{
+ "id": "1696437389086",
+ "createdOn": 1696437389086
+}
\ No newline at end of file
--- /dev/null
+# 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
{
- "id": "1692886191081",
- "createdOn": 1692886191081
+ "id": "1696437389086",
+ "createdOn": 1696437389086
}
\ No newline at end of file
{
- "id": "1689830901871",
- "createdOn": 1689830901871
+ "id": "1692886191081",
+ "createdOn": 1692886191081
}
\ No newline at end of file
+++ /dev/null
-# Link: On-by-default Edge feature seems to be sending all the URLs you visit to Bing
-
-=> https://arstechnica.com/gadgets/2023/04/on-by-default-edge-feature-seems-to-be-sending-all-the-urls-you-visit-to-bing/ On-by-default Edge feature seems to be sending all the URLs you visit to Bing
-> Microsoft's Edge browser has a relatively recent on-by-default feature that allows you to "follow content creators" in Edge itself.
-> The problem is that this feature may be sending information about every single site you visit in Edge to Microsoft.
-
-I feel there’s been a lot of attempts to rehabilitate Microsoft recently, especially from tech people that are all in with Microsoft tooling, but it shouldn’t surprise anyone to see this behavior.
-
-> the feature intended to only notify Bing when you were on specific sites you had elected to follow but that "it doesn’t appear to be working correctly, instead sending nearly every domain you visit to Bing."
-
-sure, bugs happen, but just as well it might have been left there until someone called it out. I’d rather my browser not send *anything* without explicit consent
\ No newline at end of file
{
- "id": "1682553617306",
- "createdOn": 1682553617306
+ "id": "1689830901871",
+ "createdOn": 1689830901871
}
\ No newline at end of file
git.r.bdr.sh / rbdr / blog.unlimited.pizza / commitdiff