From b4ca4a1e0baabf47fb1052eb8815175b9821336a Mon Sep 17 00:00:00 2001 From: Jack Palevich Date: Sat, 15 Sep 2012 19:00:31 -0700 Subject: [PATCH] Fix documentation. Hide non-essential types and functions. --- bencode_test.go | 2 +- decode.go | 4 ++-- parse.go | 8 +++---- struct.go | 56 ++++++++++++++++++++++++++++++++++++++++--------- 4 files changed, 53 insertions(+), 17 deletions(-) diff --git a/bencode_test.go b/bencode_test.go index 22d34e8..5257f0d 100644 --- a/bencode_test.go +++ b/bencode_test.go @@ -190,7 +190,7 @@ func checkUnmarshal(expected string, data any) (err error) { dataValue := reflect.ValueOf(data) newOne := reflect.New(reflect.TypeOf(data)) buf := bytes.NewBufferString(expected) - if err = UnmarshalValue(buf, newOne); err != nil { + if err = unmarshalValue(buf, newOne); err != nil { return } if err = checkFuzzyEqualValue(dataValue, newOne.Elem()); err != nil { diff --git a/decode.go b/decode.go index 4adabd0..f44f545 100644 --- a/decode.go +++ b/decode.go @@ -20,10 +20,10 @@ import ( // elements may in turn contain any of the types listed above and so on. // // If Decode encounters a syntax error, it returns with err set to an -// instance of ParseError. See ParseError documentation for details. +// instance of Error. func Decode(r io.Reader) (data interface{}, err error) { jb := newDecoder(nil, nil) - err = Parse(r, jb) + err = parse(r, jb) if err == nil { data = jb.Copy() } diff --git a/parse.go b/parse.go index 02d46e3..cfde50d 100644 --- a/parse.go +++ b/parse.go @@ -103,7 +103,7 @@ func decodeString(r Reader) (data string, err error) { return } -func parse(r Reader, build Builder) (err error) { +func parseFromReader(r Reader, build Builder) (err error) { c, err := r.ReadByte() if err != nil { goto exit @@ -185,7 +185,7 @@ func parse(r Reader, build Builder) (err error) { if err != nil { goto exit } - err = parse(r, build.Elem(n)) + err = parseFromReader(r, build.Elem(n)) if err != nil { goto exit } @@ -201,10 +201,10 @@ exit: // Parse parses the bencode stream and makes calls to // the builder to construct a parsed representation. -func Parse(r io.Reader, builder Builder) (err error) { +func parse(r io.Reader, builder Builder) (err error) { rr, ok := r.(Reader) if !ok { rr = bufio.NewReader(r) } - return parse(rr, builder) + return parseFromReader(rr, builder) } diff --git a/struct.go b/struct.go index 0290d65..d136fb2 100644 --- a/struct.go +++ b/struct.go @@ -226,7 +226,7 @@ func (b *structBuilder) Key(k string) Builder { return nobuilder } -// Unmarshal parses the bencode syntax string s and fills in +// Unmarshal reads and parses the bencode syntax data from r and fills in // an arbitrary struct or slice pointed at by val. // It uses the reflect package to assign to fields // and arrays embedded in val. Well-formed data that does not fit @@ -249,9 +249,9 @@ func (b *structBuilder) Key(k string) Builder { // // unmarshalling the bencode syntax string // -// d5:emailld5:where4:home4:addr15:gre@example.come\ +// "d5:emailld5:where4:home4:addr15:gre@example.come\ // d5:where4:work4:addr12:gre@work.comee4:name14:Gr\ -// ace R. Emlin7:address15:123 Main Streete +// ace R. Emlin7:address15:123 Main Streete" // // via Unmarshal(s, &r) is equivalent to assigning // @@ -277,7 +277,6 @@ func (b *structBuilder) Key(k string) Builder { // To unmarshal a top-level bencode array, pass in a pointer to an empty // slice of the correct type. // - func Unmarshal(r io.Reader, val interface{}) (err error) { // If e represents a value, the answer won't get back to the // caller. Make sure it's a pointer. @@ -285,14 +284,11 @@ func Unmarshal(r io.Reader, val interface{}) (err error) { err = errors.New("Attempt to unmarshal into a non-pointer") return } - err = UnmarshalValue(r, reflect.Indirect(reflect.ValueOf(val))) + err = unmarshalValue(r, reflect.Indirect(reflect.ValueOf(val))) return } -// This API is public primarily to make testing easier, but it is available if you -// have a use for it. - -func UnmarshalValue(r io.Reader, v reflect.Value) (err error) { +func unmarshalValue(r io.Reader, v reflect.Value) (err error) { var b *structBuilder // XXX: Decide if the extra codnitions are needed. Affect map? @@ -306,7 +302,7 @@ func UnmarshalValue(r io.Reader, v reflect.Value) (err error) { b = &structBuilder{val: v} } - err = Parse(r, b) + err = parse(r, b) return } @@ -479,6 +475,46 @@ func isValueNil(val reflect.Value) bool { return false } +// Marshal writes the bencode encoding of val to w. +// +// Marshal traverses the value v recursively. +// +// Marshal uses the following type-dependent encodings: +// +// Floating point, integer, and Number values encode as bencode numbers. +// +// String values encode as bencode strings. +// +// Array and slice values encode as bencode arrays. +// +// Struct values encode as bencode maps. Each exported struct field +// becomes a member of the object. +// The object's default key string is the struct field name +// but can be specified in the struct field's tag value. The "json" key in +// the struct field's tag value is the key name, followed by an optional comma +// and options. Examples: +// +// // Field appears in bencode as key "Field". +// Field int +// +// // Field appears in bencode as key "myName". +// Field int "myName" +// +// Anonymous struct fields are ignored. +// +// Map values encode as bencode objects. +// The map's key type must be string; the object keys are used directly +// as map keys. +// +// Boolean, Pointer, Interface, Channel, complex, and function values cannot +// be encoded in bencode. +// Attempting to encode such a value causes Marshal to return +// a MarshalError. +// +// Bencode cannot represent cyclic data structures and Marshal does not +// handle them. Passing cyclic structures to Marshal will result in +// an infinite recursion. +// func Marshal(w io.Writer, val interface{}) error { return writeValue(w, reflect.ValueOf(val)) }