Skip to content

Commit

Permalink
docs: update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
widmogrod committed Jun 1, 2024
1 parent 2605e86 commit b90c3bd
Show file tree
Hide file tree
Showing 3 changed files with 16 additions and 21 deletions.
2 changes: 0 additions & 2 deletions docs/examples/generic_union.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,6 @@ You can use `mkunion` to create a union type for the tree:
```go title="example/tree.go"
package example

//go:generate go run ../cmd/mkunion/main.go

//go:tag mkunion:"Tree"
type (
Branch[A any] struct{ L, R Tree[A] }
Expand Down
26 changes: 9 additions & 17 deletions docs/getting_started.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,6 @@ But in a more complex example you may want to represent different states of your
```go title="example/vehicle.go"
package example

//go:generate mkunion

//go:tag mkunion:"Vehicle"
type (
Car struct {
Expand All @@ -33,21 +31,15 @@ type (

In above example you can see a few important concepts:

#### `//go:generate mkunion`

Go generate directive runs `mkunion` command that you installed in previous step.
It will generate union type and pattern matching functions for you.

#### `//go:tag mkunion:"Vehicle"`

Tag are powerful and flexible way to add metadata to your code.
You may be familiar with tags when you work with JSON in golang

```go
type User struct {
Name string `json:"name"`
Name string `json:"name"`
}

```

Unfortunately Golang don't extend this feature to other parts of the language.
Expand All @@ -64,30 +56,30 @@ And MkUnion use it heavily to offer way of adding new behaviour to go types.
```go
//go:tag mkunion:",no-type-registry"
package example

```

#### `type (...)` convention

Union type is defined as a set of types in a single type declaration. You can think of it as "one of" type.
To make it more readable, as convention I decided to use `type (...)` declaration block, instead of individual `type` declaration.

### Generate code
In IDEs like Goland run `Option + Command + G` for fast code generation
### Generate code and watch for changes

Or, run in your terminal
Run in your terminal to generate union type for your code and watch for changes
```
go generate ./...
mkunion watch ./...
```

To generate unions without watching for changes, you can run
```
mkunion watch -g ./...
```

Alternatively you can run `mkunion` command directly
```
mkunion -i example/vehicle.go
```

In future I plan to add `mkununion watch ./...` command that will watch for changes in your code and automatically generate union types for you.
This will allow you to remove `//go:generate` directive from your code, and have faster feedback loop.

### Match over union type
When you run `mkunion` command, it will generate file alongside your original file with `union_gen.go` suffix (example [vehicle_union_gen.go](https://github.com/widmogrod/mkunion/tree/main/example/vehicle_union_gen.go))

Expand Down
9 changes: 7 additions & 2 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,6 @@ MkUnion solves all of those problems, by generating opinionated and strongly typ
```go title="example/vehicle.go"
package example

//go:generate mkunion

// union declaration
//go:tag mkunion:"Vehicle"
type (
Expand Down Expand Up @@ -83,6 +81,13 @@ func ExampleFromJSON() {
}
```

Watch for changes in the file and generate code on the fly:
```sh
mkunion watch ./...

# or use -g flag to generate code without watching
mkunion watch -g ./...
```

## Next

Expand Down

0 comments on commit b90c3bd

Please sign in to comment.