opc: github.com/qmuntal/opc Index | Examples | Files

package opc

import "github.com/qmuntal/opc"

Package opc implements the ISO/IEC 29500-2, also known as the "Open Packaging Convention".

The Open Packaging specification describes an abstract model and physical format conventions for the use of XML, Unicode, ZIP, and other openly available technologies and specifications to organize the content and resources of a document within a package.

The OPC is the foundation technology for many new file formats: .docx, .pptx, .xlsx, .3mf, .dwfx, ...



Package Files

errors.go package.go part.go reader.go relationship.go writer.go zip_reader.go

func NormalizePartName Uses

func NormalizePartName(name string) string

NormalizePartName transforms the input name so it follows the constrains specified in the ISO/IEC 29500-2 §9.1.1:

part-URI = 1*( "/" segment )
segment = 1*( pchar )

pchar is defined in RFC 3986:

pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
pct-encoded = "%" HEXDIG HEXDIG
sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="

This method is recommended to be used before adding a new Part to a package to avoid errors. If, for whatever reason, the name can't be adapted to the specs, the return value will be the same as the original. Warning: This method can heavily modify the original if it differs a lot from the specs, which could led to duplicated part names.

func ResolveRelationship Uses

func ResolveRelationship(source string, rel string) string

ResolveRelationship returns the absolute URI (from the package root) of the part pointed by a relationship of a source part. This method should be used in places where we have a target relationship URI and we want to get the name of the part it targets with respect to the source part. The source can be a valid part URI, for part relationships, or "/", for package relationships.

type CompressionOption Uses

type CompressionOption int

CompressionOption is an enumerable for the different compression options.

