bplist

README

bplist

Package bplist implements a parser and builder for Apple binary property list files. This is a work in progress.

Documentation

Overview

Package bplist implements a parser and writer for binary property list files.

Index

• func Parse(data []byte, h Handler) error
• type Builder
  • func NewBuilder() *Builder
  • func (b *Builder) Err() error
  • func (b *Builder) Open(coll Collection, f func(*Builder))
  • func (b *Builder) Reset()
  • func (b *Builder) Value(typ Type, datum any) error
  • func (b *Builder) WriteTo(w io.Writer) (int64, error)
• type Collection
  • func (c Collection) String() string
• type Handler
• type Type
  • func (t Type) String() string

Functions

func Parse

func Parse(data []byte, h Handler) error

Parse parses data as a binary property list, calling the methods of h to deliver the results. An error from h terminates parsing and is reported to the caller of Parse.

Only version "00" of the binary property list schema is fully understood.

Types

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

A Builder accumulates values to build a binary property list. The zero value is ready for use. Add elements and collections to the list with Value and Open. When the property list is complete, use WriteTo to encode it.

func NewBuilder

func NewBuilder() *Builder

NewBuilder constructs a new empty property list builder. Add items to the property list using the Value, Open, and Close methods.

func (*Builder) Err

func (b *Builder) Err() error

Err reports the last error that caused an operation on b to fail. It returns nil for a new builder. Any error causes all subsequent operations on the builder to fail with the same error.

func (*Builder) Open

func (b *Builder) Open(coll Collection, f func(*Builder))

Open adds a new empty collection of the given type, and calls f to populate its contents. When f returns, the collection is automatically closed. It is safe and valid for f to open further nested collections.

For example:

b.Open(bplist.Array, func(b *bplist.Builder) {
  b.Value(bplist.TString, "foo")
  b.Value(bplist.TString, "bar")
})

func (*Builder) Reset

func (b *Builder) Reset()

Reset discards all the data associated with b and restores it to its initial state. This also clears any error from a previous failed operation.

func (*Builder) Value

func (b *Builder) Value(typ Type, datum any) error

Value adds a single data element to the property list. It reports an error if typ is not a known element type, or if datum is not a valid value for that type.

func (*Builder) WriteTo

func (b *Builder) WriteTo(w io.Writer) (int64, error)

WriteTo encodes the property list and writes it in binary form to w.

type Collection

type Collection int

Collection enumerates the types of container elements.

const (
	Array Collection = iota + 1 // an ordered sequence
	Set                         // an unordered group
	Dict                        // a collection of key/value pairs
)

Constants defining the collection types.

func (Collection) String

func (c Collection) String() string

type Handler

type Handler interface {
	// Called for the version string, e.g., "00". This method is the first to be
	// called when a file is parsed, and if it reports an error, the rest of the
	// file will not be consumed.
	Version(string) error

	// Called for primitive data values. The concrete type of the datum depends
	// on the Type; see the comments for the Type enumerators.
	Value(typ Type, datum any) error

	// Called to indicate the beginning of new collection of the given type,
	// having n elements. After Open, subsequent values belong to this
	// collection until the corresponding Close.  For a dictionary, keys and
	// values alternate: key1, value, key2, value2, ..., in n pairs.
	Open(typ Collection, n int) error

	// Called to indicate the end of the most recently-opened collection of the
	// given type.
	Close(Collection) error
}

A Handler provides callbacks to handle objects from a property list. If a handler method reports an error, that error is propagated to the caller.

type Type

type Type int

Type enumerates the types of primitive elements in the property list.

const (
	// TNull represents the singleton null value. Its datum is nil.
	TNull Type = iota

	// TBool represents a Boolean value. Its datum is a bool.
	TBool

	// TInteger represents an integer value. Its datum is an int64.
	TInteger

	// TFloat represents a floating-point value. Its datum is a float64.
	TFloat

	// TTime represents a timestamp. Its datum is a time.Time in UTC.
	TTime

	// TBytes represents arbitrary bytes. Its datum is a []byte.
	TBytes

	// TString represents a UTF-8 string value. Its datum is a string.
	TString

	// TUnicode represents a UTF-16 string. Its datum is a []rune.
	TUnicode

	// TUID represents a UID value. Its datum is a []byte.
	TUID
)

func (Type) String

func (t Type) String() string