From a139b5d77f73963ba6a5af04499a5641684d56cc Mon Sep 17 00:00:00 2001 From: Martin Angers Date: Fri, 31 Aug 2012 10:47:28 -0400 Subject: [PATCH] doc fixes --- doc.go | 126 +++++++++++++++++++++++++++++++++++-------------- expand.go | 5 ++ filter.go | 4 +- filter_test.go | 4 +- property.go | 5 +- 5 files changed, 103 insertions(+), 41 deletions(-) diff --git a/doc.go b/doc.go index 7fc7ed7..af480a6 100644 --- a/doc.go +++ b/doc.go @@ -22,27 +22,83 @@ // WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. /* -Package goquery implements features similar to jQuery, including the chainable syntax, -to manipulate and query an HTML document. +Package goquery implements features similar to jQuery, including the chainable +syntax, to manipulate and query an HTML document. -It depends on Go's experimental html package, which must be installed so that it can be imported -as "exp/html". See this tutorial on how to install it accordingly: http://code.google.com/p/go-wiki/wiki/InstallingExp +It depends on Go's experimental html package, which must be installed so that it +can be imported as "exp/html". See this tutorial on how to install it +accordingly: http://code.google.com/p/go-wiki/wiki/InstallingExp -It uses Cascadia as CSS selector (similar to Sizzle for jQuery). This dependency is automatically installed -when using "go get ..." to install GoQuery. +It uses Cascadia as CSS selector (similar to Sizzle for jQuery). This dependency +is automatically installed when using "go get ..." to install GoQuery. -To provide chainable interface, error management is strict, and goquery panics if an invalid Cascadia selector -is used (basically the same behavior as jQuery/Sizzle/document.querySelectorAll, an error is thrown). This is -necessary since multiple return values cannot be used to allow a chainable interface. +To provide a chainable interface, error management is strict, and goquery panics +if an invalid Cascadia selector is used (this is consistent with the behavior of +jQuery/Sizzle/document.querySelectorAll, where an error is thrown). This is +necessary since multiple return values cannot be used to allow a chainable +interface. -It is hosted here, along with additional documentation in the README.md file: -https://github.com/puerkitobio/goquery +It is hosted on GitHub, along with additional documentation in the README.md +file: https://github.com/puerkitobio/goquery + +The various methods are split into files based on the category of behavior: + +* array.go : array-like positional manipulation of the selection. + - First() + - Last() + - Eq() + - Get() + - Index...() + - Slice() + +* filter.go : filtering methods, that reduce the selection's set. + - Filter...() + - Not...() + - Has...() + - End() + - Intersection(), which is an alias of FilterSelection() + +* expand.go : methods that expand or augment the selection's set. + - Add...() + - AndSelf() + - Union(), which is an alias for AddSelection() + +* query.go : methods that query, or reflect, a node's identity. + - Contains() + - HasClass() + - Is...() + +* property.go : methods that inspect and get the node's properties values. + - Attr() + - Contents() + - Html() + - Length() + - Size(), which is an alias for Length() + - Text() + - Val() + +* traversal.go : methods to traverse the HTML document tree. + - Children...() + - Closest() + - Find...() + - Next...() + - Parent[s]...() + - Prev...() + - Siblings...() + +* iteration.go : methods to loop over the selection's nodes. + - Each() + - Map() + +* type.go : definition of the types exposed by GoQuery. + - Document + - Selection */ package goquery // DONE array.go : Positional Manipulation: First(), Last(), Eq(), Get(), Index(), Slice() // DONE filter.go : Filtering: Filter(), Not(), Has(), End() -// expand.go : "Expanding": Add(), AndSelf() +// DONE expand.go : "Expanding": Add(), AndSelf() // query.go : Reflect (query) node: Is(), Contains(), HasClass() // property.go : Inspect node: Contents(), Html(), Text(), Attr(), Val(), Length(), Size() // traversal.go : Traversal: Find(), Children(), Parents...(), Next...(), Prev...(), Closest(), Siblings() @@ -54,42 +110,42 @@ package goquery // TODO : Check each method, if it applies to any node or only Element nodes (Cascadia's selectors already make sure of that) // TODO : Add the following methods: -// x Add() - Misc. Traversing -// - AndSelf() - Misc. Traversing -// x Attr() - Attributes -// x Children() - Tree Traversal +// x Add() +// x AndSelf() +// x Attr() +// x Children() // - Closest() - Tree Traversal -// x Contains() (static function?) - Utilities - needs tests +// x Contains() // - Contents() (similar to Children(), but includes text and comment nodes, so Children() should filter them out) - Misc. Traversing -// x Each() - Traversing -// x End() - Misc. Traversing -// x Eq() - Filtering -// x Filter() - Filtering -// x Find() : Complete with Selection object and Node object as selectors - Tree Traversal -// x First() - Filtering -// x Get() - Node (DOM) Manipulation -// x Has() - Filtering -// x HasClass() - Attributes +// x Each() +// x End() +// x Eq() +// x Filter() +// - Find() : Complete with Selection object and Node object as selectors - Tree Traversal +// x First() +// x Get() +// x Has() +// x HasClass() // - Html() ? - Attributes -// x Index() - DOM Manipulation +// x Index() // - Is() - Filtering -// x Last() - Filtering -// x Length() / Size() - jQUery property -// x Map() - Filtering +// x Last() +// x Length() / Size() +// x Map() // - Next() - Tree traversal // - NextAll() - Tree traversal // - NextUntil() - Tree traversal -// x Not() - Filtering +// x Not() // - Parent() - Tree traversal // - Parents() - Tree traversal // - ParentsUntil() - Tree traversal // - Prev() - Tree traversal // - PrevAll() - Tree traversal // - PrevUntil() - Tree traversal -// x PushStack() ? - Internals +// x PushStack() // - Siblings() - Tree traversal -// x Slice() - Filtering +// x Slice() // - Text() - DOM Manipulation -// x ToArray() Is not implemented, is Selection.Nodes -// x Unique() ? Or internally only, to remove duplicates and maintain node order? - Utilities +// x ToArray() +// x Unique() internally only // - Val() ? - Attributes diff --git a/expand.go b/expand.go index 3770269..9a107d9 100644 --- a/expand.go +++ b/expand.go @@ -21,6 +21,11 @@ func (this *Selection) AddSelection(sel *Selection) *Selection { return this.AddNodes(sel.Nodes...) } +// Union() is an alias for AddSelection(). +func (this *Selection) Union(sel *Selection) *Selection { + return this.AddSelection(sel) +} + // AddNodes() adds the specified nodes to those in the // current selection and returns a new Selection object. func (this *Selection) AddNodes(nodes ...*html.Node) *Selection { diff --git a/filter.go b/filter.go index 20b1bef..29f5960 100644 --- a/filter.go +++ b/filter.go @@ -61,8 +61,8 @@ func (this *Selection) NotSelection(s *Selection) *Selection { return pushStack(this, winnowNodes(this, s.Nodes, false)) } -// Union() is an alias for FilterSelection(). -func (this *Selection) Union(s *Selection) *Selection { +// Intersection() is an alias for FilterSelection(). +func (this *Selection) Intersection(s *Selection) *Selection { return this.FilterSelection(s) } diff --git a/filter_test.go b/filter_test.go index 97fb706..ae7d853 100644 --- a/filter_test.go +++ b/filter_test.go @@ -94,9 +94,9 @@ func TestNotSelection(t *testing.T) { } } -func TestUnion(t *testing.T) { +func TestIntersection(t *testing.T) { sel := Doc().Find(".pvk-gutter") - sel2 := Doc().Find("div").Union(sel) + sel2 := Doc().Find("div").Intersection(sel) if len(sel2.Nodes) != 6 { t.Errorf("Expected 6 nodes, found %v.", len(sel2.Nodes)) } diff --git a/property.go b/property.go index fddd45a..09c7bcc 100644 --- a/property.go +++ b/property.go @@ -4,8 +4,9 @@ import ( "exp/html" ) -// 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. +// 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 (this *Selection) Attr(attrName string) (val string, exists bool) { if len(this.Nodes) == 0 { return