This getting started tutorial shows a simple example on how to use repogen. You can also see the working code inside `examples` directory for more information.
### Step 1: Download and install repogen
Run this command in your terminal to download and install repogen
Write repository specification as an interface in the same file as the model struct. There are 5 types of operations that are currently supported and are determined by the first word of the method name. Single-entity and multiple-entity modes are determined be the first return value. More complex queries can also be written.
You can also write the above command in the `go:generate` format inside Go files in order to generate the implementation when `go generate` command is executed.
To begin, your method name must be in pascal-case (camel-case with beginning uppercase letter). Repogen determines an operation for a method by getting the **first word** of the method name. There are 5 supported words which refer to 5 supported operations.
1.`Insert` - Stores new data to the database
2.`Find` - Retrives data from the database
3.`Update` - Changes some fields of the data in the database
4.`Delete` - Removes data from the database
5.`Count` - Retrieves number of matched documents in the database
Each of the operations has their own requirements for the method name, parameters and return values. Please consult the documentation for each operation for its requirements.
#### Insert operation
An `Insert` operation has a very limited use case, i.e. inserting a single document or multiple documents. So, it is quite limited in method parameters and method returns. An insert method can only have one of these signatures.
```go
// InsertOne inserts a single document
InsertOne(ctx context.Context, model *Model) (interface{}, error)
Repogen determines a single-entity operation or a multiple-entity by checking the second parameter and the first return value. However, the operation requires the first parameter to be of type `context.Context` and the second return value to be of type `error`.
As the `Insert` operation has a limited use case, we do not want to limit you on how you name your method. Any method that has the name starting with the word `Insert` is always valid. For example, you can name your method `InsertAWholeBunchOfDocuments` and it will work as long as you specify method parameters and returns correctly.
#### Find operation
A `Find` operation also has two modes like `Insert` operation: single-entity and multiple-entity. However `Find` operation can be very simple or complex depending on how complex the query is. In this section, we will show you how to write single-modes and multiple-entity modes of find method with a simple query. For more information about more complex queries, please consult the query specification section in this document.
```go
// FindByID gets a single document by ID
FindByID(ctx context.Context, id primitive.ObjectID) (*Model, error)
// FindByCity gets all documents that match city parameter
FindByCity(ctx context.Context, city string) ([]*Model, error)
Repogen determines a single-entity or a multiple-entity operation by checking the first return value. If it is a pointer of a model, the method will be single-entity operation. If it is a slice of pointers of a model, the method will be multiple-entity operation.
The requirement of the `Find` operation method is that there must be only two return values, the second return value must be of type `error` and the first method parameter must be of type `context.Context`. The requirement of number of method parameters depends on the query which will be described in the query specification section.
#### Update operation
An `Update` operation also has two modes like `Insert` and `Find` operations: single-entity and multiple-entity. An `Update` operation also supports querying like `Find` operation. However, an `Update` operation requires more parameters than `Find` method, i.e. new values of updating fields. Specifying the query is the same as in `Find` method but specifying the updating fields are a little different.
```go
// UpdateDisplayNameAndCityByID updates a single document with a new display name and
// city by ID
UpdateDisplayNameAndCityByID(ctx context.Context, displayName string, city string,
id primitive.ObjectID) (bool, error)
// UpdateGenderByCity updates Gender field of documents with matching city parameter
UpdateGenderByCity(ctx context.Context, gender Gender, city string) (int, error)
```
Repogen determines a single-entity operation or a multiple-entity by checking the first return value. If it is of type `bool`, the method will be single-entity operation. If it is of type `int`, the method will be multiple-entity operation. For single-entity operation, the method returns true if there is a matching document. For multiple-entity operation, the integer return shows the number of matched documents.
The requirement of the `Update` operation method is that there must be only two return values, the second return value must be of type `error` and the first method parameter must be of type `context.Context`. The requirement of number of method parameters depends on the number of updating fields and the query. Updating fields must be directly after context parameter and query fields must be directly after updating fields.
#### Delete operation
A `Delete` operation is the very similar to `Find` operation. It has two modes. The method name pattern is the same. The method parameters and returns are also almost the same except that `Delete` operation has different first return value of the method. For single-entity operation, the method returns true if there is a matching document. For multiple-entity operation, the integer return shows the number of matched documents.
```go
// DeleteByID deletes a single document by ID
DeleteByID(ctx context.Context, id primitive.ObjectID) (bool, error)
// DeleteByCity deletes all documents that match city parameter
DeleteByCity(ctx context.Context, city string) (int, error)
// DeleteAll deletes all documents
DeleteAll(ctx context.Context) (int, error)
```
#### Count operation
A `Count` operation is also similar to `Find` operation except it has only multiple-entity mode. This means that the method returns are always the same for any count operations. The method name pattern and the parameters are the same as `Find` operation.
```go
// CountByGender returns number of documents that match gender parameter
A query can be applied on `Find`, `Update`, `Delete` and `Count` operations. The query specification starts with `By` or `All` word in the method name.
-`All` is used for querying all documents of the given type in the database. It is simple because only one word `All` is enough for repogen to understand. For example, `FindAll`, `UpdateCityAll` and `DeleteAll`.
-`By` is used for querying by a set of fields with specific operators. It is more complicated than `All` query but not be too difficult to understand. For example, `FindByGenderAndCity` and `DeleteByAgeGreaterThan`.
#### Specifying fields to query
You can write a query by specifying field name after `By` such as `ByID`. In case that you have multiple fields to query, you can connect field names with `And` or `Or` word such as `ByCityAndGender` and `ByCityOrGender`. `And` and `Or` operators are different in their meaning so the query result will be also different.
After specifying query to the method name, you also need to provide method parameters that match the given query fields. The example is given below:
```go
FindByCityAndGender(ctx context.Context, city string, gender Gender) ([]*UserModel, error)
```
Assuming that the `City` field in the `UserModel` struct is of type `string` and the `Gender` field in the `UserModel` struct is of custom type `Gender`, you have to provide `string` and `Gender` type parameters in the method.
#### Comparators to each field
When you specify the query like `ByAge`, it finds documents that contains age value **equal to** the provided parameter value. However, there are other types of comparators provided for you to use as follows.
-`Not`: The value in the document is not equal to the provided parameter value.
-`LessThan`: The value in the document is less than the provided parameter value.
-`LessThanEqual`: The value in the document is less than or equal to the provided parameter value.
-`GreaterThan`: The value in the document is greater than the provided parameter value.
-`GreaterThanEqual`: The value in the document is greater than of equal to the provided parameter value.
-`Between`: The value in the document is between two provided parameter values (inclusive).
-`In`: The value in the document is in the provided parameter value (which is a slice).
To apply these comparators to the query, place these words after the field name such as `ByAgeGreaterThan`. You can also use comparators along with `And` and `Or` operators. For example, `ByGenderNotOrAgeLessThan` will apply `Not` comparator to the `Gender` field and `LessThan` comparator to the `Age` field.
`Between` and `In` comparators are special in terms of parameter requirements. `Between` needs two parameters to perform the query and `In` needs a slice instead of its raw type. The example is provided below:
Assuming that the `Age` field in the `UserModel` struct is of type `int`, it requires that there must be two `int` parameters provided for `Age` field in the method. And assuming that the `City` field in the `UserModel` struct is of type `string`, it requires that the parameter that is provided to the query must be of slice type.
