README
¶
Package cloudeng.io/file/content
import cloudeng.io/file/content
Package content provides support for working with different content types. In particular it defines a mean of specifying content types and a registry for matching content types against handlers for processing those types.
Constants
InvalidObjectEncoding, GOBObjectEncoding, JSONObjectEncoding
InvalidObjectEncoding ObjectEncoding = iota
GOBObjectEncoding = iota
JSONObjectEncoding
Functions
Func Error
func Error(err error) error
Error is an implementation of error that is registered with the gob package and marshals the error as the string value returned by its Error() method. It will return nil if the specified error is nil. Common usage is:
response.Err = content.Error(object.Err)
Func ParseType
func ParseType(ctype Type) (string, error)
ParseType is like ParseTypeFull but only returns the major/minor component.
Func ParseTypeFull
func ParseTypeFull(ctype Type) (typ, par, value string, err error)
ParseTypeFull parses a content type specification into its major/minor components and any parameter/value pairs. It returns an error if multiple / or ; characters are found.
Types
Type Object
type Object[Value, Response any] struct {
Type Type
Value Value
Response Response
}
Object represents the result of object/file download/crawl operation. As such it contains both the value that was downloaded and the result of the operation. The Value field represents the typed value of the result of the download or API operation. The Response field is the actual response for the download, API call and may include additional metadata such as object size, ownership etc. The content.Type is used by a reader to determine the type of the Value and Response fields and in this sense an object is a union.
Objects are intended to be serialized to/from storage with the reader needing to determine the types of the serialized Value and Response from the encoded data. The format chosen for the serialized data is intended to allow for dealing with the different sources of both Value and Response and allows for each to be encoded using a different encoding. For example, a response from a rest API may be only encodable as json. Similarly responses generated by native go code are likely most conveniently encoded as gob. The serialized format is:
type []byte
valueEncoding uint8
responseEncoding uint8
value []byte
response []byte
The gob format assumes that the decoder knows the type of the previously encoded binary data, including interface types. JSON cannot readily handle interface types.
When gob encoding is used care must be taken to ensure that any fields that are interface types are appropriately registered with the gob package. error is a common such case and the Error function can be used to replace the existing error with a wrapper that implements the error interface and is registered with the gob package. Canonical usage is:
response.Err = content.Error(object.Err)
Methods
func (o *Object[V, R]) Decode(data []byte) error
Decode decodes the object in data.
func (o *Object[V, R]) Encode(valueEncoding, responseEncoding ObjectEncoding) ([]byte, error)
Encode encodes the object using the requested encodings.
func (o *Object[V, R]) WriteObjectFile(path string, valueEncoding, responseEncoding ObjectEncoding) error
WriteObject will encode the object using the requested encoding to the specified file. It will create the directory that the file is to be written to if it does not exist.
Type ObjectEncoding
type ObjectEncoding int
ObjectEncoding represents the encoding to be used for the object's Value and Response fields.
Type Registry
type Registry[T any] struct {
// contains filtered or unexported fields
}
Registry provides a means of registering and looking up handlers for processing content types and for converting between content types.
Functions
func NewRegistry[T any]() *Registry[T]
NewRegistry returns a new instance of Registry.
Methods
func (c *Registry[T]) LookupConverters(from, to Type) (T, error)
LookupConverters returns the converter registered for converting the 'from' content type to the 'to' content type. The returned handlers are in the same order as that registered via RegisterConverter.
func (c *Registry[T]) LookupHandlers(ctype Type) ([]T, error)
LookupHandlers returns the handler registered for the given content type.
func (c *Registry[T]) RegisterConverters(from, to Type, converter T) error
RegisterConverters registers a lust of handlers for converting from one content type to another. The caller of LookupConverter must decide which converter to use.
func (c *Registry[T]) RegisterHandlers(ctype Type, handlers ...T) error
RegisterHandlers registers a handler for a given content type. The caller of LookupHandlers must decide which converter to use.
Type Type
type Type string
Type represents a content type specification in mime type format, major/minor[;parameter=value]. The major/minor part is required and the parameter is optional. The values used need not restricted to predefined mime types; ie. the values of major/minor;parameter=value are not restricted to those defined by the IANA.
Functions
func Clean(ctype Type) Type
Clean removes any spaces around the ; separator if present. That is, "text/plain ; charset=utf-8" becomes "text/plain;charset=utf-8".
func ReadObjectFile(path string) (Type, []byte, error)
ReadObjectFile will read the specified file and return the object type, encoding and the the contents of that file. The returned byte slice can be used to decode the object using its Decode method.
func TypeForPath(path string) Type
TypeForPath returns the Type for the given path. The Type is determined by obtaining the extension of the path and looking up the corresponding mime type.
Documentation
¶
Overview ¶
Package content provides support for working with different content types. In particular it defines a mean of specifying content types and a registry for matching content types against handlers for processing those types.
Index ¶
- Constants
- func Error(err error) error
- func ParseType(ctype Type) (string, error)
- func ParseTypeFull(ctype Type) (typ, par, value string, err error)
- type FS
- type Object
- func (o *Object[V, R]) Decode(data []byte) error
- func (o *Object[V, R]) Encode(valueEncoding, responseEncoding ObjectEncoding) ([]byte, error)
- func (o *Object[V, R]) Load(ctx context.Context, s ObjectStore, prefix, name string) (Type, error)
- func (o *Object[V, R]) Store(ctx context.Context, s ObjectStore, prefix, name string, ...) error
- type ObjectEncoding
- type ObjectStore
- type Registry
- type Type
Constants ¶
const ( InvalidObjectEncoding ObjectEncoding = iota GOBObjectEncoding = iota JSONObjectEncoding )
Variables ¶
This section is empty.
Functions ¶
func Error ¶
Error is an implementation of error that is registered with the gob package and marshals the error as the string value returned by its Error() method. It will return nil if the specified error is nil. Common usage is:
response.Err = content.Error(object.Err)
func ParseTypeFull ¶
ParseTypeFull parses a content type specification into its major/minor components and any parameter/value pairs. It returns an error if multiple / or ; characters are found.
Types ¶
type Object ¶
Object represents the result of an object/file download/crawl operation. As such it contains both the value that was downloaded and the result of the operation. The Value field represents the typed value of the result of the download or API operation. The Response field is the actual response for the download, API call and may include additional metadata such as object size, ownership etc. The content.Type is used by a reader to determine the type of the Value and Response fields and in this sense an object is a union.
Objects are intended to be serialized to/from storage with the reader needing to determine the types of the serialized Value and Response from the encoded data. The format chosen for the serialized data is intended to allow for dealing with the different sources of both Value and Response and allows for each to be encoded using a different encoding. For example, a response from a rest API may be only encodable as json. Similarly responses generated by native go code are likely most conveniently encoded as gob. The serialized format is:
type []byte valueEncoding uint8 responseEncoding uint8 value []byte response []byte
The gob format assumes that the decoder knows the type of the previously encoded binary data, including interface types. JSON cannot readily handle interface types.
When gob encoding is used care must be taken to ensure that any fields that are interface types are appropriately registered with the gob package. error is a common such case and the Error function can be used to replace the existing error with a wrapper that implements the error interface and is registered with the gob package. Canonical usage is:
response.Err = content.Error(object.Err)
func (*Object[V, R]) Encode ¶
func (o *Object[V, R]) Encode(valueEncoding, responseEncoding ObjectEncoding) ([]byte, error)
Encode encodes the object using the requested encodings.
func (*Object[V, R]) Load ¶
Load reads the serialized data from the supplied store at the specified prefix and name and deserializes it into the object. The caller is responsible for ensuring that the type of the stored object and the type of the object are identical.
func (*Object[V, R]) Store ¶
func (o *Object[V, R]) Store(ctx context.Context, s ObjectStore, prefix, name string, valueEncoding, responseEncoding ObjectEncoding) error
Store serializes the object and writes the resulting data the supplied store at the specified prefix and name.
type ObjectEncoding ¶
type ObjectEncoding int
ObjectEncoding represents the encoding to be used for the object's Value and Response fields.
type ObjectStore ¶
type ObjectStore interface {
Read(ctx context.Context, prefix, name string) (Type, []byte, error)
Write(ctx context.Context, prefix, name string, data []byte) error
}
ObjectStore represents the interface used by Objects to store and retrieve their data.
type Registry ¶
type Registry[T any] struct { // contains filtered or unexported fields }
Registry provides a means of registering and looking up handlers for processing content types and for converting between content types.
func NewRegistry ¶
NewRegistry returns a new instance of Registry.
func (*Registry[T]) LookupConverters ¶
LookupConverters returns the converter registered for converting the 'from' content type to the 'to' content type. The returned handlers are in the same order as that registered via RegisterConverter.
func (*Registry[T]) LookupHandlers ¶
LookupHandlers returns the handler registered for the given content type.
func (*Registry[T]) RegisterConverters ¶
RegisterConverters registers a lust of handlers for converting from one content type to another. The caller of LookupConverter must decide which converter to use.
func (*Registry[T]) RegisterHandlers ¶
RegisterHandlers registers a handler for a given content type. The caller of LookupHandlers must decide which converter to use.
type Type ¶
type Type string
Type represents a content type specification in mime type format, major/minor[;parameter=value]. The major/minor part is required and the parameter is optional. The values used need not restricted to predefined mime types; ie. the values of major/minor;parameter=value are not restricted to those defined by the IANA.
func Clean ¶
Clean removes any spaces around the ; separator if present. That is, "text/plain ; charset=utf-8" becomes "text/plain;charset=utf-8".
func TypeForPath ¶
TypeForPath returns the Type for the given path. The Type is determined by obtaining the extension of the path and looking up the corresponding mime type.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package processor provides support for processing different content types.
|
Package processor provides support for processing different content types. |