Examples appear in the documentation (go-ldap#251)

ccin2p3 · Dec 13, 2019 · a75d3c9 · a75d3c9
1 parent 5c8e362
commit a75d3c9
Show file tree

Hide file tree

Showing 21 changed files with 59 additions and 395 deletions.
diff --git a/README.md b/README.md
@@ -3,6 +3,11 @@
 
 # Basic LDAP v3 functionality for the GO programming language.
 
+The library implements the following specifications:
+ - https://tools.ietf.org/html/rfc4511 for basic operations
+ - https://tools.ietf.org/html/rfc3062 for password modify operation
+ - https://tools.ietf.org/html/rfc4514 for distinguished names parsing
+
 ## Features:
 
  - Connecting to LDAP server (non-TLS, TLS, STARTTLS)
@@ -15,11 +20,6 @@
  - Delete Requests / Responses
  - Modify DN Requests / Responses
 
-## Examples:
-
- - search
- - modify
-
 ## Go Modules:
 
 `go get github.com/go-ldap/ldap/v3`

diff --git a/add.go b/add.go
@@ -1,12 +1,3 @@
-//
-// https://tools.ietf.org/html/rfc4511
-//
-// AddRequest ::= [APPLICATION 8] SEQUENCE {
-//      entry           LDAPDN,
-//      attributes      AttributeList }
-//
-// AttributeList ::= SEQUENCE OF attribute Attribute
-
 package ldap
 
 import (

diff --git a/compare.go b/compare.go
@@ -1,22 +1,3 @@
-// File contains Compare functionality
-//
-// https://tools.ietf.org/html/rfc4511
-//
-// CompareRequest ::= [APPLICATION 14] SEQUENCE {
-//              entry           LDAPDN,
-//              ava             AttributeValueAssertion }
-//
-// AttributeValueAssertion ::= SEQUENCE {
-//              attributeDesc   AttributeDescription,
-//              assertionValue  AssertionValue }
-//
-// AttributeDescription ::= LDAPString
-//                         -- Constrained to <attributedescription>
-//                         -- [RFC4512]
-//
-// AttributeValue ::= OCTET STRING
-//
-
 package ldap
 
 import (

diff --git a/del.go b/del.go
@@ -1,8 +1,3 @@
-//
-// https://tools.ietf.org/html/rfc4511
-//
-// DelRequest ::= [APPLICATION 10] LDAPDN
-
 package ldap
 
 import (

diff --git a/dn.go b/dn.go
@@ -1,44 +1,3 @@
-// File contains DN parsing functionality
-//
-// https://tools.ietf.org/html/rfc4514
-//
-//   distinguishedName = [ relativeDistinguishedName
-//         *( COMMA relativeDistinguishedName ) ]
-//     relativeDistinguishedName = attributeTypeAndValue
-//         *( PLUS attributeTypeAndValue )
-//     attributeTypeAndValue = attributeType EQUALS attributeValue
-//     attributeType = descr / numericoid
-//     attributeValue = string / hexstring
-//
-//     ; The following characters are to be escaped when they appear
-//     ; in the value to be encoded: ESC, one of <escaped>, leading
-//     ; SHARP or SPACE, trailing SPACE, and NULL.
-//     string =   [ ( leadchar / pair ) [ *( stringchar / pair )
-//        ( trailchar / pair ) ] ]
-//
-//     leadchar = LUTF1 / UTFMB
-//     LUTF1 = %x01-1F / %x21 / %x24-2A / %x2D-3A /
-//        %x3D / %x3F-5B / %x5D-7F
-//
-//     trailchar  = TUTF1 / UTFMB
-//     TUTF1 = %x01-1F / %x21 / %x23-2A / %x2D-3A /
-//        %x3D / %x3F-5B / %x5D-7F
-//
-//     stringchar = SUTF1 / UTFMB
-//     SUTF1 = %x01-21 / %x23-2A / %x2D-3A /
-//        %x3D / %x3F-5B / %x5D-7F
-//
-//     pair = ESC ( ESC / special / hexpair )
-//     special = escaped / SPACE / SHARP / EQUALS
-//     escaped = DQUOTE / PLUS / COMMA / SEMI / LANGLE / RANGLE
-//     hexstring = SHARP 1*hexpair
-//     hexpair = HEX HEX
-//
-//  where the productions <descr>, <numericoid>, <COMMA>, <DQUOTE>,
-//  <EQUALS>, <ESC>, <HEX>, <LANGLE>, <NULL>, <PLUS>, <RANGLE>, <SEMI>,
-//  <SPACE>, <SHARP>, and <UTFMB> are defined in [RFC4512].
-//
-
 package ldap
 
 import (
@@ -48,7 +7,7 @@ import (
 	"fmt"
 	"strings"
 
-	"github.com/go-asn1-ber/asn1-ber"
+	ber "github.com/go-asn1-ber/asn1-ber"
 )
 
 // AttributeTypeAndValue represents an attributeTypeAndValue from https://tools.ietf.org/html/rfc4514
@@ -69,7 +28,8 @@ type DN struct {
 	RDNs []*RelativeDN
 }
 
-// ParseDN returns a distinguishedName or an error
+// ParseDN returns a distinguishedName or an error.
+// The function respects https://tools.ietf.org/html/rfc4514
 func ParseDN(str string) (*DN, error) {
 	dn := new(DN)
 	dn.RDNs = make([]*RelativeDN, 0)

diff --git a/moddn_test.go → examples_moddn_test.go b/moddn_test.go → examples_moddn_test.go
@@ -4,9 +4,9 @@ import (
 	"log"
 )
 
-// ExampleConn_ModifyDN_renameNoMove shows how to rename an entry without moving it
+// This example shows how to rename an entry without moving it
 func ExampleConn_ModifyDN_renameNoMove() {
-	conn, err := Dial("tcp", "ldap.example.org:389")
+	conn, err := DialURL("ldap://ldap.example.org:389")
 	if err != nil {
 		log.Fatalf("Failed to connect: %s\n", err)
 	}
@@ -26,9 +26,9 @@ func ExampleConn_ModifyDN_renameNoMove() {
 	}
 }
 
-// ExampleConn_ModifyDN_renameAndMove shows how to rename an entry and moving it to a new base
+// This example shows how to rename an entry and moving it to a new base
 func ExampleConn_ModifyDN_renameAndMove() {
-	conn, err := Dial("tcp", "ldap.example.org:389")
+	conn, err := DialURL("ldap://ldap.example.org:389")
 	if err != nil {
 		log.Fatalf("Failed to connect: %s\n", err)
 	}
@@ -50,9 +50,9 @@ func ExampleConn_ModifyDN_renameAndMove() {
 	}
 }
 
-// ExampleConn_ModifyDN_moveOnly shows how to move an entry to a new base without renaming the RDN
+// This example shows how to move an entry to a new base without renaming the RDN
 func ExampleConn_ModifyDN_moveOnly() {
-	conn, err := Dial("tcp", "ldap.example.org:389")
+	conn, err := DialURL("ldap://ldap.example.org:389")
 	if err != nil {
 		log.Fatalf("Failed to connect: %s\n", err)
 	}

diff --git a/example_test.go → examples_test.go b/example_test.go → examples_test.go
@@ -6,10 +6,10 @@ import (
 	"log"
 )
 
-// ExampleConn_Bind demonstrates how to bind a connection to an ldap user
+// This example demonstrates how to bind a connection to an ldap user
 // allowing access to restricted attributes that user has access to
 func ExampleConn_Bind() {
-	l, err := Dial("tcp", fmt.Sprintf("%s:%d", "ldap.example.com", 389))
+	l, err := DialURL("ldap://ldap.example.com:389")
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -21,9 +21,9 @@ func ExampleConn_Bind() {
 	}
 }
 
-// ExampleConn_Search demonstrates how to use the search interface
+// This example demonstrates how to use the search interface
 func ExampleConn_Search() {
-	l, err := Dial("tcp", fmt.Sprintf("%s:%d", "ldap.example.com", 389))
+	l, err := DialURL("ldap://ldap.example.com:389")
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -47,9 +47,9 @@ func ExampleConn_Search() {
 	}
 }
 
-// ExampleStartTLS demonstrates how to start a TLS connection
+// This example demonstrates how to start a TLS connection
 func ExampleConn_StartTLS() {
-	l, err := Dial("tcp", fmt.Sprintf("%s:%d", "ldap.example.com", 389))
+	l, err := DialURL("ldap://ldap.example.com:389")
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -64,9 +64,9 @@ func ExampleConn_StartTLS() {
 	// Operations via l are now encrypted
 }
 
-// ExampleConn_Compare demonstrates how to compare an attribute with a value
+// This example demonstrates how to compare an attribute with a value
 func ExampleConn_Compare() {
-	l, err := Dial("tcp", fmt.Sprintf("%s:%d", "ldap.example.com", 389))
+	l, err := DialURL("ldap://ldap.example.com:389")
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -81,7 +81,7 @@ func ExampleConn_Compare() {
 }
 
 func ExampleConn_PasswordModify_admin() {
-	l, err := Dial("tcp", fmt.Sprintf("%s:%d", "ldap.example.com", 389))
+	l, err := DialURL("ldap://ldap.example.com:389")
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -101,7 +101,7 @@ func ExampleConn_PasswordModify_admin() {
 }
 
 func ExampleConn_PasswordModify_generatedPassword() {
-	l, err := Dial("tcp", fmt.Sprintf("%s:%d", "ldap.example.com", 389))
+	l, err := DialURL("ldap://ldap.example.com:389")
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -123,7 +123,7 @@ func ExampleConn_PasswordModify_generatedPassword() {
 }
 
 func ExampleConn_PasswordModify_setNewPassword() {
-	l, err := Dial("tcp", fmt.Sprintf("%s:%d", "ldap.example.com", 389))
+	l, err := DialURL("ldap://ldap.example.com:389")
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -143,7 +143,7 @@ func ExampleConn_PasswordModify_setNewPassword() {
 }
 
 func ExampleConn_Modify() {
-	l, err := Dial("tcp", fmt.Sprintf("%s:%d", "ldap.example.com", 389))
+	l, err := DialURL("ldap://ldap.example.com:389")
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -160,7 +160,7 @@ func ExampleConn_Modify() {
 	}
 }
 
-// Example User Authentication shows how a typical application can verify a login attempt
+// This example shows how a typical application can verify a login attempt
 func Example_userAuthentication() {
 	// The username and password we want to check
 	username := "someuser"
@@ -169,7 +169,7 @@ func Example_userAuthentication() {
 	bindusername := "readonly"
 	bindpassword := "password"
 
-	l, err := Dial("tcp", fmt.Sprintf("%s:%d", "ldap.example.com", 389))
+	l, err := DialURL("ldap://ldap.example.com:389")
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -221,7 +221,7 @@ func Example_userAuthentication() {
 }
 
 func Example_beherappolicy() {
-	l, err := Dial("tcp", fmt.Sprintf("%s:%d", "ldap.example.com", 389))
+	l, err := DialURL("ldap://ldap.example.com:389")
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -260,7 +260,7 @@ func Example_beherappolicy() {
 }
 
 func Example_vchuppolicy() {
-	l, err := Dial("tcp", fmt.Sprintf("%s:%d", "ldap.example.com", 389))
+	l, err := DialURL("ldap://ldap.example.com:389")
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -305,7 +305,7 @@ func Example_vchuppolicy() {
 // This example demonstrates how to use ControlPaging to manually execute a
 // paginated search request instead of using SearchWithPaging.
 func ExampleControlPaging_manualPaging() {
-	conn, err := Dial("tcp", fmt.Sprintf("%s:%d", "ldap.example.com", 389))
+	conn, err := DialURL("ldap://ldap.example.com:389")
 	if err != nil {
 		log.Fatal(err)
 	}

diff --git a/moddn.go b/moddn.go
@@ -1,13 +1,3 @@
-// Package ldap - moddn.go contains ModifyDN functionality
-//
-// https://tools.ietf.org/html/rfc4511
-// ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
-//      entry           LDAPDN,
-//      newrdn          RelativeLDAPDN,
-//      deleteoldrdn    BOOLEAN,
-//      newSuperior     [0] LDAPDN OPTIONAL }
-//
-//
 package ldap
 
 import (

diff --git a/modify.go b/modify.go
@@ -1,28 +1,3 @@
-// File contains Modify functionality
-//
-// https://tools.ietf.org/html/rfc4511
-//
-// ModifyRequest ::= [APPLICATION 6] SEQUENCE {
-//      object          LDAPDN,
-//      changes         SEQUENCE OF change SEQUENCE {
-//           operation       ENUMERATED {
-//                add     (0),
-//                delete  (1),
-//                replace (2),
-//                ...  },
-//           modification    PartialAttribute } }
-//
-// PartialAttribute ::= SEQUENCE {
-//      type       AttributeDescription,
-//      vals       SET OF value AttributeValue }
-//
-// AttributeDescription ::= LDAPString
-//                         -- Constrained to <attributedescription>
-//                         -- [RFC4512]
-//
-// AttributeValue ::= OCTET STRING
-//
-
 package ldap
 
 import (

diff --git a/passwdmodify.go b/passwdmodify.go
@@ -1,8 +1,3 @@
-// This file contains the password modify extended operation as specified in rfc 3062
-//
-// https://tools.ietf.org/html/rfc3062
-//
-
 package ldap
 
 import (
@@ -61,7 +56,7 @@ func (req *PasswordModifyRequest) appendTo(envelope *ber.Packet) error {
 
 // NewPasswordModifyRequest creates a new PasswordModifyRequest
 //
-// According to the RFC 3602:
+// According to the RFC 3602 (https://tools.ietf.org/html/rfc3062):
 // userIdentity is a string representing the user associated with the request.
 // This string may or may not be an LDAPDN (RFC 2253).
 // If userIdentity is empty then the operation will act on the user associated