DEV Community: Code Monk

Flargs: parsimonious parsing of flags and arguments

Code Monk — Thu, 02 May 2024 03:07:51 +0000

While working on a small CLI for encrypting and decrypting files, I found myself unstatisfied with the practice of writing, and testing, and reasoning about a CLI in Go. The flag package was not pleasant to work with. Testing was hard and inelegant, and the whole concept of a CLI is leaky. So I pulled out my hair, and cursed at the sky.

Then, I distilled the problem down its constiuent parts, and wrapped them in Flargs. At it’s heart, Flargs is a very simple framework that forces you to do a few things, and in return gives you ease, power, and reproducibility. This is the Hermetic promise: If you never touch the world, you will become divine.

Flargs has three run-time phases:

Parsing. This execution phase gives you no access to your command or the environment it will run against. All you have is a “Konf”, a []string{}, and the logic to turn the latter into the former. If you return an error here, the program stops.
Loading. In this phase you do have access to the environment. Here you can decide if you Konf makes sense in this environment. For instance, you can check to see that a file actually exists. If you return an error, execution stops.
Running. This is actually what makes your CLI useful. The run phase has no access to the original []string{}. It has a Konf and an Environment.

Read Moar: https://www.seanmacdonald.ca/posts/flargs/

Ergonomic Trees in Go

Code Monk — Sun, 25 Feb 2024 17:45:58 +0000

While working on a recursive file-watcher I came upon an elegant way to express trees in Go. This approach works well in cases where each sibling node must have a unique value and that value cannot be the zero value (as in a filesystem). In practice, this is most trees.

A tree is a data structure that contains data in a hierarchy whereby one parent has as many children as it wants, and those children can have children, and so on.

Let us imagine a folder named "Primates", containing sub-folders, which themselves contain more sub-folders and/or text files:

.
└── Primates
    └── Apes
        └── Great Apes
            ├── African Apes
            │   └── Gorillas
            │       ├── Eastern Gorilla.txt
            │       └── Western Gorilla.txt
            ├── Chimpanzees
            │   ├── Bonobo
            │   └── Chimpanzee
            ├── Homo Sapien.txt
            └── Orangutans
                ├── Bornean Orangutan.txt
                └── Sumatran Orangutan.txt

In terms of behaviour, strictly speaking, a tree needs only two methods (although more are often provided for convenience and optimisation).

type Node[T comparable] interface {
    Data() T
    Children []Node[T]
}

Where T is the data we care about. In the example above, T is string, and that string represents the folder or file name. So we might begin to build our tree of life like so:

lifeTree := createTree[string]()
primates := lifeTree.AddChild("Primates")
apes := primates.AddChild("Apes")
// etc...

But how do we power this data structure, in terms of a concrete type? The canonical way is to use a struct.

type node[T comparable] struct {
    data T
    children []*node[T]
}

This is perfectly fine. But there is a more ergonomic way, made possible because of two important characteristics of maps in Go:

a map can be defined recursively
the zero-value for a map is nil

// recusively defined node
type node[T comparable] map[T]node[T]

Here, we're defining a map type whose keys are the values we care about, and whose values are... other maps whose keys are values we care about.

Remember that Node is the only object we need to define, because a tree can be said to be it's root node.

Keys of maps need not be simple strings or ints, but they need to satisfy the comparable type constraint.

Leaf nodes (in our example, text files) are nil maps. They terminate recursion. A recusive data structure is not useful without a base case. We do not wish to swallow the universe.

So how might we implement the Node[T] interface using the node[T] concrete type? Let's look at a basic interface, and then dive in.

type Node[T comparable] interface {
    Data() T
    Children map[T]Node[T]
    Set(T)
    Get(T) Node[T]
    AddChild(T) Node[T]
    RemoveChild(T)
}

Children()

This is the simplest. A node is precisely defined as it's children, so:

func (n *node[T]) Children() map[T]Node[T] {
    return n
}

Set(T)

This will be used to set leaf nodes. To set non-leaf nodes (branches) we'll be using AddChild()

func (n *node[T]) Set(key T) {
    n[key] = nil
}

Remember, key is meaningful here. it's not a lookup key. It's the data we care about.

AddChild()

Here's where we get to define our hierachy and enable actual tree behaviour

func (n *node[T]) AddChild(key T) Node[T] {
    branch := new(node[T])
    n[key] = branch
}

Data()

This is a little bit trickier. Since a Node is entirely defined as the map that represents it's children, where does it's Data(), the data we care about, come from?

The answer is that the Data() of a node is the key of parent that contains that node. This makes perfect sense when you think about a filesystem. A folder name only makes sense in the context of where it sits in the hierarchy. The uniqueness constraint of it's name comes from it's parent. To change a folder name is to change nothing about the folder itself and it's behaviour, but it does change how it's parent addresses it.

Here is where you begin to see that it would be useful (though strictly speaking not necessary) for a node to have a link back to it's parent. To use our folder example, we would like to have our special ".." file in our directory listing. It makes traversing the filesystem way easier, and certain operations way more efficient.

