unicode/cldr: improve documentation
Change-Id: I376ad957a3417cc909f828786d6faf2a0d61bb1f
Reviewed-on: https://go-review.googlesource.com/101995
Run-TryBot: Marcel van Lohuizen <mpvl@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ross Light <light@google.com>
diff --git a/unicode/cldr/cldr.go b/unicode/cldr/cldr.go
index 2197f8a..052845f 100644
--- a/unicode/cldr/cldr.go
+++ b/unicode/cldr/cldr.go
@@ -5,14 +5,15 @@
//go:generate go run makexml.go -output xml.go
// Package cldr provides a parser for LDML and related XML formats.
-// This package is intended to be used by the table generation tools
-// for the various internationalization-related packages.
-// As the XML types are generated from the CLDR DTD, and as the CLDR standard
-// is periodically amended, this package may change considerably over time.
-// This mostly means that data may appear and disappear between versions.
-// That is, old code should keep compiling for newer versions, but data
-// may have moved or changed.
-// CLDR version 22 is the first version supported by this package.
+//
+// This package is intended to be used by the table generation tools for the
+// various packages in x/text and is not internal for historical reasons.
+//
+// As the XML types are generated from the CLDR DTD, and as the CLDR standard is
+// periodically amended, this package may change considerably over time. This
+// mostly means that data may appear and disappear between versions. That is,
+// old code should keep compiling for newer versions, but data may have moved or
+// changed. CLDR version 22 is the first version supported by this package.
// Older versions may not work.
package cldr // import "golang.org/x/text/unicode/cldr"
@@ -94,6 +95,12 @@
// LDML returns the fully resolved LDML XML for loc, which must be one of
// the strings returned by Locales.
+//
+// Deprecated: use RawLDML and implement inheritance manually or using the
+// internal cldrtree package.
+// Inheritance has changed quite a bit since the onset of this package and in
+// practice data often represented in a way where knowledge of how it was
+// inherited is relevant.
func (cldr *CLDR) LDML(loc string) (*LDML, error) {
return cldr.resolve(loc)
}
diff --git a/unicode/cldr/decode.go b/unicode/cldr/decode.go
index 094d431..bb4d4d1 100644
--- a/unicode/cldr/decode.go
+++ b/unicode/cldr/decode.go
@@ -58,9 +58,10 @@
if len(d.dirFilter) > 0 && !in(d.dirFilter, m[1]) {
continue
}
- var r io.Reader
+ var r io.ReadCloser
if r, err = l.Reader(i); err == nil {
err = d.decode(m[1], m[2], r)
+ r.Close()
}
if err != nil {
return nil, err
diff --git a/unicode/cldr/examples_test.go b/unicode/cldr/examples_test.go
index 1a69b00..85d79d1 100644
--- a/unicode/cldr/examples_test.go
+++ b/unicode/cldr/examples_test.go
@@ -2,10 +2,85 @@
import (
"fmt"
+ "os"
+ "path/filepath"
+ "golang.org/x/text/internal/gen"
"golang.org/x/text/unicode/cldr"
)
+func ExampleDecoder() {
+ // Obtain the default CLDR reader (only for x/text packages).
+
+ var d cldr.Decoder
+
+ // Speed up decoding by setting filters for only what you need.
+ d.SetDirFilter("main", "supplemental")
+ d.SetSectionFilter("numbers", "plurals")
+
+ cldr, err := d.DecodeZip(gen.OpenCLDRCoreZip())
+ if err != nil {
+ fmt.Println("ERROR", err)
+ return
+ }
+ supplemental := cldr.Supplemental()
+
+ fmt.Println(supplemental.MeasurementData.MeasurementSystem[0].Type)
+ for _, lang := range cldr.Locales() {
+ data := cldr.RawLDML(lang)
+ fmt.Println(lang, data.Identity.Version.Number)
+ }
+}
+
+func ExampleDecoder_DecodePath() {
+ // This directory will exist if a go generate has been run in any of the
+ // packages in x/text using the cldr package.
+ path := filepath.FromSlash("../../DATA/cldr/" + cldr.Version)
+
+ var d cldr.Decoder
+
+ // Speed up decoding by setting filters for only what you need.
+ d.SetDirFilter("main")
+ d.SetSectionFilter("numbers")
+
+ cldr, err := d.DecodePath(path)
+ if err != nil {
+ // handle error
+ fmt.Println("ERROR", err)
+ return
+ }
+ for _, lang := range cldr.Locales() {
+ if numbers := cldr.RawLDML(lang).Numbers; numbers != nil {
+ fmt.Println(lang, len(numbers.Symbols))
+ }
+ }
+}
+
+func ExampleDecoder_DecodeZip() {
+ // This directory will exist if a go generate has been run in any of the
+ // packages in x/text using the cldr package.
+ path := filepath.FromSlash("../../DATA/cldr/" + cldr.Version)
+
+ var d cldr.Decoder
+
+ r, err := os.Open(filepath.Join(path, "core.zip"))
+ if err != nil {
+ fmt.Println("error:", err)
+ return
+ }
+
+ // Only loading supplemental data can be done much faster using a dir
+ // filter.
+ d.SetDirFilter("supplemental")
+ cldr, err := d.DecodeZip(r)
+ if err != nil {
+ fmt.Println("error:", err)
+ return
+ }
+
+ fmt.Println(cldr.Supplemental().MeasurementData.MeasurementSystem[0].Type)
+}
+
func ExampleSlice() {
var dr *cldr.CLDR // assume this is initialized
