Add changelog

Fixed ExampleScrape README Sample

.builds/fedora.yml

@@ -0,0 +1,104 @@
+image: fedora/latest
+packages:
+  - tar
+environment:
+  GOROOT: /tmp/go
+  GOPATH: /home/build
+  GOBIN: /home/build/bin
+sources:
+  - https://github.com/PuerkitoBio/goquery
+tasks:
+  - setup: |
+      mkdir bin
+      mkdir -p src/github.com/PuerkitoBio
+      mv goquery src/github.com/PuerkitoBio/
+  - go1_7: |
+      cd /tmp
+      rm -rf go
+      curl -Lo golang.tar.gz https://golang.org/dl/go1.7.6.linux-amd64.tar.gz
+      tar xvf golang.tar.gz
+      cd /home/build/src/github.com/PuerkitoBio/goquery
+      /tmp/go/bin/go version
+      /tmp/go/bin/go get -t .
+      /tmp/go/bin/go test -v
+  - go1_8: |
+      cd /tmp
+      rm -rf go
+      curl -Lo golang.tar.gz https://golang.org/dl/go1.8.7.linux-amd64.tar.gz
+      tar xvf golang.tar.gz
+      cd /home/build/src/github.com/PuerkitoBio/goquery
+      /tmp/go/bin/go version
+      /tmp/go/bin/go get -t .
+      /tmp/go/bin/go test -v
+  - go1_9: |
+      cd /tmp
+      rm -rf go
+      curl -Lo golang.tar.gz https://golang.org/dl/go1.9.7.linux-amd64.tar.gz
+      tar xvf golang.tar.gz
+      cd /home/build/src/github.com/PuerkitoBio/goquery
+      /tmp/go/bin/go version
+      /tmp/go/bin/go get -t .
+      /tmp/go/bin/go test -v
+  - go1_10: |
+      cd /tmp
+      rm -rf go
+      curl -Lo golang.tar.gz https://golang.org/dl/go1.10.8.linux-amd64.tar.gz
+      tar xvf golang.tar.gz
+      cd /home/build/src/github.com/PuerkitoBio/goquery
+      /tmp/go/bin/go version
+      /tmp/go/bin/go get -t .
+      /tmp/go/bin/go test -v
+  - go1_11: |
+      cd /tmp
+      rm -rf go
+      curl -Lo golang.tar.gz https://golang.org/dl/go1.11.13.linux-amd64.tar.gz
+      tar xvf golang.tar.gz
+      cd /home/build/src/github.com/PuerkitoBio/goquery
+      /tmp/go/bin/go version
+      /tmp/go/bin/go get -t .
+      /tmp/go/bin/go test -v
+  - go1_12: |
+      cd /tmp
+      rm -rf go
+      curl -Lo golang.tar.gz https://golang.org/dl/go1.12.17.linux-amd64.tar.gz
+      tar xvf golang.tar.gz
+      cd /home/build/src/github.com/PuerkitoBio/goquery
+      /tmp/go/bin/go version
+      /tmp/go/bin/go get -t .
+      /tmp/go/bin/go test -v
+  - go1_13: |
+      cd /tmp
+      rm -rf go
+      curl -Lo golang.tar.gz https://golang.org/dl/go1.13.15.linux-amd64.tar.gz
+      tar xvf golang.tar.gz
+      cd /home/build/src/github.com/PuerkitoBio/goquery
+      /tmp/go/bin/go version
+      /tmp/go/bin/go get -t .
+      /tmp/go/bin/go test -v
+  - go1_14: |
+      cd /tmp
+      rm -rf go
+      curl -Lo golang.tar.gz https://golang.org/dl/go1.14.12.linux-amd64.tar.gz
+      tar xvf golang.tar.gz
+      cd /home/build/src/github.com/PuerkitoBio/goquery
+      /tmp/go/bin/go version
+      /tmp/go/bin/go get -t .
+      /tmp/go/bin/go test -v
+  - go1_15: |
+      cd /tmp
+      rm -rf go
+      curl -Lo golang.tar.gz https://golang.org/dl/go1.15.5.linux-amd64.tar.gz
+      tar xvf golang.tar.gz
+      cd /home/build/src/github.com/PuerkitoBio/goquery
+      /tmp/go/bin/go version
+      /tmp/go/bin/go get -t .
+      /tmp/go/bin/go test -v
+  - go1_16: |
+      cd /tmp
+      rm -rf go
+      curl -Lo golang.tar.gz https://golang.org/dl/go1.16beta1.linux-amd64.tar.gz
+      tar xvf golang.tar.gz
+      cd /home/build/src/github.com/PuerkitoBio/goquery
+      /tmp/go/bin/go version
+      /tmp/go/bin/go get -t .
+      /tmp/go/bin/go test -v

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: [mna]
+custom: ["https://www.buymeacoffee.com/mna"]