But how can this be done using a map? According to the Go Proverbs, we should Make the Zero Value Useful. Remember that we do not allow our users to use the zero-value (for example, a file or folder name cannot be blank). We will use that special value for ourselves.

So then, a constructor function might now look like this:

func New[T comparable](parent Node[T]) Node[T] {
    var zeroK K // auto initialized to zero value
    branch := new(node[T])

    // tell the child where the parent is
    branch[zeroK] = parent

    return branch

}

// the root node has no parent
myExampleTree := New[string](nil)
myBranch := myExampleTree.AddChild("some branch")

... requiring us to augment certain methods:

func (n *node[T]) AddChild(key T) Node[T]) {

   // tell the parent where the child is
   n[key] = New[T](n)

}

In my view, this is an elegant approach to building trees satisfying the two aformentioned constraints (must be comparable, can't be zero). I wrote a more full-featured implementation of this that includes the following method set for common efficient tree operations.

type Node[K comparable] interface {
    Data() K
    Children() map[K]Node[K]
    Spawn(K) Node[K]
    RemoveChild(K)
    Parent() Node[K]
    Walk() [][]K
    Ancestry() []K
    IsTerminal() bool
    Set(K)
    Get(K) (Node[K], bool)
    SetParent(Node[K])
    fmt.Stringer
}

Use it: https://pkg.go.dev/github.com/sean9999/go-ergonomic-tree#section-readme

Fork it: https://github.com/sean9999/go-ergonomic-tree/tree/v0.0.1

Go Functional

Code Monk — Thu, 11 May 2023 21:07:50 +0000

Go Functional is a Go package providing Functional Programming capabilities to Go.

What is Functional Programming?

Functional Programming is a style, most notably employed by LISP, Haskell, F#, Clojure, and Erlang, which (to various degrees) offer the following characteristics:

Functions handle most of the logic
Functions are pure. The only thing a function knows is what's passed into it. It cannot mutate it's inputs. It can only produce new outputs.
Functions are first-class citizens. They can be passed as parameters to other functions.
Functions can be chained. The output of one function can be the input of another. At the end of the chain, you get the data you want.

This is an extremely expressive style that makes reading and writing code a delight.

What does it look like?

There are many examples on the official docs, but in a nutshell, Go Functional works like this:

import (
    "github.com/sean9999/GoFunctional/fslice"
)

//  apply a filter function and then a map function to get squares of primes
inputNums := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11}

outputNums := fslice.From(inputNums).Filter(func(v int, _ int, _ []int) bool {
    return primes.IsPrime(v)
}).Map(func(v int, _ int, _ []int) int {
    return v * v
})

fmt.Println(outputNums)
// Output: [4 9 25 49 121]

In the above, we take in a slice of integers, filter out all those that are not prime, square the remaining, and return that. We pass our user-defined functions into fslice.Map and fslice.Filter directly as anonymous functions, but this could just as easily be done differently.

onlyPrimes := func(val int, _ int, _ []int) {
    return primes.IsPrime(val)
}

square := func() {
    return val * val
}

outputNums := fslice.From(inputNums).Filter(onlyPrimes).Map(square)

fmt.Println(outputNums)
// Output: [4 9 25 49 121]

The above might be considered more readable than the previous. They are functionally equivilant.

The general pattern that Fslice employs is this:

Every Fslice method takes a user-defined function
That user-defined function usually takes three parameters: value, index, and the underlying slice in it's entirety.
The user-defined function is called for every element in the slice, or as many times as necessary (if it can quit early, it will).

So, for example Fslice.Map() takes a user-defined function matching the signature MapFunction. The user-defined function takes one value and produces another value of the same type. Since Fslice.Map() calls that function for every element of the slice, the return value is another slice.

Often you'll only need the value in your user-defined function, but sometimes you need the full set of parameters. Here is an example of an fslice method returning early because it has all the information it needs, and makes use of all three parameters:

import (
    "github.com/fxtlabs/primes"
    "github.com/sean9999/GoFunctional/fslice"
)

// are any two sequential integers co-prime?
inputSlice := []int{1,2,3,4,5,6,7,8,9,20,24,665,771}

isCoPrimeWithPrevious := func(n int, i int, arr []int) bool {
    if n > 0 {
        m := arr[i-1]
        return primes.Coprime(m, n)
    }
    return false
}

answer := fslice.From(inputSlice).Some(isCoPrimeWithPrevious)

fmt.Println(answer)
// Output: true

The set of methods and their signatures was inspired by the Javascript spec for iterative methods on arrays. Some array methods in Javascript mutate the underlying array. Go Functional avoids these. It aims to be more respectful of Functional Programing principles.

What's Next?

I would like to find a semi-authoritative set of methods, aside from Javascript, to base the work on.

I would like to develop Fmap, in the same manner as Fslice.

I would like to find a way to provide greater polymorphism by introducting the concept of a Functor. This could free the developer from having to restrict themselves to just one type (int, float64, string, etc) at a time.

Pull requests enthusiastically welcomed.

Read the blog post
Discuss on Hacker News