internal/export/idna: improved naming, docs, and examples.
I hope this makes it a bit clearer.
Documentation with the ToASCII and ToUnicode functions
has been removed to avoid suggesting that this behavior is
specific to the Punycode Profile.
Renamed UseSTD3Rules to the more descriptive StrictDomainName.
Other possible names are StrictASCII or just DomainName.
Change-Id: Iec8e8d4dd6c8f4ebda71c2894a199c9203f263db
Reviewed-on: https://go-review.googlesource.com/36871
Run-TryBot: Marcel van Lohuizen <mpvl@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Nigel Tao <nigeltao@golang.org>
diff --git a/internal/export/idna/example_test.go b/internal/export/idna/example_test.go
index ab8d326..6e31be9 100644
--- a/internal/export/idna/example_test.go
+++ b/internal/export/idna/example_test.go
@@ -10,6 +10,32 @@
"golang.org/x/text/internal/export/idna"
)
+func ExampleProfile() {
+ // Raw Punycode has no restrictions and does no mappings.
+ fmt.Println(idna.ToASCII(""))
+ fmt.Println(idna.ToASCII("*.faß.com"))
+ fmt.Println(idna.Punycode.ToASCII("*.faß.com"))
+
+ // Rewrite IDN for lookup. This (currently) uses transitional mappings to
+ // find a balance between IDNA2003 and IDNA2008 compatibility.
+ fmt.Println(idna.Lookup.ToASCII(""))
+ fmt.Println(idna.Lookup.ToASCII("www.faß.com"))
+
+ // Convert an IDN to ASCII for registration purposes. This changes the
+ // encoding, but reports an error if the input was illformed.
+ fmt.Println(idna.Registration.ToASCII(""))
+ fmt.Println(idna.Registration.ToASCII("www.faß.com"))
+
+ // Output:
+ // <nil>
+ // *.xn--fa-hia.com <nil>
+ // *.xn--fa-hia.com <nil>
+ // <nil>
+ // www.fass.com <nil>
+ // idna: invalid label ""
+ // www.xn--fa-hia.com <nil>
+}
+
func ExampleNew() {
var p *idna.Profile
@@ -26,8 +52,8 @@
// Set up a profile maps for lookup, but allows wild cards.
p = idna.New(
idna.MapForLookup(),
- idna.Transitional(true), // Map ß -> ss
- idna.UseSTD3Rules(false)) // Set more permissive ASCII rules.
+ idna.Transitional(true), // Map ß -> ss
+ idna.StrictDomainName(false)) // Set more permissive ASCII rules.
fmt.Println(p.ToASCII("*.faß.com"))
// Output:
diff --git a/internal/export/idna/idna.go b/internal/export/idna/idna.go
index 5f91db6..a3d9ad2 100644
--- a/internal/export/idna/idna.go
+++ b/internal/export/idna/idna.go
@@ -39,19 +39,12 @@
// error in the future.
// I think Option 1 is best, but it is quite opinionated.
-// ToASCII is a wrapper for Punycode.ToASCII. It converts a domain or domain
-// label to its ASCII form. For example, ToASCII("bücher.example.com") is
-// "xn--bcher-kva.example.com", and ToASCII("golang") is "golang". If an error
-// is encountered it will return an error and a (partially) processed result.
+// ToASCII is a wrapper for Punycode.ToASCII.
func ToASCII(s string) (string, error) {
return Punycode.process(s, true)
}
-// ToUnicode is a wrapper for Punycode.ToUnicode. It converts a domain or domain
-// label to its Unicode form. For example,
-// ToUnicode("xn--bcher-kva.example.com") is "bücher.example.com", and
-// ToUnicode("golang") is "golang". If an error is encountered it will return an
-// error and a (partially) processed result.
+// ToUnicode is a wrapper for Punycode.ToUnicode.
func ToUnicode(s string) (string, error) {
return Punycode.process(s, false)
}
@@ -59,9 +52,11 @@
// An Option configures a Profile at creation time.
type Option func(*options)
-// Transitional sets a Profile to use the Transitional mapping as defined
-// in UTS #46. This will cause, for example, "ß" to be mapped to "ss".
-// This option is only useful if combined with MapForLookup.
+// Transitional sets a Profile to use the Transitional mapping as defined in UTS
+// #46. This will cause, for example, "ß" to be mapped to "ss". Using the
+// transitional mapping provides a compromise between IDNA2003 and IDNA2008
+// compatibility. It is used by most browsers when resolving domain names. This
+// option is only meaningful if combined with MapForLookup.
func Transitional(transitional bool) Option {
return func(o *options) { o.transitional = true }
}
@@ -88,13 +83,15 @@
}
}
-// UseSTD3Rules sets whether ASCII characters outside the A-Z, a-z, 0-9 and the
-// hyphen should be disallowed. Disallowing these characters is required by
-// IDNA2008 and is the default for ValidateForRegistration and MapForLookup.
-// However, IDNA2003 and UTS #46 allow this to be overridden to support browsers
-// that allow characters outside this range, for example a '_' (U+005F LOW
-// LINE). See http://www.rfc-editor.org/std/std3.txt for more details.
-func UseSTD3Rules(use bool) Option {
+// StrictDomainName limits the set of permissable ASCII characters to those
+// allowed in domain names as defined in RFC 1034 (A-Z, a-z, 0-9 and the
+// hyphen). This is set by default for MapForLookup and ValidateForRegistration.
+//
+// This option is useful, for instance, for browsers that allow characters
+// outside this range, for example a '_' (U+005F LOW LINE). See
+// http://www.rfc-editor.org/std/std3.txt for more details This option
+// corresponds to the UseSTD3ASCIIRules option in UTS #46.
+func StrictDomainName(use bool) Option {
return func(o *options) {
o.trie = trie
o.useSTD3Rules = use
@@ -116,7 +113,7 @@
func ValidateForRegistration() Option {
return func(o *options) {
o.mapping = validateRegistration
- UseSTD3Rules(true)(o)
+ StrictDomainName(true)(o)
ValidateLabels(true)(o)
VerifyDNSLength(true)(o)
BidiRule()(o)
@@ -134,7 +131,7 @@
func MapForLookup() Option {
return func(o *options) {
o.mapping = validateAndMap
- UseSTD3Rules(true)(o)
+ StrictDomainName(true)(o)
ValidateLabels(true)(o)
}
}
diff --git a/internal/export/idna/idna_test.go b/internal/export/idna/idna_test.go
index 5ad0e5a..01fd50b 100644
--- a/internal/export/idna/idna_test.go
+++ b/internal/export/idna/idna_test.go
@@ -122,7 +122,7 @@
p := New(VerifyDNSLength(true), MapForLookup(), BidiRule())
lengthU := kind{"CheckLengthU", p.ToUnicode}
lengthA := kind{"CheckLengthA", p.ToASCII}
- p = New(MapForLookup(), UseSTD3Rules(false))
+ p = New(MapForLookup(), StrictDomainName(false))
std3 := kind{"STD3", p.ToASCII}
testCases := []struct {
