Draft of the new README

README.md

@@ -1,29 +1,25 @@
 # fakedata
 
-`fakedata` is a small command line utility that generates random data.
-
-Please **note** you're reading the documentation of an unreleased version of
-`fakedata` which differs quite a lot from the latest stable release. We're about
-to release version [1.0.0](https://github.com/lucapette/fakedata/issues/44) that
-has some breaking changes. If you're running `fakedata v0.6.0` (you can find out
-with `fakedata --version`, then please refer to its
-[docs](https://github.com/lucapette/fakedata/tree/v0.6.0).
+`fakedata` is a small program that generates random data on the command line.
 
 # Table Of Contents
 
 - [Overview](#overview)
+  - [Quick Start](#quick-start)
+  - [Why another random data generator?](#why-another-random-data-generator)
 - [Generators](#generators)
-- [Formatters](#formatters)
+  -[Constraints](#constraints)
 - [Templates](#templates)
 - [How to install](#how-to-install)
 - [How to contribute](#how-to-contribute)
 - [Code of conduct](#code-of-conduct)
 
 # Overview
 
-Here is a list of examples to get a feeling of how `fakedata` works.
+## Quick Start
 
-You can specify the name of generators you want to use:
+`fakedata` helps you generate random data in various ways. You generate data by
+specifying on the command line the kind of data you need:
 
 ```sh
 $ fakedata email country
@@ -38,19 +34,8 @@ [email protected] Haiti
 [email protected] Malaysia
 [email protected] Virgin Islands, British
 ```
-
-Limit the number of rows:
-
-```sh
-$ fakedata --limit 5 country.code
-SH
-CF
-GQ
-PE
-FO
-```
-
-Choose a different output format:
+Be default, `fakedata` generates data using a space as a separator. You can
+choose a different output formats like CSV:
 
 ```sh
 $ fakedata --format=csv product.category product.name
@@ -66,13 +51,52 @@ Shoes,Freetop
 Tools,Domnix
 ```
 
+or SQL insert statements:
+
+`fakedata` can generate insert statements. By default, it uses the name of the
+generators as column names:
+
+```sh
+$ # 
+$ fakedata --format=sql --limit 1 email domain
+INSERT INTO TABLE (email,domain) values ('[email protected]','example.me');
+```
+
+You can specify the name of the column using a field with the following format
+`column_name=generator`:
+
+```sh
+$ fakedata --format=sql --limit 1 login=email referral=domain
+INSERT INTO TABLE (login,referral) values ('[email protected]','test.me');
+```
+
+If you need some control over the output, you can use templates:
+
+```sh
+$ echo '{{Email}}--{{Int}}--{{Color}}' | fakedata -l5
+[email protected]
+[email protected]
+[email protected]
+[email protected]
+[email protected]
+```
+
+## Why another random data generator?
+
+`fakedata` focuses on a simple UI (if you think it could be simpler, please [let
+us know!](https://github.com/lucapette/fakedata/issues/new) We :heart:
+feedback!) and the ability to fully control both the output format (using
+[templates](#templates)) and the set of values a generator will pick from. We
+call this feature "generators' constraints" and it's explained in detail
+[here](#constraints).
+
 # Generators
 
 `fakedata` provides a number of generators. You can see the full list running
 the following command:
 
 ```sh
-$ fakedata --generators
+$ fakedata --generators # or -G
 color             one word color
 country           Full country name
 country.code      2-digit country code
@@ -83,8 +107,15 @@ domain.tld        example|test
 # It's a long list :)
 ```
 
+## Constraints
+
 Some generators allow you to pass in a range to constraint the output to a
-subset of values:
+subset of values. To find out which generators support constraints:
+
+```sh
+$ fakedata --constraints
+
+```
 
 ```sh
 $ fakedata int:1,100 # will generate only integers between 1 and 100
@@ -93,7 +124,7 @@ $ fakedata int:50 # also works
 ```
 
 The `enum` generator allows you to specify a set of values. It comes handy when
-you need random data from a small subset of values:
+you need random data from a small set of values:
 
 ```sh
 $ fakedata --limit 5 enum
@@ -133,31 +164,6 @@ one
 two
 ```
 
-# Formatters
-
-### SQL formatter
-
-`fakedata` can generate insert statements. By default, it uses the name of the
-generators as column names:
-
-```sh
-$ fakedata --format=sql --limit 1 email domain
-INSERT INTO TABLE (email,domain) values ('[email protected]','example.me');
-```
-
-You can specify the name of the column using a field with the following format
-`column_name=generator`:
-
-```sh
-$ fakedata --format=sql --limit 1 login=email referral=domain
-INSERT INTO TABLE (login,referral) values ('[email protected]','test.me');
-```
-
-```sh
-fakedata --format=sql --limit=1 --table=users login=email referral=domain
-INSERT INTO users (login,referral) VALUES ('[email protected]' 'test.us');
-```
-
 # Templates
 
 `fakedata` supports parsing and executing template files for generating

integration/cli_test.go

@@ -89,12 +89,6 @@ func TestCLI(t *testing.T) {
 			"help.golden",
 			false,
 		},
-		{
-			"list generators",
-			[]string{"-g"},
-			"generators.golden",
-			false,
-		},
 		{
 			"default format",
 			[]string{"int:42,42", "enum:foo,foo"},

integration/golden/file-does-not-exist.golden

@@ -2,9 +2,10 @@ could not read file this file does not exist.txt: open this file does not exist.
 
 Usage: fakedata [option ...] field...
 
-  -f, --format string     generators rows in f format. Available formats: csv|tab|sql
-  -g, --generators        lists available generators
-  -l, --limit int         limits rows up to n (default 10)
-  -t, --table string      table name of the sql format (default "TABLE")
-  -T, --template string   Use template as input
-  -v, --version           shows version information
+  -f, --format string                 generators rows in f format. Available formats: csv|tab|sql
+  -g, --generators                    lists available generators
+  -c, --generators-with-constraints   lists available generators with constraints
+  -l, --limit int                     limits rows up to n (default 10)
+  -t, --table string                  table name of the sql format (default "TABLE")
+  -T, --template string               Use template as input
+  -v, --version                       shows version information

integration/golden/help.golden

@@ -1,8 +1,9 @@
 Usage: fakedata [option ...] field...
 
-  -f, --format string     generators rows in f format. Available formats: csv|tab|sql
-  -g, --generators        lists available generators
-  -l, --limit int         limits rows up to n (default 10)
-  -t, --table string      table name of the sql format (default "TABLE")
-  -T, --template string   Use template as input
-  -v, --version           shows version information
+  -f, --format string                 generators rows in f format. Available formats: csv|tab|sql
+  -g, --generators                    lists available generators
+  -c, --generators-with-constraints   lists available generators with constraints
+  -l, --limit int                     limits rows up to n (default 10)
+  -t, --table string                  table name of the sql format (default "TABLE")
+  -T, --template string               Use template as input
+  -v, --version                       shows version information

integration/golden/path-empty.golden

@@ -2,9 +2,10 @@ no file path given
 
 Usage: fakedata [option ...] field...
 
-  -f, --format string     generators rows in f format. Available formats: csv|tab|sql
-  -g, --generators        lists available generators
-  -l, --limit int         limits rows up to n (default 10)
-  -t, --table string      table name of the sql format (default "TABLE")
-  -T, --template string   Use template as input
-  -v, --version           shows version information
+  -f, --format string                 generators rows in f format. Available formats: csv|tab|sql
+  -g, --generators                    lists available generators
+  -c, --generators-with-constraints   lists available generators with constraints
+  -l, --limit int                     limits rows up to n (default 10)
+  -t, --table string                  table name of the sql format (default "TABLE")
+  -T, --template string               Use template as input
+  -v, --version                       shows version information

integration/golden/unknown-format.golden

@@ -2,9 +2,10 @@ unknown format: sqll
 
 Usage: fakedata [option ...] field...
 
-  -f, --format string     generators rows in f format. Available formats: csv|tab|sql
-  -g, --generators        lists available generators
-  -l, --limit int         limits rows up to n (default 10)
-  -t, --table string      table name of the sql format (default "TABLE")
-  -T, --template string   Use template as input
-  -v, --version           shows version information
+  -f, --format string                 generators rows in f format. Available formats: csv|tab|sql
+  -g, --generators                    lists available generators
+  -c, --generators-with-constraints   lists available generators with constraints
+  -l, --limit int                     limits rows up to n (default 10)
+  -t, --table string                  table name of the sql format (default "TABLE")
+  -T, --template string               Use template as input
+  -v, --version                       shows version information

integration/golden/unknown-generators.golden

@@ -2,9 +2,10 @@ unknown generator: madeupgenerator
 
 Usage: fakedata [option ...] field...
 
-  -f, --format string     generators rows in f format. Available formats: csv|tab|sql
-  -g, --generators        lists available generators
-  -l, --limit int         limits rows up to n (default 10)
-  -t, --table string      table name of the sql format (default "TABLE")
-  -T, --template string   Use template as input
-  -v, --version           shows version information
+  -f, --format string                 generators rows in f format. Available formats: csv|tab|sql
+  -g, --generators                    lists available generators
+  -c, --generators-with-constraints   lists available generators with constraints
+  -l, --limit int                     limits rows up to n (default 10)
+  -t, --table string                  table name of the sql format (default "TABLE")
+  -T, --template string               Use template as input
+  -v, --version                       shows version information

main.go

@@ -30,17 +30,15 @@ func getFormatter(format, table string) (f fakedata.Formatter, err error) {
 	return f, err
 }
 
-func generatorsHelp() string {
-	generators := fakedata.Generators()
-	buffer := &bytes.Buffer{}
+func generatorsHelp(generators fakedata.Generators) string {
 	max := 0
-
 	for _, gen := range generators {
 		if len(gen.Name) > max {
 			max = len(gen.Name)
 		}
 	}
 
+	buffer := &bytes.Buffer{}
 	pattern := fmt.Sprintf("%%-%ds%%s\n", max+2) //+2 makes the output more readable
 	for _, gen := range generators {
 		fmt.Fprintf(buffer, pattern, gen.Name, gen.Desc)
@@ -52,7 +50,7 @@ func generatorsHelp() string {
 func isPipe() bool {
 	stat, err := os.Stdin.Stat()
 	if err != nil {
-		fmt.Printf("Error checking shell pipe: %s", err)
+		fmt.Printf("error checking shell pipe: %v", err)
 	}
 	// Check if template data is piped to fakedata
 	return (stat.Mode() & os.ModeCharDevice) == 0
@@ -84,15 +82,16 @@ func findTemplate(path string) string {
 
 func main() {
 	var (
-		generatorsFlag = flag.BoolP("generators", "g", false, "lists available generators")
-		limitFlag      = flag.IntP("limit", "l", 10, "limits rows up to n")
-		formatFlag     = flag.StringP("format", "f", "", "generators rows in f format. Available formats: csv|tab|sql")
-		versionFlag    = flag.BoolP("version", "v", false, "shows version information")
-		tableFlag      = flag.StringP("table", "t", "TABLE", "table name of the sql format")
-		templateFlag   = flag.StringP("template", "T", "", "Use template as input")
+		generatorsFlag  = flag.BoolP("generators", "g", false, "lists available generators")
+		constraintsFlag = flag.BoolP("generators-with-constraints", "c", false, "lists available generators with constraints")
+		limitFlag       = flag.IntP("limit", "l", 10, "limits rows up to n")
+		formatFlag      = flag.StringP("format", "f", "", "generators rows in f format. Available formats: csv|tab|sql")
+		versionFlag     = flag.BoolP("version", "v", false, "shows version information")
+		tableFlag       = flag.StringP("table", "t", "TABLE", "table name of the sql format")
+		templateFlag    = flag.StringP("template", "T", "", "Use template as input")
 	)
 	flag.Usage = func() {
-		fmt.Fprintf(os.Stderr, "Usage: fakedata [option ...] field...\n\n")
+		fmt.Fprintf(os.Stdout, "Usage: fakedata [option ...] field...\n\n")
 		flag.PrintDefaults()
 	}
 	flag.Parse()
@@ -102,8 +101,15 @@ func main() {
 		os.Exit(0)
 	}
 
+	generators := fakedata.NewGenerators()
+
 	if *generatorsFlag {
-		fmt.Print(generatorsHelp())
+		fmt.Print(generatorsHelp(generators))
+		os.Exit(0)
+	}
+
+	if *constraintsFlag {
+		fmt.Print(generatorsHelp(generators.WithConstraints()))
 		os.Exit(0)
 	}