admin/wire
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

wire/doc: reformat README.md (google/go-cloud#495)

Browse Source
This commit is contained in:
Robert van Gent
2018-09-28 10:33:08 -07:00
committed by Ross Light
parent ec7cb36215
commit 32c3dc8578
1 changed files with 113 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
README.md
View File

@@ -23,8 +23,8 @@ Wire has two core concepts: providers and injectors.
### Defining Providers
The primary mechanism in Wire is the **provider**: a function that can
produce a value. These functions are ordinary Go code.
The primary mechanism in Wire is the **provider**: a function that can produce a
value. These functions are ordinary Go code.
```go
package foobarbaz
@@ -150,8 +150,8 @@ func initializeBaz(ctx context.Context) (foobarbaz.Baz, error) {
Like providers, injectors can be parameterized on inputs (which then get sent to
providers) and can return errors. Arguments to `wire.Build` are the same as
`wire.NewSet`: they form a provider set. This is the provider set that gets
used during code generation for that injector.
`wire.NewSet`: they form a provider set. This is the provider set that gets used
during code generation for that injector.
Any non-injector declarations found in a file with injectors will be copied into
the generated file.
@@ -206,9 +206,9 @@ injectors.
Frequently, dependency injection is used to bind a concrete implementation for
an interface. Wire matches inputs to outputs via [type identity][], so the
inclination might be to create a provider that returns an interface type.
However, this would not be idiomatic, since the Go best practice is to [return
concrete types][]. Instead, you can declare an interface binding in a provider
set:
However, this would not be idiomatic, since the Go best practice is to
[return concrete types][]. Instead, you can declare an interface binding in a
provider set:
```go
type Fooer interface {
@@ -233,9 +233,9 @@ var BarFooer = wire.NewSet(
```
The first argument to `wire.Bind` is a pointer to a value of the desired
interface type and the second argument is a zero value of the concrete type.
Any set that includes an interface binding must also have a provider in the
same set that provides the concrete type.
interface type and the second argument is a zero value of the concrete type. Any
set that includes an interface binding must also have a provider in the same set
that provides the concrete type.
[type identity]: https://golang.org/ref/spec#Type_identity
[return concrete types]: https://github.com/golang/go/wiki/CodeReviewComments#interfaces
@@ -289,8 +289,8 @@ And similarly if the injector needed a `*FooBar`.
### Binding Values
Occasionally, it is useful to bind a basic value (usually `nil`) to a type.
Instead of having injectors depend on a throwaway provider function, you can
add a value expression to a provider set.
Instead of having injectors depend on a throwaway provider function, you can add
a value expression to a provider set.
```go
type Foo struct {
@@ -313,9 +313,9 @@ func injectFoo() Foo {
```
It's important to note that the expression will be copied to the injector's
package; references to variables will be evaluated during the injector
package's initialization. Wire will emit an error if the expression calls
any functions or receives from any channels.
package; references to variables will be evaluated during the injector package's
initialization. Wire will emit an error if the expression calls any functions or
receives from any channels.
For interface values, use `InterfaceValue`:
@@ -325,6 +325,7 @@ func injectReader() io.Reader {
return Foo{}
}
```
### Cleanup functions
If a provider creates a value that needs to be cleaned up (e.g. closing a file),
@@ -370,8 +371,8 @@ over time.
### Distinguishing Types
If you need to inject a common type like `string`, create a new string type
to avoid conflicts with other providers. For example:
If you need to inject a common type like `string`, create a new string type to
avoid conflicts with other providers. For example:
```go
type MySQLConnectionString string
@@ -404,11 +405,11 @@ without breaking compatibility are:
- Change which provider a provider set uses to provide a specific output, as
long as it does not introduce a new input to the provider set. It may remove
inputs. However, note that existing injectors will use the old provider until
they are regenerated.
- Introduce a new output type into the provider set, but only if the type itself
is newly added. If the type is not new, it is possible that some injector
already has the output type included, which would cause a conflict.
inputs. However, note that existing injectors will use the old provider
until they are regenerated.
- Introduce a new output type into the provider set, but only if the type
itself is newly added. If the type is not new, it is possible that some
injector already has the output type included, which would cause a conflict.
All other changes are not safe. This includes: