Updating examples README.md

.gitignore

@@ -0,0 +1,16 @@
+/click/click
+/cookie/cookie
+/eval/eval
+/keys/keys
+/logic/logic
+/pool/pool
+/screenshot/screenshot
+/simple/simple
+/standalone/standalone
+/submit/submit
+/text/text
+/upload/upload
+/visible/visible
+
+*.png
+*.exe

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016-2017 Kenneth Shaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,57 @@
+# About chromedp examples
+
+This folder contains a variety of code examples for working with
+[`chromedp`][1]. Please note that when the `chromedp` package is being
+rewritten, these examples may break. Additionally, since these examples are
+written for specific websites, there is a good chance that the current
+selectors, etc break after the website they are written against changes.
+
+While every effort is made to ensure that these examples are kept up-to-date,
+it is expected that the examples made available here
+and working, As this is not a core part of the `chromedp` project,
+
+## Building and Running an Example
+
+You can build and run these examples in the usual Go way:
+
+```sh
+# retrieve examples
+$ go get -u -d github.com/chromedp/examples
+
+# run example <prog>
+$ go run $GOPATH/src/github.com/chromedp/examples/<prog>/main.go
+
+# build example <prog>
+$ go build -o <prog> github.com/chromedp/examples/<prog> && ./<prog>
+```
+### Available Examples
+
+The following examples are currently available:
+
+<!-- the following section is updated by running `go run gen.go` -->
+<!-- START EXAMPLES -->
+| Example                   | Description                                                                               |
+|---------------------------|-------------------------------------------------------------------------------------------|
+| [click](/click)           | use a selector to click on an element.                                                    |
+| [cookie](/cookie)         | set a HTTP cookie on requests.                                                            |
+| [eval](/eval)             | evaluate javascript and retrieve the result.                                              |
+| [keys](/keys)             | send key events to an element.                                                            |
+| [logic](/logic)           | more complex logic beyond simple actions.                                                 |
+| [pool](/pool)             | use chromedp pool.                                                                        |
+| [screenshot](/screenshot) | take a screenshot of a specific element.                                                  |
+| [simple](/simple)         | do a simple google search.                                                                |
+| [standalone](/standalone) | use chromedp with a standalone (ie, a "pre-existing" / manually started) chrome instance. |
+| [submit](/submit)         | fill out and submit a form.                                                               |
+| [text](/text)             | extract text from a specific element.                                                     |
+| [upload](/upload)         | upload a file on a form.                                                                  |
+| [visible](/visible)       | wait until an element is visible.                                                         |
+<!-- END EXAMPLES -->
+
+## Contributing
+
+Pull Requests and contributions to this project are encouraged and greatly
+welcomed!  The `chromedp` project always needs new examples, and needs talented
+developers (such as yourself!) to submit fixes for the existing examples when
+they break (for example, when a website's layout/HTML changes).
+
+[1]: https://github.com/chromedp/chromedp

click/main.go

@@ -1,3 +1,5 @@
+// Command click is a chromedp example demonstrating how to use a selector to
+// click on an element.
 package main
 
 import (

cookie/main.go

@@ -1,3 +1,5 @@
+// Command cookie is a chromedp example demonstrating how to set a HTTP cookie
+// on requests.
 package main
 
 import (

eval/main.go

@@ -1,3 +1,5 @@
+// Command eval is a chromedp example demonstrating how to evaluate javascript
+// and retrieve the result.
 package main
 
 import (

gen.go

@@ -0,0 +1,109 @@
+// +build ignore
+
+package main
+
+import (
+	"bytes"
+	"flag"
+	"fmt"
+	"go/parser"
+	"go/token"
+	"io/ioutil"
+	"log"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+const (
+	sectionStart = "<!-- START EXAMPLES -->"
+	sectionEnd   = "<!-- END EXAMPLES -->"
+
+	descStart  = "demonstrating"
+	descPrefix = "how to"
+)
+
+var (
+	flagReadme = flag.String("readme", "README.md", "file to update")
+	flagMask   = flag.String("mask", "*/main.go", "")
+
+	spaceRE = regexp.MustCompile(`\s+`)
+)
+
+func main() {
+	flag.Parse()
+
+	buf, err := ioutil.ReadFile(*flagReadme)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	start, end := bytes.Index(buf, []byte(sectionStart)), bytes.Index(buf, []byte(sectionEnd))
+	if start == -1 || end == -1 {
+		log.Fatalf("could not find %s or %s in %s", sectionStart, sectionEnd, *flagReadme)
+	}
+
+	files, err := filepath.Glob(*flagMask)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	type ex struct {
+		name, desc string
+	}
+	var examples []ex
+	for _, fn := range files {
+		f, err := parser.ParseFile(token.NewFileSet(), fn, nil, parser.ParseComments)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		n := filepath.Base(filepath.Dir(fn))
+		name := fmt.Sprintf("[%s](/%s)", n, n)
+
+		// clean comment
+		comment := strings.Replace(f.Doc.Text(), "\n", " ", -1)
+		i := strings.Index(comment, descStart)
+		if i == -1 {
+			log.Fatalf("could not find %q in doc comment for %s", descStart, fn)
+		}
+		comment = strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(comment[i+len(descStart):]), descPrefix))
+
+		examples = append(examples, ex{name, comment})
+	}
+	sort.Slice(examples, func(i, j int) bool { return strings.Compare(examples[i].name, examples[j].name) < 0 })
+
+	// determine max length
+	var namelen, desclen int
+	for _, e := range examples {
+		namelen, desclen = max(namelen, len(e.name)), max(desclen, len(e.desc))
+	}
+
+	// generate
+	out := new(bytes.Buffer)
+	out.Write(buf[:start+len(sectionStart)])
+	out.WriteString(fmt.Sprintf("\n| %s | %s |\n", pad("Example", " ", namelen), pad("Description", " ", desclen)))
+	out.WriteString(fmt.Sprintf("|%s|%s|\n", pad("", "-", namelen+2), pad("", "-", desclen+2)))
+	for _, e := range examples {
+		out.WriteString(fmt.Sprintf("| %s | %s |\n", pad(e.name, " ", namelen), pad(e.desc, " ", desclen)))
+	}
+	out.Write(buf[end:])
+
+	// write
+	err = ioutil.WriteFile(*flagReadme, out.Bytes(), 0644)
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+
+func max(a, b int) int {
+	if a >= b {
+		return a
+	}
+	return b
+}
+
+func pad(s, v string, n int) string {
+	return s + strings.Repeat(v, n-len(s))
+}

keys/main.go

@@ -1,3 +1,5 @@
+// Command keys is a chromedp example demonstrating how to send key events to
+// an element.
 package main
 
 import (

logic/main.go

@@ -1,4 +1,5 @@
-// examples/logic/main.go
+// Command logic is a chromedp example demonstrating more complex logic beyond
+// simple actions.
 package main
 
 import (

pool/main.go

@@ -1,3 +1,4 @@
+// Command pool is a chromedp example demonstrating how to use chromedp pool.
 package main
 
 import (

screenshot/main.go

@@ -1,3 +1,5 @@
+// Command screenshot is a chromedp example demonstrating how to take a
+// screenshot of a specific element.
 package main
 
 import (

simple/main.go

@@ -1,4 +1,5 @@
-// examples/simple/main.go
+// Command simple is a chromedp example demonstrating how to do a simple google
+// search.
 package main
 
 import (

standalone/README.md

@@ -0,0 +1,47 @@
+# About example standalone
+
+This is a version of the [`simple`][1] example but uses the `chromedp.WithTargets`
+option with `chromedp/client.WatchPageTargets` to connect to an existing Chrome
+instance (ie, no process will be launched).
+
+## Manually Starting Chrome
+
+To use this example, please manually start a Chrome instance with the `--remote-debugging-port=9222`
+command-line option make the Chrome Debugging Protocol available to clients:
+
+```sh
+# start google-chrome
+$ google-chrome --remote-debugging-port=9222
+
+# start headless_shell
+$ headless_shell --headless --remote-debugging-port=9222
+
+# start google-chrome-unstable in headless mode
+$ google-chrome-unstable --headless --remote-debugging-port=9222
+```
+
+### Docker Image
+
+A Docker image, [knqz/chrome-headless][2], provides a small ready-to-use
+`headless_shell` that can be used with this example:
+
+```sh
+# retrieve docker image
+$ docker pull knqz/chrome-headless
+
+# start chrome-headless
+$ docker run -d -p 9222:9222 --rm --name chrome-headless knqz/chrome-headless
+```
+
+[1]: ../simple
+[2]: https://hub.docker.com/r/knqz/chrome-headless/
+
+## Building and Running
+
+The `standalone` example can be run like any other Go code:
+
+```sh
+# run example
+$ cd $GOPATH/src/github.com/chromedp/examples/standalone
+$ go build && ./standalone
+```

headless/main.go → standalone/main.go

@@ -1,3 +1,5 @@
+// Command standalone is a chromedp example demonstrating how to use chromedp
+// with a standalone (ie, a "pre-existing" / manually started) chrome instance.
 package main
 
 import (

submit/main.go

@@ -1,3 +1,5 @@
+// Command submit is a chromedp example demonstrating how to fill out and
+// submit a form.
 package main
 
 import (

text/main.go

@@ -1,3 +1,5 @@
+// Command text is a chromedp example demonstrating how to extract text from a
+// specific element.
 package main
 
 import (

upload/main.go

@@ -1,3 +1,5 @@
+// Command upload is a chromedp example demonstrating how to upload a file on a
+// form.
 package main
 
 import (

visible/main.go

@@ -1,3 +1,5 @@
+// Command visible is a chromedp example demonstrating how to wait until an
+// element is visible.
 package main
 
 import (