Update changelog for 1.7.0

Merge branch 'wip-i255-single-match'
Finalize documentation
2024-04-21 12:31:36 +00:00 · 2021-06-14 09:16:48 -04:00 · 2021-06-14 09:09:43 -04:00 · 2021-06-14 09:06:47 -04:00 · 2021-06-13 15:02:43 -04:00 · 2021-06-13 14:34:32 -04:00
11 changed files with 379 additions and 42 deletions
@@ -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
@@ -0,0 +1,2 @@
+github: [mna]
+custom: ["https://www.buymeacoffee.com/mna"]
@@ -1,11 +1,9 @@
+arch:
+    - amd64
+    - ppc64le
 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
@@ -13,5 +11,21 @@ go:
    - 1.11.x
    - 1.12.x
    - 1.13.x
+    - 1.14.x
+    - 1.15.x
    - tip

+jobs:
+ exclude:
+    - arch: ppc64le
+      go: 1.7.x
+    - arch: ppc64le
+      go: 1.8.x
+    - arch: ppc64le
+      go: 1.9.x
+    - arch: ppc64le
+      go: 1.10.x
+    - arch: ppc64le
+      go: 1.11.x
+    - arch: ppc64le
+      go: 1.12.x
@@ -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:
@@ -1,5 +1,5 @@
 # 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 +19,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 +37,9 @@ 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-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.
 *    **2018-11-15 (v1.5.0)** : Go module support (thanks @Zaba505).
 *    **2018-06-07 (v1.4.1)** : Add `NewDocumentFromReader` examples.
@@ -48,7 +51,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].
@@ -77,7 +80,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):

