xmp

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 29, 2024 License: GPL-3.0 Imports: 15 Imported by: 2

README

Extensible Metadata Platform in Go

Go Reference OpenSSF Scorecard

This package provides a Go API for reading and writing XMP metadata files. It is written in pure Go and does not depend on any external libraries.

Copyright (C) 2024 Jochen Voss

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Documentation

Overview

Package xmp reads and writes Extensible Metadata Platform (XMP) data.

XMP Packets

The main type in this package is the Packet type, which represents an XMP packet. XMP packets can be read from file using the Read function and written to file using the Packet.Write method.

Properties

An XMP packet stores a set of properties. Each property is identified by a namespace and a name. The value of a property has type which implements Value, the specific type depends on the property namespace and name. Use GetValue to read a property from an XMP packet and Packet.Set to set a property in an XMP packet.

The package provides the following types for XMP values:

  • Text represents a generic text string.
  • AgentName represents the name of some document creator software.
  • AlternativeArray is an ordered array of values.
  • Date represents a date and time.
  • GUID represents a globally unique identifier.
  • Locale represents a language code.
  • Localized represents a localized text value
  • MimeType represents the media type of a file.
  • OptionalBool represents a value which can be true, false or unset.
  • OrderedArray is an ordered array of values.
  • ProperName represents a proper name.
  • Real represents a floating-point number.
  • RenditionClass states the form or intended usage of a resource (e.g. "draft" or "low-res").
  • ResourceRef represents a reference to an external resource.
  • URL is a URL or URI.
  • UnorderedArray is an unordered array of values.

Additional types can be defined by implementing the Value interface.

Every XMP value can be annotated with a list of qualifiers, for example to specify the language of a text value. Qualifiers are identified by a namespace and a name. The value of a qualifier is again a Value.

Models

Models can be used get or set several properties from a namespace at once. Use Packet.Get to read values from an XMP packet into a model, and Packet.Set to store values from a model into an XMP packet. The following models are defined in this library:

  • DublinCore represents the Dublin Core namespace.
  • MediaManagement represents the XMP Media Management namespace.
  • RightsManagement represents the XMP RightsManagement Management namespace.
  • Basic represents the XMP basic namespace.

Additional models can be defined by defining a struct with fields of type Value and using the Go struct tags to specify the XMP property name where this is different from the field name. See DublinCore, Namespace and Prefix for examples.

Index

Constants

This section is empty.

Variables

View Source 
var ErrInvalid = errors.New("invalid XMP data")

ErrInvalid is returned by GetValue when XMP data is present in the XML file, but the data does not have the expected structure.

View Source 
var ErrNotFound = errors.New("property not found")

ErrNotFound is returned by GetValue when a requested property is not present in the packet.

Functions

func GetValue 

func GetValue[E Value](p *Packet, namespace, propertyName string) (E, error)

GetValue retrieves the value of the given property from the packet.

In case the value is not found, ErrNotFound is returned. If the value exists but has the wrong format, ErrInvalid is returned.

Note: This should be a method of the Packet type, but at the moment Go does not allow methods with type parameters.

Types

type AgentName 

type AgentName struct {
	V string
	Q
}

AgentName represents the name of some document creator software.

The recommended format of this string is 

Organization Software_name Version (token;token;...)

where the fields have the following meanings:

  • Organization: the company or organization providing the software, without spaces.
  • Software_name: The full name of the software, spaces allowed.
  • Version: The version of the software, without spaces.
  • tokens: additional information, e.g. OS version

func NewAgentName added in v0.2.0 

func NewAgentName(v string, qualifiers ...Qualifier) AgentName

NewAgentName creates a new XMP AgentName object.

func (AgentName) DecodeAnother 

func (AgentName) DecodeAnother(val Raw) (Value, error)

DecodeAnother implements the Value interface.

func (AgentName) EncodeXMP added in v0.3.0 

func (a AgentName) EncodeXMP(*Packet) Raw

EncodeXMP implements the Value interface.

func (AgentName) IsZero 

func (a AgentName) IsZero() bool

IsZero implements the Value interface.

func (AgentName) String added in v0.2.0 

func (a AgentName) String() string

