rewrite in go

vendor/github.com/sagikazarmark/slog-shim/README.md

@@ -0,0 +1,81 @@
+# [slog](https://pkg.go.dev/log/slog) shim
+
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/sagikazarmark/slog-shim/ci.yaml?style=flat-square)](https://github.com/sagikazarmark/slog-shim/actions/workflows/ci.yaml)
+[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/mod/github.com/sagikazarmark/slog-shim)
+![Go Version](https://img.shields.io/badge/go%20version-%3E=1.20-61CFDD.svg?style=flat-square)
+[![built with nix](https://img.shields.io/badge/builtwith-nix-7d81f7?style=flat-square)](https://builtwithnix.org)
+
+Go 1.21 introduced a [new structured logging package](https://golang.org/doc/go1.21#slog), `log/slog`, to the standard library.
+Although it's been eagerly anticipated by many, widespread adoption isn't expected to occur immediately,
+especially since updating to Go 1.21 is a decision that most libraries won't make overnight.
+
+Before this package was added to the standard library, there was an _experimental_ version available at [golang.org/x/exp/slog](https://pkg.go.dev/golang.org/x/exp/slog).
+While it's generally advised against using experimental packages in production,
+this one served as a sort of backport package for the last few years,
+incorporating new features before they were added to the standard library (like `slices`, `maps` or `errors`).
+
+This package serves as a bridge, helping libraries integrate slog in a backward-compatible way without having to immediately update their Go version requirement to 1.21. On Go 1.21 (and above), it acts as a drop-in replacement for `log/slog`, while below 1.21 it falls back to `golang.org/x/exp/slog`.
+
+**How does it achieve backwards compatibility?**
+
+Although there's no consensus on whether dropping support for older Go versions is considered backward compatible, a majority seems to believe it is.
+(I don't have scientific proof for this, but it's based on conversations with various individuals across different channels.)
+
+This package adheres to that interpretation of backward compatibility. On Go 1.21, the shim uses type aliases to offer the same API as `slog/log`.
+Once a library upgrades its version requirement to Go 1.21, it should be able to discard this shim and use `log/slog` directly.
+
+For older Go versions, the library might become unstable after removing the shim.
+However, since those older versions are no longer supported, the promise of backward compatibility remains intact.
+
+## Installation
+
+```shell
+go get github.com/sagikazarmark/slog-shim
+```
+
+## Usage
+
+Import this package into your library and use it in your public API:
+
+```go
+package mylib
+
+import slog "github.com/sagikazarmark/slog-shim"
+
+func New(logger *slog.Logger) MyLib {
+    // ...
+}
+```
+
+When using the library, clients can either use `log/slog` (when on Go 1.21) or `golang.org/x/exp/slog` (below Go 1.21):
+
+```go
+package main
+
+import "log/slog"
+
+// OR
+
+import "golang.org/x/exp/slog"
+
+mylib.New(slog.Default())
+```
+
+**Make sure consumers are aware that your API behaves differently on different Go versions.**
+
+Once you bump your Go version requirement to Go 1.21, you can drop the shim entirely from your code:
+
+```diff
+package mylib
+
+- import slog "github.com/sagikazarmark/slog-shim"
++ import "log/slog"
+
+func New(logger *slog.Logger) MyLib {
+    // ...
+}
+```
+
+## License
+
+The project is licensed under a [BSD-style license](LICENSE).