const (
    // CompressionNone disables the compression.
    CompressionNone CompressionOption = iota - 1
    // CompressionNormal is optimized for a reasonable compromise between size and performance.
    // CompressionMaximum is optimized for size.
    // CompressionFast is optimized for performance.
    // CompressionSuperFast is optimized for super performance.

type CoreProperties Uses

type CoreProperties struct {
    PartName       string // Won't be writed to the package, only used to indicate the location of the CoreProperties part. If empty the default location is "/props/core.xml".
    Category       string // A categorization of the content of this package.
    ContentStatus  string // The status of the content.
    Created        string // Date of creation of the resource.
    Creator        string // An entity primarily responsible for making the content of the resource.
    Description    string // An explanation of the content of the resource.
    Identifier     string // An unambiguous reference to the resource within a given context.
    Keywords       string // A delimited set of keywords to support searching and indexing.
    Language       string // The language of the intellectual content of the resource.
    LastModifiedBy string // The user who performed the last modification.
    LastPrinted    string // The date and time of the last printing.
    Modified       string // Date on which the resource was changed.
    Revision       string // The revision number.
    Subject        string // The topic of the content of the resource.
    Title          string // The name given to the resource.
    Version        string // The version number.

CoreProperties enable users to get and set well-known and common sets of property metadata within packages.

type Error Uses

type Error struct {
    // contains filtered or unexported fields

An Error from this package is always associated to an OPC entity that is not conformant with the OPC specs.

func (*Error) Code Uses

func (e *Error) Code() int

Code of the error as described in the OPC specs. The first number is the top level topic and the second and third digits are the specific error code. The top level topics are described as follows: 1. Package Model requirements 2. Physical Packages requirements 3. ZIP Physical Mapping requirements 4. Core Properties requirements 5. Thumbnail requirements 6. Digital Signatures requirements 7. Pack URI requirements

func (*Error) Error Uses

func (e *Error) Error() string

func (*Error) PartName Uses

func (e *Error) PartName() string

PartName returns the name of the Part associated to the error.

func (*Error) RelationshipID Uses

func (e *Error) RelationshipID() string

RelationshipID returns the ID of the relationship associated to the error. If the error is not associated to a relationship, the value is empty.

type File Uses

type File struct {
    Size int
    // contains filtered or unexported fields

File is used to read a part from the OPC package.

func (*File) Open Uses

func (f *File) Open() (io.ReadCloser, error)

Open returns a ReadCloser that provides access to the File's contents. Multiple files may be read concurrently.

type Part Uses

type Part struct {
    Name          string          // The name of the part.
    ContentType   string          // The type of content stored in the part.
    Relationships []*Relationship // The relationships associated to the part. Can be modified until the Writer is closed.

A Part is a stream of bytes defined in ISO/IEC 29500-2 §9.1.. Parts are analogous to a file in a file system or to a resource on an HTTP server.

type ReadCloser Uses

type ReadCloser struct {
    // contains filtered or unexported fields

ReadCloser wrapps a Reader than can be closed.

func OpenReader Uses

func OpenReader(name string) (*ReadCloser, error)

OpenReader will open the OPC file specified by name and return a ReadCloser.

func (*ReadCloser) Close Uses

func (r *ReadCloser) Close() error

Close closes the OPC file, rendering it unusable for I/O.

type Reader Uses

type Reader struct {
    Files         []*File
    Relationships []*Relationship
    Properties    CoreProperties
    // contains filtered or unexported fields

Reader implements a OPC file reader.


r, err := opc.OpenReader("testdata/component.3mf")
if err != nil {
defer r.Close()

// Iterate through the files in the archive,
// printing some of their contents.
for _, f := range r.Files {
    fmt.Printf("Contents of %s with type %s :\n", f.Name, f.ContentType)
    rc, err := f.Open()
    if err != nil {
    _, err = io.CopyN(os.Stdout, rc, 68)
    if err != nil {

func NewReader Uses

func NewReader(r io.ReaderAt, size int64) (*Reader, error)

NewReader returns a new Reader reading an OPC file to r.

func (*Reader) SetDecompressor Uses

func (r *Reader) SetDecompressor(dcomp func(r io.Reader) io.ReadCloser)

SetDecompressor sets or overrides a custom decompressor for the DEFLATE.

type Relationship Uses

type Relationship struct {
    ID         string     // The relationship identifier which shall conform the xsd:ID naming restrictions and unique within the part.
    Type       string     // Defines the role of the relationship.
    TargetURI  string     // Holds a URI that points to a target resource. If expressed as a relative URI, it is resolved against the base URI of the Relationships source part.
    TargetMode TargetMode // Indicates whether or not the target describes a resource inside the package or outside the package.

Relationship is used to express a relationship between a source and a target part. If the ID is not specified a random string with 8 characters will be generated. If The TargetMode is not specified the default value is Internal. Defined in ISO/IEC 29500-2 §9.3.

type TargetMode Uses

type TargetMode int

TargetMode is an enumerable for the different target modes.

const (
    // ModeInternal when the target targetMode is Internal (default value).
    // Target points to a part within the package and target uri must be relative.
    ModeInternal TargetMode = iota
    // ModeExternal when the target targetMode is External.
    // Target points to an external resource and target uri can be relative or absolute.

type Writer Uses

type Writer struct {
    Properties    CoreProperties  // Package metadata. Can be modified until the Writer is closed.
    Relationships []*Relationship // The relationships associated to the package. Can be modified until the Writer is closed.
    // contains filtered or unexported fields

Writer implements a OPC file writer.


// Create a buffer to write our archive to.
buf := new(bytes.Buffer)

// Create a new OPC archive.
w := opc.NewWriter(buf)

// Create a new OPC part.
name := opc.NormalizePartName("docs\\readme.txt")
part, err := w.Create(name, "text/plain")
if err != nil {

// Write content to the part.
_, err = part.Write([]byte("This archive contains some text files."))
if err != nil {

// Make sure to check the error on Close.
if err := w.Close(); err != nil {

func NewWriter Uses

func NewWriter(w io.Writer) *Writer

NewWriter returns a new Writer writing an OPC file to w.

func (*Writer) Close Uses

func (w *Writer) Close() error

Close finishes writing the opc file. It does not close the underlying writer.

func (*Writer) Create Uses

func (w *Writer) Create(name, contentType string) (io.Writer, error)

Create adds a file to the OPC archive using the provided name and content type. The file contents will be compressed using the Deflate default method. The name shall be a valid part name, one can use NormalizePartName before calling Create to normalize it

This returns a Writer to which the file contents should be written. The file's contents must be written to the io.Writer before the next call to Create, CreatePart, or Close.

func (*Writer) CreatePart Uses

func (w *Writer) CreatePart(part *Part, compression CompressionOption) (io.Writer, error)

CreatePart adds a file to the OPC archive using the provided part. The name shall be a valid part name, one can use NormalizePartName before calling CreatePart to normalize it. Writer takes ownership of part and may mutate all its fields except the Relationships, which can be modified until the next call to Create, CreatePart or Close. The caller must not modify part after calling CreatePart, except the Relationships.

This returns a Writer to which the file contents should be written. The file's contents must be written to the io.Writer before the next call to Create, CreatePart, or Close.

func (*Writer) Flush Uses

func (w *Writer) Flush() error

Flush flushes any buffered data to the underlying writer. Part metadata, relationships, content types and other OPC related files won't be flushed. Calling Flush is not normally necessary; calling Close is sufficient. Useful to do simultaneous writing and reading.

Package opc imports 13 packages (graph) and is imported by 1 packages. Updated 2019-05-05. Refresh now. Tools for package owners.