type AlternativeArray 

type AlternativeArray[E Value] struct {
	V []E
	Q
}

AlternativeArray is an ordered array of values. All values in the array have the same type E.

func (AlternativeArray[E]) DecodeAnother 

func (AlternativeArray[E]) DecodeAnother(val Raw) (Value, error)

DecodeAnother implements the Value interface.

func (AlternativeArray[E]) EncodeXMP added in v0.3.0 

func (a AlternativeArray[E]) EncodeXMP(p *Packet) Raw

EncodeXMP implements the Value interface.

func (AlternativeArray[E]) IsZero 

func (a AlternativeArray[E]) IsZero() bool

IsZero implements the Value interface.

type Basic added in v0.3.0 

type Basic struct {

	// CreateDate is the date and time the resource was originally created.
	CreateDate Date

	// CreatorTool is the name of the first known tool used to create the
	// resource.
	CreatorTool AgentName

	// Identifier is an unambiguous reference to the resource within a given
	// context.  An array item may be qualified with xmpidq:Scheme to specify
	// the identification system for that item.
	Identifier UnorderedArray[Text]

	// Label is a word or short phrase that identifies a resource within a
	// local context.
	Label Text

	// MetadataDate is the date and time that any metadata for this resource was
	// last modified.
	MetadataDate Date

	// ModifyDate is the date and time the resource was last modified.
	ModifyDate Date

	// Rating is a user-assigned rating for this resource.
	//
	// The value must be -1 (rejected), 0 (unrated) or a rating in the range
	// (0, 5].
	Rating Real
	// contains filtered or unexported fields
}

Basic represents the XMP basic namespace.

See section 8.4 of ISO 16684-1:2011 for details.

type Date 

type Date struct {
	V time.Time

	// NumOmitted can be used to reduce the precision of the date
	// when serializing it to XMP.  The value is a number between 0 and 5:
	// 1=omit nano, 2=omit sec, 3=omit time, 4=omit day, 5=month.
	NumOmitted int

	Q
}

Date represents a date and time.

func NewDate 

func NewDate(t time.Time, qualifiers ...Qualifier) Date

NewDate creates a new XMP date value.

func (Date) DecodeAnother 

func (Date) DecodeAnother(val Raw) (Value, error)

DecodeAnother implements the Value interface.

func (Date) EncodeXMP added in v0.3.0 

func (d Date) EncodeXMP(*Packet) Raw

EncodeXMP implements the Value interface.

func (Date) IsZero 

func (d Date) IsZero() bool

IsZero implements the Value interface.

type DublinCore 

type DublinCore struct {

	// Contributor is a list of contributors to the resource.
	// This should not include names listed in the Creator field.
	Contributor UnorderedArray[ProperName] `xmp:"contributor"`

	// Coverage is the extent or scope of the resource.
	Coverage Text `xmp:"coverage"`

	// Creator is a list of the creators of the resource.  Entities should be
	// listed in order of decreasing precedence, if such order is significant.
	Creator OrderedArray[ProperName] `xmp:"creator"`

	// Date is a point or period of time associated with an event in the life
	// cycle of the resource.
	Date OrderedArray[Date] `xmp:"date"`

	// Description is a textual description of the content of the resource.
	Description Localized `xmp:"description"`

	// Format is the media type of the resource.
	Format MimeType `xmp:"format"`

	// Identifier is an unambiguous reference for the resource.
	Identifier Text `xmp:"identifier"`

	// Language is a list of languages used in the content of the resource.
	Language UnorderedArray[Locale] `xmp:"language"`

	// Publisher is a list of publishers of the resource.
	Publisher UnorderedArray[ProperName] `xmp:"publisher"`

	// Relation is a list of related resources.
	Relation UnorderedArray[Text] `xmp:"relation"`

	// Rights is an informal rights statement for the resource.
	Rights Localized `xmp:"rights"`

	// Source is a reference to a resource from which the present resource is
	// derived, either in whole or in part.
	Source Text `xmp:"source"`

	// Subject is a list of descriptive phrases or keywords that specify the
	// content of the resource.
	Subject UnorderedArray[Text] `xmp:"subject"`

	// Title is the title or name of the resource.
	Title Localized `xmp:"title"`

	// Type is the nature or genre of the resource.
	Type UnorderedArray[Text] `xmp:"type"`
	// contains filtered or unexported fields
}

