Skip to content

Commit

Permalink
reformat README and stop trying to get a job
Browse files Browse the repository at this point in the history
  • Loading branch information
dave4420 committed Feb 4, 2024
1 parent a839129 commit 449729b
Showing 1 changed file with 41 additions and 42 deletions.
83 changes: 41 additions & 42 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,109 +1,105 @@
# gen-elm-wrappers

You are writing an Elm program. You have a custom type, which you would
You are writing an Elm program. You have a custom type, which you would
like to use for the keys of a `Dict`, or the elements of a `Set`.
Unfortunately, for both of these cases, your type has to be `comparable`,
and custom types cannot be `comparable`. What to do?
and custom types cannot be `comparable`. What to do?

Solution: add some config to your `elm.json`, run `gen-elm-wrappers`,
and it will generate one or more Elm modules that wrap `Dict` or `Set`,
so that you can use them with your custom type.


## Installing

I haven’t wrapped this all up nicely in an NPM package yet.

For now, you need to run:

- `brew install go`
- don’t worry, you don’t need to know Go to _use_ this
- don’t worry, you don’t need to know Go to _use_ this
- `npm ci`
- `npm test`

Assuming the tests all pass, this builds a `gen-elm-wrappers` executable.
Copy it to somewhere on your `$PATH`.


## Using

Create a `gen-elm-wrappers.json` file. This needs to contain an
Create a `gen-elm-wrappers.json` file. This needs to contain an
object which (will eventually contain more config data, but currently
only) contains a `generate` key holding an array of module definitions.

To wrap `Dict`, the module definition is an object containing these keys:

- `underlying-type`
- Must be `"Dict"`
- Must be `"Dict"`
- `wrapper-type`
- The fully-qualified name of the type to generate. The generated
code will be stored in the module named here. e.g. to generate
a `Foo.Bar` module containing a `MyDict` type, you would put
`"Foo.Bar.MyDict"` here
- The fully-qualified name of the type to generate. The generated
code will be stored in the module named here. e.g. to generate
a `Foo.Bar` module containing a `MyDict` type, you would put
`"Foo.Bar.MyDict"` here
- `public-key-type`
- The fully-qualified name of your custom type that you want to use
as keys
- The fully-qualified name of your custom type that you want to use
as keys
- `private-key-type`
- The type of keys to use in the underlying `Dict`. This will
typically be `Int` or `String`, but can be any concrete
`comparable` type
- The type of keys to use in the underlying `Dict`. This will
typically be `Int` or `String`, but can be any concrete
`comparable` type
- `public-key-to-private-key`
- The fully-qualified name of a function that converts values from
`public-key-type` to `private-key-type`. i.e. it has a type
like `PublicKey -> PrivateKey`
- The fully-qualified name of a function that converts values from
`public-key-type` to `private-key-type`. i.e. it has a type
like `PublicKey -> PrivateKey`
- `private-key-to-public-key`
- The fully-qualified name of a function that converts values from
`private-key-type` to `public-key-type`. It has a type
like `PrivateKey -> Maybe PublicKey`. You can’t use a function
with a type like `PrivateKey -> PublicKey` here — you may need
to write a wrapper function in your code with the correct type
- The fully-qualified name of a function that converts values from
`private-key-type` to `public-key-type`. It has a type
like `PrivateKey -> Maybe PublicKey`. You can’t use a function
with a type like `PrivateKey -> PublicKey` here — you may need
to write a wrapper function in your code with the correct type

(Currently only `Dict` is supported.)

Then, run `gen-elm-wrappers`. It expects `elm.json` to be in the
current directory. It writes the generated code to the appropriate
Then, run `gen-elm-wrappers`. It expects `elm.json` to be in the
current directory. It writes the generated code to the appropriate
location inside your `src` directory.

For `Dict`s, the generated code wraps all functions from the core `Dict`
module. If your program also has `elm-community/dict-extra` as a direct
module. If your program also has `elm-community/dict-extra` as a direct
dependency, it will also wrap several functions from `Dict.Extra`.

If `elm-format` is on your PATH (and not a relative path, i.e. not
starting with `.` or `..`) then the generated code will be beautifully
formatted. (This is the case, for example, when `elm-format` and
formatted. (This is the case, for example, when `elm-format` and
`gen-elm-wrappers` were both installed locally using npm, and you’re
running `gen-elm-wrappers` via npm.)


## Examples

See the [`bin/test.sh`](bin/test.sh) script.


## Portability

I’ve only tested this on my Mac. But it’s written in Go, and I hear
I’ve only tested this on my Mac. But it’s written in Go, and I hear
Go’s really portable, so presumably it should also run on \*BSD, various
Linuxes, Windows, smart toasters, ZX-81, etc.

Actually… the test script won’t run on Windows. (Unless you use WSL?)

Actually… the test script won’t run on Windows. (Unless you use WSL?)

## Roadmap

This isn’t in priority order yet and I’ve probably forgotten something.

- Wrap it all up nicely in an NPM package that includes/downloads
prebuilt binaries (like the `elm` NPM package does)
prebuilt binaries (like the `elm` NPM package does)
- Support `Set`
- Support type variables in key types
- Support versions of `elm-community/dict-extra` before 2.4.0
- Wrap more functions from `elm-community/dict-extra`
- Support writing the generated code to a directory other than `src`;
optionally wipe it first
optionally wipe it first
- Write more unit tests around reading the config from `elm.json`
- Improve error messages when something’s wrong in `elm.json`
- Validate identifiers in the config (instead of blindly writing them
out and letting Elm complain about them)

out and letting Elm complain about them)

## Development

Expand All @@ -118,17 +114,20 @@ component tests.
If you `brew install fswatch` then you can `npm run test:go:watch`.
This runs the unit tests whenever the source code changes.


## If you’re a hiring manager or a recruiter

I’m looking for a job, yes.
I’m not looking for a job, no.

- Senior/lead roles
- Senior / tech lead roles
- Full stack or backend
- Permanent only (no contracting)
- Remote (UK timezone ± 1 hour) or on-site/hybrid (London/Medway)
- IC only (no line management)
- Remote (UK timezone ± 1 hour) or on-site/hybrid (London/Medway); not willing to relocate
- I prefer to work with statically typed languages (e.g. Typescript, not plain Javascript)
- not blockchain (except for catching crims), not ad tech (unless it’s surveillance-free),
don’t really want to work for a hedge fund
- Ich kann ein bisschen Deutsch sprechen, aber mein Deutsch ist schlect
und Englisch is meine Muttersprache.
und Englisch is meine Muttersprache.

Please [connect to me on LinkedIn](https://www.linkedin.com/in/dave-hinton-7507b4ab)
and mention this repo in your invitation.

0 comments on commit 449729b

Please sign in to comment.