From 993153693a33e7bb72c6fe4200036f2a55334b00 Mon Sep 17 00:00:00 2001 From: Gregory Eremin Date: Tue, 3 Jul 2018 20:33:55 +0200 Subject: [PATCH] Move readme parts to their corresponding packages --- README.md | 127 +++++-------------------------------------- config/README.md | 40 ++++++++++++++ filecache/README.md | 20 +++++++ log/README.md | 27 +++++++++ set/README.md | 26 +++++++++ threadpool/README.md | 22 ++++++++ 6 files changed, 148 insertions(+), 114 deletions(-) create mode 100644 config/README.md create mode 100644 filecache/README.md create mode 100644 log/README.md create mode 100644 set/README.md create mode 100644 threadpool/README.md diff --git a/README.md b/README.md index acec246..ab9093b 100644 --- a/README.md +++ b/README.md @@ -1,117 +1,16 @@ # Gobelt -Gobelt is a collection of Go tools. +Gobelt is a collection of Go tools that I got tired of implementing again and +again. -### Thread pool - -```go -import "github.com/localhots/gobelt/threadpool" -``` - -```go -ctx := context.Background() -ctx, cancel = context.WithTimeout(ctx, 30*time.Second) -defer cancel() - -pool := threadpool.New(10) -defer pool.Close() -for i := 0; i < 1000000; i++ { - i := i - pool.Enqueue(ctx, func() { - fmt.Printf("The number is %d\n", i) - }) -} -``` - -### File cache - -```go -import "github.com/localhots/gobelt/filecache" -``` - -```go -ctx := context.Background() -var items []Item -filecache.Load(&items, "tmp/cache/items.json", func() { - err := conn.Query(ctx, "SELECT * FROM items").Load(&items).Error() - if err != nil { - log.Fatalf("Failed to load items: %v", err) - } -}) -``` - -### Log - -```go -import "github.com/localhots/gobelt/log" -``` - -```go -ctx := context.Background() -ctx = log.ContextWithFields(ctx, log.F{"email": params["email"]}) - -user, err := signup(ctx, params) -if err != nil { - log.Errorf(ctx, "Signup failed: %v", err) - // [ERRO] Signup failed: db: duplicate entry email=bob@example.com - return -} - -log.Info(ctx, "New user signed up", log.F{"id": user.ID}) -// [INFO] New user signed up email=bob@example.com id=14 -``` - -### Set - -There is a collection of packages implementing a set data type located inside -the `set` package. Implemented types include: - -* `int`, `int8`, `int16`, `int32`, `int64` -* `uint`, `uint8`, `uint16`, `uint32`, `uint64` -* `string` - -All the package names are type names prefixed with "set", e.g. `setuint64`. - -```go -import "github.com/localhots/gobelt/set/setstring" -``` - -```go -s := setstring.New("one", "two") -s.Add("three") -s.Remove("one", "two").Add("four", "five") -fmt.Println("Size:", s.Len()) // 3 -fmt.Println("Has one", s.Has("one")) // false -fmt.Println(s.SortedSlice()) // [three four five] -``` - -### Config - -```go -import "github.com/localhots/gobelt/config" -``` - -Describe configuration structure inside a target package. - -```go -package db - -var conf struct { - Flavor string `toml:"flavor"` - DSN string `toml:"dsn"` -} - -func init() { - config.Require("db", &conf) -} -``` - -Load configuration from a `main` function: - -```go -package main - -func main() { - config.Load("config/config.toml") -} -``` \ No newline at end of file +* [Config](config): Configuration manager +* [CSV](csv2): Extensions to `encoding/csv` package +* [File cache](filecache): File cache implementation +* [Log](log): +* [Pointers](ptrto): Pointers to basic types +* [Reflect](reflect2): Extensions to `reflect` package +* [Sets](set): A collection of packages that implement set data structure for +basic types. +* [ORM](sqldb): ORM wannabe +* [Thread pool](threadpool): Implements a thread pool +* [Time](time2): Extensions to `time` package with time freezing features diff --git a/config/README.md b/config/README.md new file mode 100644 index 0000000..355e7b6 --- /dev/null +++ b/config/README.md @@ -0,0 +1,40 @@ +## Config + +Package config allows other packages to require a certain section of TOML +configuration file to be parsed into its internal configuration structure. Once +config file is processed its values are distributed by the packages that +required them. + +```go +import "github.com/localhots/gobelt/config" +``` + +Describe configuration structure inside a target package then call +`config.Require` from the init function of a package. + +> Note: subgroups are not currently supported. If a package is called `s3` and +> located in `aws` parent package, call config section `aws_s3` instead of +> `aws.s3`. + +```go +package db + +var conf struct { + Flavor string `toml:"flavor"` + DSN string `toml:"dsn"` +} + +func init() { + config.Require("db", &conf) +} +``` + +Load configuration from a `main` function of the app: + +```go +package main + +func main() { + config.Load("config/config.toml") +} +``` diff --git a/filecache/README.md b/filecache/README.md new file mode 100644 index 0000000..cf16fdf --- /dev/null +++ b/filecache/README.md @@ -0,0 +1,20 @@ +## File cache + +Package `file_cache` implements a helper function that would cache results of +an expensive operation to a file. It would use file contents when the file exist +and won't call the function again unless the file is deleted. + +```go +import "github.com/localhots/gobelt/filecache" +``` + +```go +ctx := context.Background() +var items []Item +filecache.Load(&items, "tmp/cache/items.json", func() { + err := conn.Query(ctx, "SELECT * FROM items").Load(&items).Error() + if err != nil { + log.Fatalf("Failed to load items: %v", err) + } +}) +``` diff --git a/log/README.md b/log/README.md new file mode 100644 index 0000000..3ccaa34 --- /dev/null +++ b/log/README.md @@ -0,0 +1,27 @@ +## Log + +Package `log` wraps [logrus](https://github.com/sirupsen/logrus) with a set of +convenient short functions. It can also add values to context for future +logging. + +```go +import "github.com/localhots/gobelt/log" +``` + +```go +ctx := context.Background() +ctx = log.ContextWithFields(ctx, log.F{"email": params["email"]}) + +user, err := signup(ctx, params) +if err != nil { + log.Errorf(ctx, "Signup failed: %v", err) + // [ERRO] Signup failed: db: duplicate entry email=bob@example.com + return +} + +log.Info(ctx, "New user signed up", log.F{ + "id": user.ID, + "name": user.Name, +}) +// [INFO] New user signed up email=bob@example.com id=14 name="Bob Fierce" +``` diff --git a/set/README.md b/set/README.md new file mode 100644 index 0000000..9682848 --- /dev/null +++ b/set/README.md @@ -0,0 +1,26 @@ +## Set + +Package `set` is a collection of packages implementing a set data type. +Supported types are: + +* `int`, `int8`, `int16`, `int32`, `int64` +* `uint`, `uint8`, `uint16`, `uint32`, `uint64` +* `string` + +All the package names are type names prefixed with "set", e.g. `setuint64`. + +> Note: These packages are generated from a template. Instead of modifying each +> package individually change the template and run `make gen`. + +```go +import "github.com/localhots/gobelt/set/setstring" +``` + +```go +s := setstring.New("one", "two") +s.Add("three") +s.Remove("one", "two").Add("four", "five") +fmt.Println("Size:", s.Len()) // 3 +fmt.Println("Has one", s.Has("one")) // false +fmt.Println(s.SortedSlice()) // [three four five] +``` \ No newline at end of file diff --git a/threadpool/README.md b/threadpool/README.md new file mode 100644 index 0000000..fa0a7f5 --- /dev/null +++ b/threadpool/README.md @@ -0,0 +1,22 @@ +## Thread pool + +Package `thread_pool` implements a pool of threads, duh. + +```go +import "github.com/localhots/gobelt/threadpool" +``` + +```go +ctx := context.Background() +ctx, cancel = context.WithTimeout(ctx, 30*time.Second) +defer cancel() + +pool := threadpool.New(10) +defer pool.Close() +for i := 0; i < 1000000; i++ { + i := i + pool.Enqueue(ctx, func() { + fmt.Printf("The number is %d\n", i) + }) +} +```