DublinCore represents the properties in the Dublin Core namespace.

See section 8.4 of ISO 16684-1:2011.

type GUID 

type GUID struct {
	V string
	Q
}

GUID represents a globally unique identifier.

func (GUID) DecodeAnother 

func (GUID) DecodeAnother(val Raw) (Value, error)

DecodeAnother implements the Value interface.

func (GUID) EncodeXMP added in v0.3.0 

func (t GUID) EncodeXMP(*Packet) Raw

EncodeXMP implements the Value interface.

func (GUID) IsZero 

func (t GUID) IsZero() bool

IsZero implements the Value interface.

type Locale 

type Locale struct {
	V language.Tag
	Q
}

Locale represents a language code.

func NewLocale 

func NewLocale(tag language.Tag, qualifiers ...Qualifier) Locale

NewLocale creates a new XMP locale value.

func (Locale) DecodeAnother 

func (Locale) DecodeAnother(val Raw) (Value, error)

DecodeAnother implements the Value interface.

func (Locale) EncodeXMP added in v0.3.0 

func (l Locale) EncodeXMP(*Packet) Raw

EncodeXMP implements the Value interface.

func (Locale) IsZero 

func (l Locale) IsZero() bool

IsZero implements the Value interface.

func (Locale) String 

func (l Locale) String() string

type Localized 

type Localized struct {
	V map[language.Tag]Text

	// Default (optional) is the default value for the property.
	// If Value is non-empty, the text contents of Default must coincide with
	// the text contents of one of the values in the map.
	Default Text

	Q
}

Localized represents a localized text value. This is a map from language tags to strings. This is implemented as an XMP "Language Alternative".

func (Localized) DecodeAnother 

func (Localized) DecodeAnother(val Raw) (Value, error)

DecodeAnother implements the Value interface.

func (Localized) EncodeXMP added in v0.3.0 

func (l Localized) EncodeXMP(*Packet) Raw

EncodeXMP implements the Value interface.

func (Localized) IsZero 

func (l Localized) IsZero() bool

IsZero implements the Value interface.

func (*Localized) Set 

func (l *Localized) Set(lang language.Tag, txt string, qualifiers ...Qualifier)

Set sets the text value for a specific language.

type MediaManagement 

type MediaManagement struct {

	// DerivedFrom is a reference to a resource from which the present resource
	// is derived, either in whole or in part.  Missing fields are assumed to
	// be unchanged from the source.
	DerivedFrom ResourceRef

	// DocumentID is a unique identifier for the document.
	DocumentID Text

	// InstanceID is a unique identifier for the document instance.
	InstanceID Text

	// OriginalDocumentID is a unique identifier for the original document.
	OriginalDocumentID Text

	// RenditionClass is a rendition class name for this resource.
	RenditionClass Text

	// RenditionParams can be used to provide additional rendition parameters
	RenditionParams Text
	// contains filtered or unexported fields
}

MediaManagement represents the XMP Media Management namespace.

See section 8.6 of ISO 16684-1:2011 for details.

type MimeType 

type MimeType struct {
	V     string
	Param map[string]string
	Q
}

MimeType represents the media type of a file. The fields V and Param correspond to the values returned by mime.ParseMediaType.

func (MimeType) DecodeAnother 

func (m MimeType) DecodeAnother(val Raw) (Value, error)

DecodeAnother implements the Value interface.

func (MimeType) EncodeXMP added in v0.3.0 

func (m MimeType) EncodeXMP(*Packet) Raw

EncodeXMP implements the Value interface.

func (MimeType) IsZero 

func (m MimeType) IsZero() bool

IsZero implements the Value interface.

func (MimeType) String 

func (m MimeType) String() string

type Namespace 

type Namespace struct{}

Namespace must be used in XMP namespace structs to specify the namespace URI. The namespace URI is specified using a struct tag on a field of type Namespace. For example: 

type MyNamespace struct {
    _ Namespace `xmp:"http://example.com/ns/my/namespace/"`
    ...
}

