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