Documentation ¶
Overview ¶
Package goquery implements features similar to jQuery, including the chainable syntax, to manipulate and query an HTML document.
GoQuery brings a syntax and a set of features similar to jQuery to the Go language. It is based on Go's net/html package and the CSS Selector library cascadia. Since the net/html parser returns tokens (nodes), and not a full-featured DOM object, jQuery's manipulation and modification functions have been left off (no point in modifying data in the parsed tree of the HTML, it has no effect).
Also, because the net/html parser requires UTF-8 encoding, so does goquery: it is the caller's responsibility to ensure that the source document provides UTF-8 encoded HTML.
Supported functions are query-oriented features (`hasClass()`, `attr()` and the likes), as well as traversing functions that make sense given what we have to work with. This makes GoQuery a great library for scraping web pages.
Syntax-wise, it is as close as possible to jQuery, with the same function names when possible, and that warm and fuzzy chainable interface. jQuery being the ultra-popular library that it is, I felt that writing a similar HTML-manipulating library was better to follow its API than to start anew (in the same spirit as Go's fmt package), even though some of its methods are less than intuitive (looking at you, index()...).
It is hosted on GitHub, along with additional documentation in the README.md file: https://github.com/puerkitobio/goquery
Please note that because of the net/html dependency, goquery requires Go1.1+.
The various methods are split into files based on the category of behavior:
* array.go : array-like positional manipulation of the selection.
- Eq()
- First()
- Get()
- Index...()
- Last()
- Slice()
* expand.go : methods that expand or augment the selection's set.
- Add...()
- AndSelf()
- Union(), which is an alias for AddSelection()
* filter.go : filtering methods, that reduce the selection's set.
- End()
- Filter...()
- Has...()
- Intersection(), which is an alias of FilterSelection()
- Not...()
* iteration.go : methods to loop over the selection's nodes.
- Each()
- EachWithBreak()
- Map()
* property.go : methods that inspect and get the node's properties values.
- Attr()
- Html()
- Length()
- Size(), which is an alias for Length()
- Text()
* query.go : methods that query, or reflect, a node's identity.
- Contains()
- HasClass()
- Is...()
* traversal.go : methods to traverse the HTML document tree.
- Children...()
- Contents()
- Find...()
- Next...()
- Parent[s]...()
- Prev...()
- Siblings...()
* type.go : definition of the types exposed by GoQuery.
- Document
- Selection
Index ¶
- type Document
- type Selection
- func (s *Selection) Add(selector string) *Selection
- func (s *Selection) AddNodes(nodes ...*html.Node) *Selection
- func (s *Selection) AddSelection(sel *Selection) *Selection
- func (s *Selection) AndSelf() *Selection
- func (s *Selection) Attr(attrName string) (val string, exists bool)
- func (s *Selection) Children() *Selection
- func (s *Selection) ChildrenFiltered(selector string) *Selection
- func (s *Selection) Closest(selector string) *Selection
- func (s *Selection) ClosestNodes(nodes ...*html.Node) *Selection
- func (s *Selection) ClosestSelection(sel *Selection) *Selection
- func (s *Selection) Contains(n *html.Node) bool
- func (s *Selection) Contents() *Selection
- func (s *Selection) ContentsFiltered(selector string) *Selection
- func (s *Selection) Each(f func(int, *Selection)) *Selection
- func (s *Selection) EachWithBreak(f func(int, *Selection) bool) *Selection
- func (s *Selection) End() *Selection
- func (s *Selection) Eq(index int) *Selection
- func (s *Selection) Filter(selector string) *Selection
- func (s *Selection) FilterFunction(f func(int, *Selection) bool) *Selection
- func (s *Selection) FilterNodes(nodes ...*html.Node) *Selection
- func (s *Selection) FilterSelection(sel *Selection) *Selection
- func (s *Selection) Find(selector string) *Selection
- func (s *Selection) FindNodes(nodes ...*html.Node) *Selection
- func (s *Selection) FindSelection(sel *Selection) *Selection
- func (s *Selection) First() *Selection
- func (s *Selection) Get(index int) *html.Node
- func (s *Selection) Has(selector string) *Selection
- func (s *Selection) HasClass(class string) bool
- func (s *Selection) HasNodes(nodes ...*html.Node) *Selection
- func (s *Selection) HasSelection(sel *Selection) *Selection
- func (s *Selection) Html() (ret string, e error)
- func (s *Selection) Index() int
- func (s *Selection) IndexOfNode(node *html.Node) int
- func (s *Selection) IndexOfSelection(sel *Selection) int
- func (s *Selection) IndexSelector(selector string) int
- func (s *Selection) Intersection(sel *Selection) *Selection
- func (s *Selection) Is(selector string) bool
- func (s *Selection) IsFunction(f func(int, *Selection) bool) bool
- func (s *Selection) IsNodes(nodes ...*html.Node) bool
- func (s *Selection) IsSelection(sel *Selection) bool
- func (s *Selection) Last() *Selection
- func (s *Selection) Length() int
- func (s *Selection) Map(f func(int, *Selection) string) (result []string)
- func (s *Selection) Next() *Selection
- func (s *Selection) NextAll() *Selection
- func (s *Selection) NextAllFiltered(selector string) *Selection
- func (s *Selection) NextFiltered(selector string) *Selection
- func (s *Selection) NextFilteredUntil(filterSelector string, untilSelector string) *Selection
- func (s *Selection) NextFilteredUntilNodes(filterSelector string, nodes ...*html.Node) *Selection
- func (s *Selection) NextFilteredUntilSelection(filterSelector string, sel *Selection) *Selection
- func (s *Selection) NextUntil(selector string) *Selection
- func (s *Selection) NextUntilNodes(nodes ...*html.Node) *Selection
- func (s *Selection) NextUntilSelection(sel *Selection) *Selection
- func (s *Selection) Not(selector string) *Selection
- func (s *Selection) NotFunction(f func(int, *Selection) bool) *Selection
- func (s *Selection) NotNodes(nodes ...*html.Node) *Selection
- func (s *Selection) NotSelection(sel *Selection) *Selection
- func (s *Selection) Parent() *Selection
- func (s *Selection) ParentFiltered(selector string) *Selection
- func (s *Selection) Parents() *Selection
- func (s *Selection) ParentsFiltered(selector string) *Selection
- func (s *Selection) ParentsFilteredUntil(filterSelector string, untilSelector string) *Selection
- func (s *Selection) ParentsFilteredUntilNodes(filterSelector string, nodes ...*html.Node) *Selection
- func (s *Selection) ParentsFilteredUntilSelection(filterSelector string, sel *Selection) *Selection
- func (s *Selection) ParentsUntil(selector string) *Selection
- func (s *Selection) ParentsUntilNodes(nodes ...*html.Node) *Selection
- func (s *Selection) ParentsUntilSelection(sel *Selection) *Selection
- func (s *Selection) Prev() *Selection
- func (s *Selection) PrevAll() *Selection
- func (s *Selection) PrevAllFiltered(selector string) *Selection
- func (s *Selection) PrevFiltered(selector string) *Selection
- func (s *Selection) PrevFilteredUntil(filterSelector string, untilSelector string) *Selection
- func (s *Selection) PrevFilteredUntilNodes(filterSelector string, nodes ...*html.Node) *Selection
- func (s *Selection) PrevFilteredUntilSelection(filterSelector string, sel *Selection) *Selection
- func (s *Selection) PrevUntil(selector string) *Selection
- func (s *Selection) PrevUntilNodes(nodes ...*html.Node) *Selection
- func (s *Selection) PrevUntilSelection(sel *Selection) *Selection
- func (s *Selection) Siblings() *Selection
- func (s *Selection) SiblingsFiltered(selector string) *Selection
- func (s *Selection) Size() int
- func (s *Selection) Slice(start int, end int) *Selection
- func (s *Selection) Text() string
- func (s *Selection) Union(sel *Selection) *Selection
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Document ¶
Document represents an HTML document to be manipulated. Unlike jQuery, which is loaded as part of a DOM document, and thus acts upon its containing document, GoQuery doesn't know which HTML document to act upon. So it needs to be told, and that's what the Document class is for. It holds the root document node to manipulate, and can make selections on this document.
func NewDocument ¶
NewDocument is a Document constructor that takes a string URL as argument. It loads the specified document, parses it, and stores the root Document node, ready to be manipulated.
func NewDocumentFromNode ¶
NewDocumentFromNode is a Document constructor that takes a root html Node as argument.
func NewDocumentFromReader ¶
NewDocumentFromReader returns a Document from a generic reader. It returns an error as second value if the reader's data cannot be parsed as html. It does *not* check if the reader is also an io.Closer, so the provided reader is never closed by this call, it is the responsibility of the caller to close it if required.
func NewDocumentFromResponse ¶
NewDocumentFromResponse is another Document constructor that takes an http resonse as argument. It loads the specified response's document, parses it, and stores the root Document node, ready to be manipulated. The response's body is closed on return.
type Selection ¶
Selection represents a collection of nodes matching some criteria. The initial Selection can be created by using Document.Find, and then manipulated using the jQuery-like chainable syntax and methods.
func (*Selection) Add ¶
Add adds the selector string's matching nodes to those in the current selection and returns a new Selection object. The selector string is run in the context of the document of the current Selection object.
func (*Selection) AddNodes ¶
AddNodes adds the specified nodes to those in the current selection and returns a new Selection object.
func (*Selection) AddSelection ¶
AddSelection adds the specified Selection object's nodes to those in the current selection and returns a new Selection object.
func (*Selection) AndSelf ¶
AndSelf adds the previous set of elements on the stack to the current set. It returns a new Selection object containing the current Selection combined with the previous one.
func (*Selection) Attr ¶
Attr gets the specified attribute's value for the first element in the Selection. To get the value for each element individually, use a looping construct such as Each or Map method.
func (*Selection) Children ¶
Children gets the child elements of each element in the Selection. It returns a new Selection object containing these elements.
func (*Selection) ChildrenFiltered ¶
ChildrenFiltered gets the child elements of each element in the Selection, filtered by the specified selector. It returns a new Selection object containing these elements.
func (*Selection) Closest ¶
Closest gets the first element that matches the selector by testing the element itself and traversing up through its ancestors in the DOM tree.
func (*Selection) ClosestNodes ¶
ClosestNodes gets the first element that matches one of the nodes by testing the element itself and traversing up through its ancestors in the DOM tree.
func (*Selection) ClosestSelection ¶
ClosestSelection gets the first element that matches one of the nodes in the Selection by testing the element itself and traversing up through its ancestors in the DOM tree.
func (*Selection) Contains ¶
Contains returns true if the specified Node is within, at any depth, one of the nodes in the Selection object. It is NOT inclusive, to behave like jQuery's implementation, and unlike Javascript's .contains, so if the contained node is itself in the selection, it returns false.
func (*Selection) Contents ¶
Contents gets the children of each element in the Selection, including text and comment nodes. It returns a new Selection object containing these elements.
func (*Selection) ContentsFiltered ¶
ContentsFiltered gets the children of each element in the Selection, filtered by the specified selector. It returns a new Selection object containing these elements. Since selectors only act on Element nodes, this function is an alias to ChildrenFiltered unless the selector is empty, in which case it is an alias to Contents.
func (*Selection) Each ¶
Each iterates over a Selection object, executing a function for each matched element. It returns the current Selection object.
func (*Selection) EachWithBreak ¶
EachWithBreak iterates over a Selection object, executing a function for each matched element. It is identical to Each except that it is possible to break out of the loop by returning false in the callback function. It returns the current Selection object.
func (*Selection) End ¶
End ends the most recent filtering operation in the current chain and returns the set of matched elements to its previous state.
func (*Selection) Eq ¶
Eq reduces the set of matched elements to the one at the specified index. If a negative index is given, it counts backwards starting at the end of the set. It returns a new Selection object, and an empty Selection object if the index is invalid.
func (*Selection) Filter ¶
Filter reduces the set of matched elements to those that match the selector string. It returns a new Selection object for this subset of matching elements.
func (*Selection) FilterFunction ¶
FilterFunction reduces the set of matched elements to those that pass the function's test. It returns a new Selection object for this subset of elements.
func (*Selection) FilterNodes ¶
FilterNodes reduces the set of matched elements to those that match the specified nodes. It returns a new Selection object for this subset of elements.
func (*Selection) FilterSelection ¶
FilterSelection reduces the set of matched elements to those that match a node in the specified Selection object. It returns a new Selection object for this subset of elements.
func (*Selection) Find ¶
Find gets the descendants of each element in the current set of matched elements, filtered by a selector. It returns a new Selection object containing these matched elements.
func (*Selection) FindNodes ¶
FindNodes gets the descendants of each element in the current Selection, filtered by some nodes. It returns a new Selection object containing these matched elements.
func (*Selection) FindSelection ¶
FindSelection gets the descendants of each element in the current Selection, filtered by a Selection. It returns a new Selection object containing these matched elements.
func (*Selection) First ¶
First reduces the set of matched elements to the first in the set. It returns a new Selection object, and an empty Selection object if the the selection is empty.
func (*Selection) Get ¶
Get retrieves the underlying node at the specified index. Get without parameter is not implemented, since the node array is available on the Selection object.
func (*Selection) Has ¶
Has reduces the set of matched elements to those that have a descendant that matches the selector. It returns a new Selection object with the matching elements.
func (*Selection) HasClass ¶
HasClass determines whether any of the matched elements are assigned the given class.
func (*Selection) HasNodes ¶
HasNodes reduces the set of matched elements to those that have a descendant that matches one of the nodes. It returns a new Selection object with the matching elements.
func (*Selection) HasSelection ¶
HasSelection reduces the set of matched elements to those that have a descendant that matches one of the nodes of the specified Selection object. It returns a new Selection object with the matching elements.
func (*Selection) Html ¶
Html gets the HTML contents of the first element in the set of matched elements. It includes text and comment nodes.
func (*Selection) Index ¶
Index returns the position of the first element within the Selection object relative to its sibling elements.
func (*Selection) IndexOfNode ¶
IndexOfNode returns the position of the specified node within the Selection object, or -1 if not found.
func (*Selection) IndexOfSelection ¶
IndexOfSelection returns the position of the first node in the specified Selection object within this Selection object, or -1 if not found.
func (*Selection) IndexSelector ¶
IndexSelector returns the position of the first element within the Selection object relative to the elements matched by the selector, or -1 if not found.
func (*Selection) Intersection ¶
Intersection is an alias for FilterSelection.
func (*Selection) Is ¶
Is checks the current matched set of elements against a selector and returns true if at least one of these elements matches.
func (*Selection) IsFunction ¶
IsFunction checks the current matched set of elements against a predicate and returns true if at least one of these elements matches.
func (*Selection) IsNodes ¶
IsNodes checks the current matched set of elements against the specified nodes and returns true if at least one of these elements matches.
func (*Selection) IsSelection ¶
IsSelection checks the current matched set of elements against a Selection object and returns true if at least one of these elements matches.
func (*Selection) Last ¶
Last reduces the set of matched elements to the last in the set. It returns a new Selection object, and an empty Selection object if the selection is empty.
func (*Selection) Map ¶
Map passes each element in the current matched set through a function, producing a slice of string holding the returned values.
func (*Selection) Next ¶
Next gets the immediately following sibling of each element in the Selection. It returns a new Selection object containing the matched elements.
func (*Selection) NextAll ¶
NextAll gets all the following siblings of each element in the Selection. It returns a new Selection object containing the matched elements.
func (*Selection) NextAllFiltered ¶
NextAllFiltered gets all the following siblings of each element in the Selection filtered by a selector. It returns a new Selection object containing the matched elements.
func (*Selection) NextFiltered ¶
NextFiltered gets the immediately following sibling of each element in the Selection filtered by a selector. It returns a new Selection object containing the matched elements.
func (*Selection) NextFilteredUntil ¶
NextFilteredUntil is like NextUntil, with the option to filter the results based on a selector string. It returns a new Selection object containing the matched elements.
func (*Selection) NextFilteredUntilNodes ¶
NextFilteredUntilNodes is like NextUntilNodes, with the option to filter the results based on a selector string. It returns a new Selection object containing the matched elements.
func (*Selection) NextFilteredUntilSelection ¶
NextFilteredUntilSelection is like NextUntilSelection, with the option to filter the results based on a selector string. It returns a new Selection object containing the matched elements.
func (*Selection) NextUntil ¶
NextUntil gets all following siblings of each element up to but not including the element matched by the selector. It returns a new Selection object containing the matched elements.
func (*Selection) NextUntilNodes ¶
NextUntilNodes gets all following siblings of each element up to but not including the element matched by the nodes. It returns a new Selection object containing the matched elements.
func (*Selection) NextUntilSelection ¶
NextUntilSelection gets all following siblings of each element up to but not including the element matched by the Selection. It returns a new Selection object containing the matched elements.
func (*Selection) Not ¶
Not removes elements from the Selection that match the selector string. It returns a new Selection object with the matching elements removed.
func (*Selection) NotFunction ¶
NotFunction removes elements from the Selection that pass the function's test. It returns a new Selection object with the matching elements removed.
func (*Selection) NotNodes ¶
NotNodes removes elements from the Selection that match the specified nodes. It returns a new Selection object with the matching elements removed.
func (*Selection) NotSelection ¶
NotSelection removes elements from the Selection that match a node in the specified Selection object. It returns a new Selection object with the matching elements removed.
func (*Selection) Parent ¶
Parent gets the parent of each element in the Selection. It returns a new Selection object containing the matched elements.
func (*Selection) ParentFiltered ¶
ParentFiltered gets the parent of each element in the Selection filtered by a selector. It returns a new Selection object containing the matched elements.
func (*Selection) Parents ¶
Parents gets the ancestors of each element in the current Selection. It returns a new Selection object with the matched elements.
func (*Selection) ParentsFiltered ¶
ParentsFiltered gets the ancestors of each element in the current Selection. It returns a new Selection object with the matched elements.
func (*Selection) ParentsFilteredUntil ¶
ParentsFilteredUntil is like ParentsUntil, with the option to filter the results based on a selector string. It returns a new Selection object containing the matched elements.
func (*Selection) ParentsFilteredUntilNodes ¶
func (s *Selection) ParentsFilteredUntilNodes(filterSelector string, nodes ...*html.Node) *Selection
ParentsFilteredUntilNodes is like ParentsUntilNodes, with the option to filter the results based on a selector string. It returns a new Selection object containing the matched elements.
func (*Selection) ParentsFilteredUntilSelection ¶
ParentsFilteredUntilSelection is like ParentsUntilSelection, with the option to filter the results based on a selector string. It returns a new Selection object containing the matched elements.
func (*Selection) ParentsUntil ¶
ParentsUntil gets the ancestors of each element in the Selection, up to but not including the element matched by the selector. It returns a new Selection object containing the matched elements.
func (*Selection) ParentsUntilNodes ¶
ParentsUntilNodes gets the ancestors of each element in the Selection, up to but not including the specified nodes. It returns a new Selection object containing the matched elements.
func (*Selection) ParentsUntilSelection ¶
ParentsUntilSelection gets the ancestors of each element in the Selection, up to but not including the elements in the specified Selection. It returns a new Selection object containing the matched elements.
func (*Selection) Prev ¶
Prev gets the immediately preceding sibling of each element in the Selection. It returns a new Selection object containing the matched elements.
func (*Selection) PrevAll ¶
PrevAll gets all the preceding siblings of each element in the Selection. It returns a new Selection object containing the matched elements.
func (*Selection) PrevAllFiltered ¶
PrevAllFiltered gets all the preceding siblings of each element in the Selection filtered by a selector. It returns a new Selection object containing the matched elements.
func (*Selection) PrevFiltered ¶
PrevFiltered gets the immediately preceding sibling of each element in the Selection filtered by a selector. It returns a new Selection object containing the matched elements.
func (*Selection) PrevFilteredUntil ¶
PrevFilteredUntil is like PrevUntil, with the option to filter the results based on a selector string. It returns a new Selection object containing the matched elements.
func (*Selection) PrevFilteredUntilNodes ¶
PrevFilteredUntilNodes is like PrevUntilNodes, with the option to filter the results based on a selector string. It returns a new Selection object containing the matched elements.
func (*Selection) PrevFilteredUntilSelection ¶
PrevFilteredUntilSelection is like PrevUntilSelection, with the option to filter the results based on a selector string. It returns a new Selection object containing the matched elements.
func (*Selection) PrevUntil ¶
PrevUntil gets all preceding siblings of each element up to but not including the element matched by the selector. It returns a new Selection object containing the matched elements.
func (*Selection) PrevUntilNodes ¶
PrevUntilNodes gets all preceding siblings of each element up to but not including the element matched by the nodes. It returns a new Selection object containing the matched elements.
func (*Selection) PrevUntilSelection ¶
PrevUntilSelection gets all preceding siblings of each element up to but not including the element matched by the Selection. It returns a new Selection object containing the matched elements.
func (*Selection) Siblings ¶
Siblings gets the siblings of each element in the Selection. It returns a new Selection object containing the matched elements.
func (*Selection) SiblingsFiltered ¶
SiblingsFiltered gets the siblings of each element in the Selection filtered by a selector. It returns a new Selection object containing the matched elements.
func (*Selection) Slice ¶
Slice reduces the set of matched elements to a subset specified by a range of indices.