type OptionalBool 

type OptionalBool struct {
	V int // 0 = unset, 1 = false, 2 = true
	Q
}

OptionalBool represents an optional boolean value. The possible values are "True", "False", and unset.

func (OptionalBool) DecodeAnother 

func (OptionalBool) DecodeAnother(val Raw) (Value, error)

DecodeAnother implements the Value interface.

func (OptionalBool) EncodeXMP added in v0.3.0 

func (o OptionalBool) EncodeXMP(*Packet) Raw

EncodeXMP implements the Value interface.

func (OptionalBool) IsFalse 

func (o OptionalBool) IsFalse() bool

IsFalse returns true if the value is set to false. Note that this is different from the value being unset.

func (OptionalBool) IsTrue 

func (o OptionalBool) IsTrue() bool

IsTrue returns true if the value is set to true.

func (OptionalBool) IsZero 

func (o OptionalBool) IsZero() bool

IsZero implements the Value interface.

func (OptionalBool) String 

func (o OptionalBool) String() string

type OrderedArray 

type OrderedArray[E Value] struct {
	V []E
	Q
}

OrderedArray is an ordered array of values. All elements of the array have the same type, E.

func (*OrderedArray[E]) Append 

func (o *OrderedArray[E]) Append(v E)

Append adds a new value to the array.

func (OrderedArray[E]) DecodeAnother 

func (OrderedArray[E]) DecodeAnother(val Raw) (Value, error)

DecodeAnother implements the Value interface.

func (OrderedArray[E]) EncodeXMP added in v0.3.0 

func (o OrderedArray[E]) EncodeXMP(p *Packet) Raw

EncodeXMP implements the Value interface.

func (OrderedArray[E]) IsZero 

func (o OrderedArray[E]) IsZero() bool

IsZero implements the Value interface.

type Packet 

type Packet struct {
	// Properties represents the properties stored in the XMP packet.
	// The key consists of the namespace and the property name,
	// the value is the low-level representation of the property.
	// Use the GetValue function to access values with known types.
	Properties map[xml.Name]Raw

	// About (optional) is the URL of the resource described by the XMP packet.
	About *url.URL
	// contains filtered or unexported fields
}

Packet represents an XMP packet.

func NewPacket 

func NewPacket() *Packet

NewPacket allocates a new, empty XMP packet.

func Read 

func Read(r io.Reader) (*Packet, error)

Read reads an XMP packet from a reader.

func (*Packet) ClearValue added in v0.2.0 

func (p *Packet) ClearValue(namespace, propertyName string)

ClearValue removes the given property from the packet.

func (*Packet) Get 

func (p *Packet) Get(dst any)

Get fills the fields in a namespace struct using data from the packet.

The argument dst must be a pointer to an XMP namespace struct or the function will panic.

func (*Packet) RegisterPrefix 

func (p *Packet) RegisterPrefix(ns, prefix string)

RegisterPrefix registers a namespace prefix.

func (*Packet) Set 

func (p *Packet) Set(models ...any) error

Set sets XMP properties from the fields of a namespace struct.

func (*Packet) SetValue 

func (p *Packet) SetValue(namespace, propertyName string, value Value)

SetValue stores the given value in the packet.

func (*Packet) Write 

func (p *Packet) Write(w io.Writer, opt *PacketOptions) error

Write writes the XMP packet to the given writer.

type PacketOptions 

type PacketOptions struct {
	Pretty bool
}

PacketOptions can be used to control the output format of the Packet.Write method.

type Prefix 

type Prefix struct{}

Prefix can be used in XMP namespace structs to optionally specify the preferred XML prefix for the namespace. The prefix is specified using a struct tag on a field of type Prefix. For example: 

type MyNamespace struct {
    _ Namespace `xmp:"http://example.com/ns/my/namespace/"`
    _ Prefix    `xmp:"myns"`
    ...
}

If no prefix is specified (or if there is a prefix name clash), a prefix is automatically chosen.

type ProperName 

type ProperName struct {
	V string
	Q
}

ProperName represents a proper name.

func NewProperName added in v0.2.0 

func NewProperName(v string, qualifiers ...Qualifier) ProperName

