README
¶
gopc
The gopc library is an implementation of the Open Packaging Conventions (OPC) for Go
WIP
Documentation
¶
Overview ¶
Package gopc 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, ...
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NormalizePartName ¶
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.
Types ¶
type CompressionOption ¶
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. CompressionNormal // CompressionMaximum is optimized for size. CompressionMaximum // CompressionFast is optimized for performance. CompressionFast // CompressionSuperFast is optimized for super performance. CompressionSuperFast )
type Package ¶
type Package struct {
// contains filtered or unexported fields
}
A Package is a container that holds a collection of parts. The purpose of the package is to aggregate constituent components of a document (or other type of content) into a single object. The package is also capable of storing relationships between parts. Defined in ISO/IEC 29500-2 §9.
type Part ¶
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.
}
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. The part properties will be validated before writing or reading from disk.
func (*Part) CreateRelationship ¶
func (p *Part) CreateRelationship(id, targetURI, relType string, targetMode TargetMode) *Relationship
CreateRelationship adds a new relationship to the Relationships slice. The ID can be an empty string, if so a unique ID will be generated. The input properties are not validated.
type Relationship ¶
type Relationship struct {
ID string
RelType string
TargetURI string
TargetMode TargetMode
// contains filtered or unexported fields
}
Relationship is used to express a relationship between a source and a target part. The only way to create a Relationship, is to call the Part.CreateRelationship() or Package.CreateRelationship(). A relationship is owned by a part or by the package itself. If the source part is deleted all the relationships it owns are also deleted. A target of the relationship need not be present. Defined in ISO/IEC 29500-2 §9.3.
type TargetMode ¶
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. ModeExternal )
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer implements a OPC file writer.
Example ¶
package main
import (
"bytes"
"log"
"github.com/qmuntal/gopc"
)
func main() {
// Create a buffer to write our archive to.
buf := new(bytes.Buffer)
// Create a new OPC archive.
w := gopc.NewWriter(buf)
// Create a new OPC part.
name := gopc.NormalizePartName("docs\\readme.txt")
part, err := w.Create(name, "text/plain")
if err != nil {
log.Fatal(err)
}
// Write content to the part.
_, err = part.Write([]byte("This archive contains some text files."))
if err != nil {
log.Fatal(err)
}
// Make sure to check the error on Close.
err = w.Close()
if err != nil {
log.Fatal(err)
}
}
Output:
func (*Writer) Close ¶
Close finishes writing the opc file. It does not close the underlying writer.
func (*Writer) Create ¶
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 ¶
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.
Source Files