.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  # Maintain dependencies for Go
+  - package-ecosystem: "gomod"
+    directory: "/"
+    schedule:
+      interval: "daily"

.travis.yml

@@ -4,11 +4,6 @@ arch:
 language: go
 
 go:
-    - 1.2.x
-    - 1.3.x
-    - 1.4.x
-    - 1.5.x
-    - 1.6.x
     - 1.7.x
     - 1.8.x
     - 1.9.x
@@ -16,20 +11,12 @@ go:
     - 1.11.x
     - 1.12.x
     - 1.13.x
+    - 1.14.x
+    - 1.15.x
     - tip
 
 jobs:
  exclude:
-    - arch: ppc64le
-      go: 1.2.x
-    - arch: ppc64le
-      go: 1.3.x
-    - arch: ppc64le
-      go: 1.4.x
-    - arch: ppc64le
-      go: 1.5.x
-    - arch: ppc64le
-      go: 1.6.x
     - arch: ppc64le
       go: 1.7.x
     - arch: ppc64le

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2012-2016, Martin Angers & Contributors
+Copyright (c) 2012-2021, Martin Angers & Contributors
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

README.md

@@ -1,5 +1,9 @@
 # goquery - a little like that j-thing, only in Go
-[![build status](https://secure.travis-ci.org/PuerkitoBio/goquery.svg?branch=master)](http://travis-ci.org/PuerkitoBio/goquery) [![GoDoc](https://godoc.org/github.com/PuerkitoBio/goquery?status.png)](http://godoc.org/github.com/PuerkitoBio/goquery) [![Sourcegraph Badge](https://sourcegraph.com/github.com/PuerkitoBio/goquery/-/badge.svg)](https://sourcegraph.com/github.com/PuerkitoBio/goquery?badge)
+
+[![builds.sr.ht status](https://builds.sr.ht/~mna/goquery/commits/fedora.yml.svg)](https://builds.sr.ht/~mna/goquery/commits/fedora.yml?)
+[![build status](https://secure.travis-ci.org/PuerkitoBio/goquery.svg?branch=master)](http://travis-ci.org/PuerkitoBio/goquery)
+[![Go Reference](https://pkg.go.dev/badge/github.com/PuerkitoBio/goquery.svg)](https://pkg.go.dev/github.com/PuerkitoBio/goquery)
+[![Sourcegraph Badge](https://sourcegraph.com/github.com/PuerkitoBio/goquery/-/badge.svg)](https://sourcegraph.com/github.com/PuerkitoBio/goquery?badge)
 
 goquery brings a syntax and a set of features similar to [jQuery][] to the [Go language][go]. It is based on Go's [net/html package][html] and the CSS Selector library [cascadia][]. Since the net/html parser returns nodes, and not a full-featured DOM tree, jQuery's stateful manipulation functions (like height(), css(), detach()) have been left off.
 
@@ -19,7 +23,7 @@ Syntax-wise, it is as close as possible to jQuery, with the same function names
 
 ## Installation
 
-Please note that because of the net/html dependency, goquery requires Go1.1+.
+Please note that because of the net/html dependency, goquery requires Go1.1+ and is tested on Go1.7+.
 
     $ go get github.com/PuerkitoBio/goquery
 
@@ -37,6 +41,8 @@ Please note that because of the net/html dependency, goquery requires Go1.1+.
 
 **Note that goquery's API is now stable, and will not break.**
 
+*    **2021-07-11 (v1.7.1)** : Update go.mod dependencies and add dependabot config (thanks [@jauderho](https://github.com/jauderho)).
+*    **2021-06-14 (v1.7.0)** : Add `Single` and `SingleMatcher` functions to optimize first-match selection (thanks [@gdollardollar](https://github.com/gdollardollar)).
 *    **2021-01-11 (v1.6.1)** : Fix panic when calling `{Prepend,Append,Set}Html` on a `Selection` that contains non-Element nodes.
 *    **2020-10-08 (v1.6.0)** : Parse html in context of the container node for all functions that deal with html strings (`AfterHtml`, `AppendHtml`, etc.). Thanks to [@thiemok][thiemok] and [@davidjwilkins][djw] for their work on this.
 *    **2020-02-04 (v1.5.1)** : Update module dependencies.
@@ -50,7 +56,7 @@ Please note that because of the net/html dependency, goquery requires Go1.1+.
 *    **2016-08-28 (v1.0.1)** : Optimize performance for large documents.
 *    **2016-07-27 (v1.0.0)** : Tag version 1.0.0.
 *    **2016-06-15** : Invalid selector strings internally compile to a `Matcher` implementation that never matches any node (instead of a panic). So for example, `doc.Find("~")` returns an empty `*Selection` object.
-*    **2016-02-02** : Add `NodeName` utility function similar to the DOM's `nodeName` property. It returns the tag name of the first element in a selection, and other relevant values of non-element nodes (see godoc for details). Add `OuterHtml` utility function similar to the DOM's `outerHTML` property (named `OuterHtml` in small caps for consistency with the existing `Html` method on the `Selection`).
+*    **2016-02-02** : Add `NodeName` utility function similar to the DOM's `nodeName` property. It returns the tag name of the first element in a selection, and other relevant values of non-element nodes (see [doc][] for details). Add `OuterHtml` utility function similar to the DOM's `outerHTML` property (named `OuterHtml` in small caps for consistency with the existing `Html` method on the `Selection`).
 *    **2015-04-20** : Add `AttrOr` helper method to return the attribute's value or a default value if absent. Thanks to [piotrkowalczuk][piotr].
 *    **2015-02-04** : Add more manipulation functions - Prepend* - thanks again to [Andrew Stone][thatguystone].
 *    **2014-11-28** : Add more manipulation functions - ReplaceWith*, Wrap* and Unwrap - thanks again to [Andrew Stone][thatguystone].
@@ -79,7 +85,7 @@ jQuery often has many variants for the same function (no argument, a selector st
 
 Utility functions that are not in jQuery but are useful in Go are implemented as functions (that take a `*Selection` as parameter), to avoid a potential naming clash on the `*Selection`'s methods (reserved for jQuery-equivalent behaviour).
 
-The complete [godoc reference documentation can be found here][doc].
+The complete [package reference documentation can be found here][doc].
 
 Please note that Cascadia's selectors do not necessarily match all supported selectors of jQuery (Sizzle). See the [cascadia project][cascadia] for details. Invalid selector strings compile to a `Matcher` that fails to match any node. Behaviour of the various functions that take a selector string as argument follows from that fact, e.g. (where `~` is an invalid selector string):
 
@@ -123,12 +129,11 @@ func ExampleScrape() {
   }
 
   // Find the review items
-  doc.Find(".sidebar-reviews article .content-block").Each(func(i int, s *goquery.Selection) {
-    // For each item found, get the band and title
-    band := s.Find("a").Text()
-    title := s.Find("i").Text()
-    fmt.Printf("Review %d: %s - %s\n", i, band, title)
-  })
+  doc.Find(".left-content article .post-title").Each(func(i int, s *goquery.Selection) {
+		// For each item found, get the title
+		title := s.Find("a").Text()
+		fmt.Printf("Review %d: %s\n", i, title)
+	})
 }
 
 func main() {
@@ -161,8 +166,9 @@ There are a number of ways you can support the project:
 * Pull requests: please discuss new code in an issue first, unless the fix is really trivial.
   - Make sure new code is tested.
   - Be mindful of existing code - PRs that break existing code have a high probability of being declined, unless it fixes a serious issue.
-
-If you desperately want to send money my way, I have a BuyMeACoffee.com page:
+* Sponsor the developer
+  - See the Github Sponsor button at the top of the repo on github
+  - or via BuyMeACoffee.com, below
 
 <a href="https://www.buymeacoffee.com/mna" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: 41px !important;width: 174px !important;box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;" ></a>
 
@@ -177,10 +183,10 @@ The [BSD 3-Clause license][bsd], the same as the [Go language][golic]. Cascadia'
 [bsd]: http://opensource.org/licenses/BSD-3-Clause
 [golic]: http://golang.org/LICENSE
 [caslic]: https://github.com/andybalholm/cascadia/blob/master/LICENSE
-[doc]: http://godoc.org/github.com/PuerkitoBio/goquery
+[doc]: https://pkg.go.dev/github.com/PuerkitoBio/goquery
 [index]: http://api.jquery.com/index/
 [gonet]: https://github.com/golang/net/
-[html]: http://godoc.org/golang.org/x/net/html
+[html]: https://pkg.go.dev/golang.org/x/net/html
 [wiki]: https://github.com/PuerkitoBio/goquery/wiki/Tips-and-tricks
 [thatguystone]: https://github.com/thatguystone
 [piotr]: https://github.com/piotrkowalczuk

bench_traversal_test.go

@@ -2,6 +2,8 @@ package goquery
 
 import (
 	"testing"
+
+	"github.com/andybalholm/cascadia"
 )
 
 func BenchmarkFind(b *testing.B) {
@@ -800,3 +802,21 @@ func BenchmarkClosestNodes(b *testing.B) {
 		b.Fatalf("want 2, got %d", n)
 	}
 }
+
+func BenchmarkSingleMatcher(b *testing.B) {
+	doc := Doc()
+	multi := cascadia.MustCompile(`div`)
+	single := SingleMatcher(multi)
+	b.ResetTimer()
+
+	b.Run("multi", func(b *testing.B) {
+		for i := 0; i < b.N; i++ {
+			_ = doc.FindMatcher(multi)
+		}
+	})
+	b.Run("single", func(b *testing.B) {
+		for i := 0; i < b.N; i++ {
+			_ = doc.FindMatcher(single)
+		}
+	})
+}

example_test.go

@@ -80,3 +80,31 @@ func ExampleNewDocumentFromReader_string() {
 
 	// Output: Header
 }
+
+func ExampleSingle() {
+	html := `
+<html>
+  <body>
+    <div>1</div>
+    <div>2</div>
+    <div>3</div>
+  </body>
+</html>
+`
+	doc, err := goquery.NewDocumentFromReader(strings.NewReader(html))
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// By default, the selector string selects all matching nodes
+	multiSel := doc.Find("div")
+	fmt.Println(multiSel.Text())
+
+	// Using goquery.Single, only the first match is selected
+	singleSel := doc.FindMatcher(goquery.Single("div"))
+	fmt.Println(singleSel.Text())
+
+	// Output:
+	// 123
+	// 1
+}

go.mod

@@ -1,8 +1,8 @@
 module github.com/PuerkitoBio/goquery
 
 require (
-	github.com/andybalholm/cascadia v1.1.0
-	golang.org/x/net v0.0.0-20200202094626-16171245cfb2
+	github.com/andybalholm/cascadia v1.2.0
+	golang.org/x/net v0.0.0-20210614182718-04defd469f4e
 )
 
 go 1.13

go.sum

@@ -1,8 +1,10 @@
-github.com/andybalholm/cascadia v1.1.0 h1:BuuO6sSfQNFRu1LppgbD25Hr2vLYW25JvxHs5zzsLTo=
-github.com/andybalholm/cascadia v1.1.0/go.mod h1:GsXiBklL0woXo1j/WYWtSYYC4ouU9PqHO0sqidkEA4Y=
-golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+github.com/andybalholm/cascadia v1.2.0 h1:vuRCkM5Ozh/BfmsaTm26kbjm0mIOM3yS5Ek/F5h18aE=
+github.com/andybalholm/cascadia v1.2.0/go.mod h1:YCyR8vOZT9aZ1CHEd8ap0gMVm2aFgxBp0T0eFw1RUQY=
 golang.org/x/net v0.0.0-20180218175443-cbe0f9307d01/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
-golang.org/x/net v0.0.0-20200202094626-16171245cfb2 h1:CCH4IOTTfewWjGOlSp+zGcjutRKlBEZQ6wTn8ozI/nI=
-golang.org/x/net v0.0.0-20200202094626-16171245cfb2/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
-golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
-golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/net v0.0.0-20210614182718-04defd469f4e h1:XpT3nA5TvE525Ne3hInMh6+GETgn27Zfm9dxsThnX2Q=
+golang.org/x/net v0.0.0-20210614182718-04defd469f4e/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=

type.go

@@ -7,7 +7,6 @@ import (
 	"net/url"
 
 	"github.com/andybalholm/cascadia"
-
 	"golang.org/x/net/html"
 )
 
@@ -122,6 +121,45 @@ type Matcher interface {
 	Filter([]*html.Node) []*html.Node
 }
 
+// Single compiles a selector string to a Matcher that stops after the first
+// match is found.
+//
+// By default, Selection.Find and other functions that accept a selector string
+// to select nodes will use all matches corresponding to that selector. By
+// using the Matcher returned by Single, at most the first match will be
+// selected.
+//
+// For example, those two statements are semantically equivalent:
+//
+//     sel1 := doc.Find("a").First()
+//     sel2 := doc.FindMatcher(goquery.Single("a"))
+//
+// The one using Single is optimized to be potentially much faster on large
+// documents.
+//
+// Only the behaviour of the MatchAll method of the Matcher interface is
+// altered compared to standard Matchers. This means that the single-selection
+// property of the Matcher only applies for Selection methods where the Matcher
+// is used to select nodes, not to filter or check if a node matches the
+// Matcher - in those cases, the behaviour of the Matcher is unchanged (e.g.
+// FilterMatcher(Single("div")) will still result in a Selection with multiple
+// "div"s if there were many "div"s in the Selection to begin with).
+func Single(selector string) Matcher {
+	return singleMatcher{compileMatcher(selector)}
+}
+
+// SingleMatcher returns a Matcher matches the same nodes as m, but that stops
+// after the first match is found.
+//
+// See the documentation of function Single for more details.
+func SingleMatcher(m Matcher) Matcher {
+	if _, ok := m.(singleMatcher); ok {
+		// m is already a singleMatcher
+		return m
+	}
+	return singleMatcher{m}
+}
+
 // compileMatcher compiles the selector string s and returns
 // the corresponding Matcher. If s is an invalid selector string,
 // it returns a Matcher that fails all matches.
@@ -133,6 +171,30 @@ func compileMatcher(s string) Matcher {
 	return cs
 }
 
+type singleMatcher struct {
+	Matcher
+}
+
+func (m singleMatcher) MatchAll(n *html.Node) []*html.Node {
+	// Optimized version - stops finding at the first match (cascadia-compiled
+	// matchers all use this code path).
+	if mm, ok := m.Matcher.(interface{ MatchFirst(*html.Node) *html.Node }); ok {
+		node := mm.MatchFirst(n)
+		if node == nil {
+			return nil
+		}
+		return []*html.Node{node}
+	}
+
+	// Fallback version, for e.g. test mocks that don't provide the MatchFirst
+	// method.
+	nodes := m.Matcher.MatchAll(n)
+	if len(nodes) > 0 {
+		return nodes[:1:1]
+	}
+	return nil
+}
+
 // invalidMatcher is a Matcher that always fails to match.
 type invalidMatcher struct{}
 

type_test.go

@@ -7,6 +7,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/andybalholm/cascadia"
 	"golang.org/x/net/html"
 )
 
@@ -208,3 +209,47 @@ func TestIssue103(t *testing.T) {
 	}
 	t.Log(text)
 }
+
+func TestSingle(t *testing.T) {
+	data := `
+<html>
+  <body>
+    <div class="b">1</div>
+    <div class="a">2</div>
+    <div class="a">3</div>
+    <p class="b">4</p>
+  </body>
+</html>
+`
+	doc, err := NewDocumentFromReader(strings.NewReader(data))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	text := doc.FindMatcher(Single("div")).Text()
+	if text != "1" {
+		t.Fatalf("want %q, got %q", "1", text)
+	}
+
+	// Verify semantic equivalence
+	sel1 := doc.Find("div").First()
+	sel2 := doc.FindMatcher(Single("div"))
+	if sel1.Text() != sel2.Text() {
+		t.Fatalf("want sel1 to equal sel2")
+	}
+
+	// Here, the Single has no effect as the selector is used to filter
+	// from the existing selection, not to find nodes in the document.
+	divs := doc.Find("div")
+	text = divs.FilterMatcher(Single(".a")).Text()
+	if text != "23" {
+		t.Fatalf("want %q, got %q", "23", text)
+	}
+
+	classA := cascadia.MustCompile(".a")
+	classB := cascadia.MustCompile(".b")
+	text = doc.FindMatcher(classB).AddMatcher(SingleMatcher(classA)).Text()
+	if text != "142" {
+		t.Fatalf("want %q, got %q", "142", text)
+	}
+}