NewProperName creates a new XMP proper name value.

func (ProperName) DecodeAnother 

func (ProperName) DecodeAnother(val Raw) (Value, error)

DecodeAnother implements the Value interface.

func (ProperName) EncodeXMP added in v0.3.0 

func (p ProperName) EncodeXMP(*Packet) Raw

EncodeXMP implements the Value interface.

func (ProperName) IsZero 

func (p ProperName) IsZero() bool

IsZero implements the Value interface.

func (ProperName) String 

func (p ProperName) String() string

type Q 

type Q []Qualifier

Q represents the qualifiers of an XMP value.

func (Q) StripLanguage 

func (q Q) StripLanguage() (language.Tag, Q)

StripLanguage returns the language qualifier of a Q and a new Q with the language qualifier removed. If no language qualifier is present, language.Und is returned.

func (Q) WithLanguage 

func (q Q) WithLanguage(l language.Tag) Q

WithLanguage returns a new Q with the given language qualifier. Any pre-existing language qualifier is removed.

type Qualifier 

type Qualifier struct {
	Name  xml.Name
	Value Raw
}

A Qualifier can be used to attach additional information to the value of an XMP property.

func Language 

func Language(l language.Tag) Qualifier

Language returns a qualifier which specifies the language of a value.

type Raw 

type Raw interface {
	// contains filtered or unexported methods
}

Raw is one of Text, URL, RawStruct, or RawArray. These are the types which can be used to represent XMP values inside the XLS representation of an XMP packet. The methods of the Value interface allow to convert a value to and from a Raw value.

type RawArray 

type RawArray struct {
	Value []Raw
	Kind  RawArrayType
	Q
}

RawArray is an XMP array. This can be an unordered array, an ordered array, or an alternative array, depending on the value of the Type field.

type RawArrayType 

type RawArrayType int

RawArrayType represents the type of an XMP array (unordered, ordered, or alternative). 

const (
	Unordered RawArrayType = iota + 1
	Ordered
	Alternative
)

These are the possible array types in XMP.

type RawStruct 

type RawStruct struct {
	Value map[xml.Name]Raw
	Q
}

RawStruct is an XMP structure.

type Real 

type Real struct {
	V float64
	Q
}

Real represents a floating-point number.

func (Real) DecodeAnother 

func (Real) DecodeAnother(val Raw) (Value, error)

DecodeAnother implements the Value interface.

func (Real) EncodeXMP added in v0.3.0 

func (r Real) EncodeXMP(*Packet) Raw

EncodeXMP implements the Value interface.

func (Real) IsZero 

func (r Real) IsZero() bool

IsZero implements the Value interface.

type RenditionClass added in v0.2.0 

type RenditionClass struct {
	V string
	Q
}

RenditionClass states the form or intended usage of a resource. This is a series of colon-separated values, the first of which names the basic usage of the rendition and the rest are parameters.

Defined values:

  • "default": the default rendition of the resource (no parameters).
  • "draft": a draft version of the resource.
  • "low-res": a low-resolution version of the resource.
  • "proof": a review proof.
  • "screen": a screen-optimized version of the resource.
  • "thumbnail": a thumbnail image.

Example: "thumbnail:gif:8x8:bw"

func (RenditionClass) DecodeAnother added in v0.2.0 

func (RenditionClass) DecodeAnother(val Raw) (Value, error)

DecodeAnother implements the Value interface.

func (RenditionClass) EncodeXMP added in v0.3.0 

func (t RenditionClass) EncodeXMP(*Packet) Raw

EncodeXMP implements the Value interface.

func (RenditionClass) IsZero added in v0.2.0 

func (t RenditionClass) IsZero() bool

IsZero implements the Value interface.

type ResourceRef 

type ResourceRef struct {
	// DocumentID is the document ID of the referenced resource,
	// as found in the xmpMM:DocumentID field.
	DocumentID GUID

	// FilePath is the file path or URL of the referenced resource.
	FilePath URL

	// InstanceID is the instance ID of the referenced resource,
	// as found in the xmpMM:InstanceID field.
	InstanceID GUID

	RenditionClass RenditionClass

	RenditionParams Text

	Q
}