@@ -121,12 +124,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() {
@@ -143,9 +145,10 @@ func main() {
 - [gnulnx/goperf](https://github.com/gnulnx/goperf), a website performance test tool that also fetches static assets.
 - [MontFerret/ferret](https://github.com/MontFerret/ferret), declarative web scraping.
 - [tacusci/berrycms](https://github.com/tacusci/berrycms), a modern simple to use CMS with easy to write plugins
- [Dataflow kit](https://github.com/slotix/dataflowkit), Web Scraping framework for Gophers.  
+- [Dataflow kit](https://github.com/slotix/dataflowkit), Web Scraping framework for Gophers.
 - [Geziyor](https://github.com/geziyor/geziyor), a fast web crawling & scraping framework for Go. Supports JS rendering.
 - [Pagser](https://github.com/foolin/pagser), a simple, easy, extensible, configurable HTML parser to struct based on goquery and struct tags.
+- [stitcherd](https://github.com/vhodges/stitcherd), A server for doing server side includes using css selectors and DOM updates.

 ## Support

@@ -158,8 +161,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>

@@ -174,11 +178,13 @@ 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
 [goq]: https://github.com/andrewstuart/goq
+[thiemok]: https://github.com/thiemok
+[djw]: https://github.com/davidjwilkins
@@ -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)
+		}
+	})
+}
@@ -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
+}
@@ -41,9 +41,10 @@ func (s *Selection) AfterSelection(sel *Selection) *Selection {
 // This follows the same rules as Selection.Append.
 func (s *Selection) AfterHtml(htmlStr string) *Selection {
 	return s.eachNodeHtml(htmlStr, true, func(node *html.Node, nodes []*html.Node) {
+		nextSibling := node.NextSibling
 		for _, n := range nodes {
 			if node.Parent != nil {
-				node.Parent.InsertBefore(n, node.NextSibling)
+				node.Parent.InsertBefore(n, nextSibling)
 			}
 		}
 	})
@@ -202,8 +203,9 @@ func (s *Selection) PrependSelection(sel *Selection) *Selection {
 // PrependHtml parses the html and prepends it to the set of matched elements.
 func (s *Selection) PrependHtml(htmlStr string) *Selection {
 	return s.eachNodeHtml(htmlStr, false, func(node *html.Node, nodes []*html.Node) {
+		firstChild := node.FirstChild
 		for _, n := range nodes {
-			node.InsertBefore(n, node.FirstChild)
+			node.InsertBefore(n, firstChild)
 		}
 	})
 }
@@ -283,9 +285,10 @@ func (s *Selection) ReplaceWithSelection(sel *Selection) *Selection {
 // This follows the same rules as Selection.Append.
 func (s *Selection) ReplaceWithHtml(htmlStr string) *Selection {
 	s.eachNodeHtml(htmlStr, true, func(node *html.Node, nodes []*html.Node) {
+		nextSibling := node.NextSibling
 		for _, n := range nodes {
 			if node.Parent != nil {
-				node.Parent.InsertBefore(n, node.NextSibling)
+				node.Parent.InsertBefore(n, nextSibling)
 			}
 		}
 	})
@@ -310,7 +313,7 @@ func (s *Selection) SetHtml(htmlStr string) *Selection {
 			context.RemoveChild(c)
 		}
 	}
-	return s.eachNodeHtml(htmlStr, true, func(node *html.Node, nodes []*html.Node) {
+	return s.eachNodeHtml(htmlStr, false, func(node *html.Node, nodes []*html.Node) {
 		for _, n := range nodes {
 			node.AppendChild(n)
 		}
@@ -371,7 +374,7 @@ func (s *Selection) WrapSelection(sel *Selection) *Selection {
 //
 // It returns the original set of elements.
 func (s *Selection) WrapHtml(htmlStr string) *Selection {
-	nodesMap := make(map[html.NodeType][]*html.Node)
+	nodesMap := make(map[string][]*html.Node)
 	for _, context := range s.Nodes {
 		var parent *html.Node
 		if context.Parent != nil {
@@ -379,10 +382,10 @@ func (s *Selection) WrapHtml(htmlStr string) *Selection {
 		} else {
 			parent = &html.Node{Type: html.ElementNode}
 		}
-		nodes, found := nodesMap[parent.Type]
+		nodes, found := nodesMap[nodeName(parent)]
 		if !found {
 			nodes = parseHtmlWithContext(htmlStr, parent)
-			nodesMap[parent.Type] = nodes
+			nodesMap[nodeName(parent)] = nodes
 		}
 		newSingleSelection(context, s.document).wrapAllNodes(cloneNodes(nodes)...)
 	}
@@ -519,12 +522,12 @@ func (s *Selection) WrapInnerSelection(sel *Selection) *Selection {
 //
 // It returns the original set of elements.
 func (s *Selection) WrapInnerHtml(htmlStr string) *Selection {
-	nodesMap := make(map[html.NodeType][]*html.Node)
+	nodesMap := make(map[string][]*html.Node)
 	for _, context := range s.Nodes {
-		nodes, found := nodesMap[context.Type]
+		nodes, found := nodesMap[nodeName(context)]
 		if !found {
 			nodes = parseHtmlWithContext(htmlStr, context)
-			nodesMap[context.Type] = nodes
+			nodesMap[nodeName(context)] = nodes
 		}
 		newSingleSelection(context, s.document).wrapInnerNodes(cloneNodes(nodes)...)
 	}
@@ -658,6 +661,9 @@ func (s *Selection) eachNodeHtml(htmlStr string, isParent bool, mergeFn func(n *
 		if isParent {
 			context = n.Parent
 		} else {
+			if n.Type != html.ElementNode {
+				continue
+			}
 			context = n
 		}
 		if context != nil {
@@ -1,6 +1,7 @@
 package goquery

 import (
+	"log"
 	"testing"
 )

@@ -70,8 +71,9 @@ func TestAfterHtmlContext(t *testing.T) {
 				</table>
 			</body>
 		</html>`)
-	doc.Find("table tr td").AfterHtml("<td>Test</td>")
-	assertLength(t, doc.Find("table tr td").Nodes, 4)
+	doc.Find("table tr td").AfterHtml("<td class='c1'>Test</td><td class='c2'>Again</td>")
+	assertLength(t, doc.Find("table tr td").Nodes, 6)
+	assertClass(t, doc.Find("table tr td").Last(), "c2")
 	printSel(t, doc.Selection)
 }

@@ -146,10 +148,10 @@ func TestAppendHtmlContext(t *testing.T) {
 				</table>
 			</body>
 		</html>`)
-	doc.Find("table tr").AppendHtml("<td class='new-node'>new node</td>")
+	doc.Find("table tr").AppendHtml("<td class='c1'>new1</td><td class='c2'>new2</td>")

-	assertLength(t, doc.Find("table td").Nodes, 4)
-	assertClass(t, doc.Find("table td").Last(), "new-node")
+	assertLength(t, doc.Find("table td").Nodes, 6)
+	assertClass(t, doc.Find("table td").Last(), "c2")
 	printSel(t, doc.Selection)
 }

@@ -205,10 +207,10 @@ func TestBeforeHtmlContext(t *testing.T) {
 				</table>
 			</body>
 		</html>`)
-	doc.Find("table tr td:first-child").BeforeHtml("<td class='new-node'>new node</td>")
+	doc.Find("table tr td:first-child").BeforeHtml("<td class='c1'>new1</td><td class='c2'>new2</td>")

-	assertLength(t, doc.Find("table td").Nodes, 4)
-	assertClass(t, doc.Find("table td").First(), "new-node")
+	assertLength(t, doc.Find("table td").Nodes, 6)
+	assertClass(t, doc.Find("table td").First(), "c1")
 	printSel(t, doc.Selection)
 }

@@ -374,10 +376,11 @@ func TestReplaceWithHtmlContext(t *testing.T) {
 				</table>
 			</body>
 		</html>`)
-	doc.Find("table th").ReplaceWithHtml("<td>Test</td><td>Replace</td>")
+	doc.Find("table th").ReplaceWithHtml("<td class='c1'>Test</td><td class='c2'>Replace</td>")

 	assertLength(t, doc.Find("table th").Nodes, 0)
 	assertLength(t, doc.Find("table tr td").Nodes, 4)
+	assertClass(t, doc.Find("table tr td").First(), "c1")
 	printSel(t, doc.Selection)
 }

@@ -434,7 +437,7 @@ func TestSetHtmlContext(t *testing.T) {

 	assertLength(t, doc.Find("table th").Nodes, 0)
 	assertLength(t, doc.Find("table td").Nodes, 4)
-	assertLength(t, doc.Find("table t2").Nodes, 2)
+	assertLength(t, doc.Find("table tr").Nodes, 2)
 	printSel(t, doc.Selection)
 }

@@ -687,3 +690,50 @@ func TestParsingRespectsVaryingContext(t *testing.T) {
 			oBothA)
 	}
 }
+
+func TestHtmlWithNonElementNode(t *testing.T) {
+	const data = `
+<html>
+  <head>
+  </head>
+  <body>
+    <p>
+      This is <span>some</span><b>text</b>.
+    </p>
+  </body>
+</html>
+`
+
+	cases := map[string]func(*Selection, string) *Selection{
+		"AfterHtml":       (*Selection).AfterHtml,
+		"AppendHtml":      (*Selection).AppendHtml,
+		"BeforeHtml":      (*Selection).BeforeHtml,
+		"PrependHtml":     (*Selection).PrependHtml,
+		"ReplaceWithHtml": (*Selection).ReplaceWithHtml,
+		"SetHtml":         (*Selection).SetHtml,
+	}
+	for nm, fn := range cases {
+		// this test is only to make sure that the HTML parsing/manipulation
+		// methods do not raise panics when executed over Selections that contain
+		// non-Element nodes.
+		t.Run(nm, func(t *testing.T) {
+			doc := loadString(t, data)
+			sel := doc.Find("p").Contents()
+			func() {
+				defer func() {
+					if err := recover(); err != nil {
+						t.Fatal(err)
+					}
+				}()
+				fn(sel, "<div></div>")
+			}()
+
+			// print the resulting document in verbose mode
+			h, err := OuterHtml(doc.Selection)
+			if err != nil {
+				log.Fatal(err)
+			}
+			t.Log(h)
+		})
+	}
+}
@@ -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{}

@@ -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)
+	}
+}
Author	SHA1	Message	Date
Martin Angers	e11510b114	Update changelog for 1.7.0	2021-06-14 09:16:48 -04:00
Martin Angers	a9cfd6779b	Merge branch 'wip-i255-single-match'	2021-06-14 09:09:43 -04:00
Martin Angers	b3953ef42a	Finalize documentation	2021-06-14 09:06:47 -04:00
Martin Angers	ee8a7e0a3a	Test and benchmark the Single[Matcher] funcs	2021-06-13 15:02:43 -04:00
Martin Angers	0126a1fd88	Implement Single and SingleMatcher	2021-06-13 14:34:32 -04:00
Martin AngersandGitHub	e1f2d60505	Merge pull request #381 from j0nimost/readme-fix Fixed ExampleScrape README Sample	2021-06-04 14:51:04 -04:00
John Nyingi	1ba0ef7e9b	Fixed ExampleScrape Sample	2021-06-04 21:37:05 +03:00
Martin Angers	795f67a092	Update doc badge	2021-05-19 11:06:14 -04:00
Martin Angers	b67d192c91	Add funding file	2021-05-19 11:03:18 -04:00
Martin Angers	bedb4e7a88	Resubmit build	2021-01-18 18:13:21 -05:00
Martin Angers	a29eef7e71	Update go versions in travis tests	2021-01-18 17:11:31 -05:00
Martin Angers	aa734f3932	add sourcehut build badge	2021-01-11 20:02:20 -05:00
Martin Angers	74649be271	fix go versions	2021-01-11 19:56:54 -05:00
Martin Angers	9d962837e1	try to fix build manifest	2021-01-11 19:24:59 -05:00
Martin Angers	7fc894a0ba	add other go versions to build manifest	2021-01-11 19:17:56 -05:00
Martin Angers	171b719dd6	add fedora build manifest	2021-01-11 19:07:57 -05:00
Martin Angers	f41c56001f	Cut new release	2021-01-11 18:44:58 -05:00
Martin Angers	8a11cc402f	Ignore non-element nodes when inserting html in a selection	2021-01-11 18:43:18 -05:00
Martin AngersandGitHub	70a02e53e3	Merge pull request #364 from santosh653/master AddingPowerSupport_CI/Testing	2020-12-08 08:09:26 -05:00
santosh653andGitHub	3798c63c0d	Update .travis.yml Excluding unsupported versions for Power., ie go <=1.12.x	2020-12-07 23:31:38 -05:00
santosh653andGitHub	705a0066a5	Update .travis.yml Adding power support & updating the go versions to >=1.13 as lower versions are not supported.,	2020-12-07 06:53:59 -05:00
Martin AngersandGitHub	a48bafac4b	Merge pull request #362 from vhodges/master Update README.md, closes #361	2020-11-30 18:58:28 -05:00
Vince HodgesandGitHub	af965a4d72	Update README.md	2020-11-30 15:54:55 -08:00
Martin Angers	b3706f8903	update readme to prepare for new release	2020-10-08 09:16:43 -04:00
Martin AngersandGitHub	7ebd145bd7	Merge pull request #348 from thiemok/context Send context to parseHtml. Closes #178 .	2020-10-08 09:10:18 -04:00
Martin Angers	4a687a672f	add test cases to check html insertion order	2020-10-08 09:02:13 -04:00
thiemok	94c2530dd8	fix(manipulation): fix node insertion and caching issues Node caching was still using the node type instead of the node name in a few places. Updated those to also use the node name as the cache key. ReplaceWithHtml and PrependHtml inserted parsed nodes in the wrong order. Kept track of the correct parent to fix this. Use correct parent flag for SetHtml	2020-10-07 20:04:45 +02:00