ResourceRef represents a reference to an external resource.

func (*ResourceRef) GetXMP 

func (r *ResourceRef) GetXMP(p *Packet) Raw

GetXMP implements the Value interface.

func (*ResourceRef) IsZero 

func (r *ResourceRef) IsZero() bool

IsZero implements the Value interface.

type RightsManagement added in v0.2.0 

type RightsManagement struct {

	// Certificate is a reference to a digital certificate that can be used to
	// verify the rights management information.
	//
	// For historical reasons, this field has type Text instead of URL.
	Certificate Text

	// Marked is true if the document has been marked as copyrighted.
	Marked OptionalBool

	// Owner is a list of legal owners of the resource.
	Owner UnorderedArray[ProperName]

	// UsageTerms is a statement that specifies the terms and conditions under
	// which the document can be used.
	UsageTerms Localized

	// WebStatement is a URL that can be used to access a rights management
	// information statement.
	//
	// For historical reasons, this field has type Text instead of URL.
	WebStatement Text
	// contains filtered or unexported fields
}

RightsManagement represents the XMP RightsManagement Management namespace.

See section 8.5 of ISO 16684-1:2011 for details.

type Text 

type Text struct {
	V string
	Q
}

Text is a simple text (i.e. non-URI) value.

Text implements both the Value and Raw interfaces.

func NewText 

func NewText(s string, qualifiers ...Qualifier) Text

NewText creates a new XMP text value.

func (Text) DecodeAnother 

func (Text) DecodeAnother(val Raw) (Value, error)

DecodeAnother implements the Value interface.

func (Text) EncodeXMP added in v0.3.0 

func (t Text) EncodeXMP(*Packet) Raw

EncodeXMP implements the Value interface.

func (Text) IsZero 

func (t Text) IsZero() bool

IsZero implements the Value interface.

func (Text) String 

func (t Text) String() string

type URL 

type URL struct {
	V *url.URL
	Q
}

URL is a URL or URI.

URL implements both the Value and Raw interfaces.

func NewURL 

func NewURL(u *url.URL, qualifiers ...Qualifier) URL

NewURL creates a new XMP URL value.

func (URL) DecodeAnother 

func (URL) DecodeAnother(val Raw) (Value, error)

DecodeAnother implements the Value interface.

func (URL) EncodeXMP added in v0.3.0 

func (u URL) EncodeXMP(*Packet) Raw

EncodeXMP implements the Value interface.

func (URL) IsZero 

func (u URL) IsZero() bool

IsZero implements the Value interface.

func (URL) String 

func (u URL) String() string

type UnorderedArray 

type UnorderedArray[E Value] struct {
	V []E
	Q
}

UnorderedArray is an unordered array of values. All elements of the array have the same type, E.

func (*UnorderedArray[E]) Append 

func (u *UnorderedArray[E]) Append(v E)

func (UnorderedArray[E]) DecodeAnother 

func (UnorderedArray[E]) DecodeAnother(val Raw) (Value, error)

DecodeAnother implements the Value interface.

func (UnorderedArray[E]) EncodeXMP added in v0.3.0 

func (u UnorderedArray[E]) EncodeXMP(p *Packet) Raw

EncodeXMP implements the Value interface.

func (UnorderedArray[E]) IsZero 

func (u UnorderedArray[E]) IsZero() bool

IsZero implements the Value interface.

type Value 

type Value interface {
	// IsZero returns true if the value is the zero value of its type, and
	// if the value has no qualifiers.
	IsZero() bool

	// EncodeXMP returns the low-lecel XMP representation of a value.
	EncodeXMP(*Packet) Raw

	// DecodeAnother converts a low-level XMP representation into a [Value].
	// The resulting Value must have the same concrete type as the receiver.
	// The receiver is not used otherwise.  If the input is not a valid
	// representation of the concrete type, the error ErrInvalid is returned.
	DecodeAnother(Raw) (Value, error)
}

A Value represents a high-level data type for XMP values. The methods of this interface are used to serialize and deserialize values.

Source Files

View all Source files

Directories

Path Synopsis
Package jvxml implements an alternative encoder for XML data.
 Package jvxml implements an alternative encoder for XML data.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.