mydocx

package module
v0.2.2 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2024 License: MIT Imports: 10 Imported by: 1

README ยถ

Go DOCX Text Processor

A powerful Go library for extracting and manipulating text in Microsoft Word (DOCX) files, with zero external dependencies. Transform your documents using Go templates or custom replacers while maintaining document structure.

GoDoc reference example Go Report Card

โœจ Features

  • Text extraction from DOCX files
  • Text modification using Go templates or custom replacers
  • Support for:
    • Main document body
    • Headers and footers
    • Tables and cells
    • Bullet points and numbered lists
  • Zero external dependencies
  • Efficient (single pass processing)
  • OOXML standard compliant
  • MIT License

๐Ÿš€ Installation

go get github.com/xavier268/mydocx

๐Ÿ“– Quick Start

Text Extraction
import "github.com/xavier268/mydocx"

func main() {
    // Extract text from all document parts (main body, headers, footers)
    content, err := mydocx.ExtractText("document.docx")
    if err != nil {
        log.Fatal(err)
    }

    // content is a map[string][]string where:
    // - key is the container name (e.g., "word/document.xml", "word/footer1.xml")
    // - value is a slice of strings, one for each paragraph
    for container, paragraphs := range content {
        fmt.Printf("Content from %s:\n", container)
        for _, para := range paragraphs {
            fmt.Println(para)
        }
    }
}
Using Go Templates
import "github.com/xavier268/mydocx"

func main() {
    // Define template data
    data := struct {
        Name    string
        Company string
        Date    string
    }{
        Name:    "John Doe",
        Company: "ACME Corp",
        Date:    time.Now().Format("2006-01-02"),
    }

    // Create a template-based replacer
    replacer := mydocx.NewTplReplacer(data)

    // Modify the document
    err := mydocx.ModifyText("template.docx", replacer, "output.docx")
    if err != nil {
        log.Fatal(err)
    }
}
Custom Replacer
// Define your custom replacer
func myReplacer(container, text string) []string {
    // container: "word/document.xml", "word/footer1.xml", etc.
    // text: original paragraph text
    // Return:
    // - empty slice to remove the paragraph
    // - slice with multiple strings to create multiple paragraphs
    // - slice with one string to replace paragraph content
    
    switch {
    case strings.Contains(text, "DELETE"):
        return []string{} // Remove paragraph
    case strings.Contains(text, "DUPLICATE"):
        return []string{text, text} // Duplicate paragraph
    default:
        return []string{strings.ToUpper(text)} // Convert to uppercase
    }
}

// Use your replacer
err := mydocx.ModifyText("input.docx", myReplacer, "output.docx")

๐Ÿ”ง Advanced Features

Template Functions
Built-in Functions

All go template functions are available. In addition, the following built-in functions are always available :

  • {{nl}} - Inserts a new paragraph
  • {{version}} - Returns version information
  • {{copyright}} - Returns copyright text
  • {{date}}- Returns the current date, as 2006-02-10
  • {{join}} - Expects an array of strings and a delimiter string, returns a single concatenated string with the delimiter (see go function strings.Join)
  • {{keepEmpty}} - From this point, will never remove a paragraph that becomes empty after modification.
  • {{removeEmpty}}- From this point, non empty paragraphs tat become empty after Replacer is applied are removed. This is the default.
Register Custom Functions
// Register a custom function
mydocx.RegisterTplFunction("upper", strings.ToUpper)

// Use in template
// {{upper .Name}}
Template Guidelines
  1. Each paragraph is an independent template

  2. Templates cannot span across paragraphs

  3. Valid example:

    Hello {{.Name}}!
    Your order #{{.OrderID}} has been processed.
    
  4. Invalid example:

    Hello {{if .Premium}}
    Premium customer {{.Name}}!
    {{else}}
    Valued customer {{.Name}}!
    {{end}}
    

๐Ÿ”„ Paragraph Management

With Custom Replacer

The Replacer function controls paragraph creation and removal through its return value:

type Replacer func(container string, text string) []string
  1. Remove Paragraph

    // Return empty slice to remove the paragraph (unless {{keepEmpty}} was called earlier)
    func myReplacer(container, text string) []string {
        if strings.Contains(text, "DELETE") {
            return []string{} // Paragraph will be removed
        }
        return []string{text}
    }
    
  2. Create Multiple Paragraphs

    // Return multiple strings to create multiple paragraphs
    func myReplacer(container, text string) []string {
        if strings.Contains(text, "DUPLICATE") {
            // Creates three identical paragraphs with the same formatting
            return []string{text, text, text}
        }
        return []string{text}
    }
    

Each new paragraph inherits the formatting of the original paragraph.

With Go Templates

When using the template-based replacer (NewTplReplacer), paragraph management is controlled by newlines in the template output:

  1. Remove Paragraph

    {{if .ShouldDelete}}{{else}}Original content{{end}}
    

    If .ShouldDelete is true, the empty output will remove the paragraph (unless {{keepEmpty}} was called before).

  2. Create Multiple Paragraphs

    {{.Title}}
    Items:
    {{range .Items}} - {{.}}{{nl}}{{end}}
    Contact: {{.Contact}}
    

The {{nl}} function inserts a newline, and the template output is split on newlines to create new paragraphs. Each resulting paragraph inherits the formatting of the original paragraph. Notice how {{range}} ... {{end}} fits within a single source paragraph but will create multiple paragraphs !

Paragraph Creation Rules
  1. Initially empty paragraphs

    • Initially empty paragraphs are always left unchanged
  2. Empty Result

    • If the Replacer returns an empty slice โ†’ paragraph is removed
    • If a template produces empty output โ†’ paragraph is removed
      Note : this is the default, it can be changed with {{keepEmpty}}
  3. Multiple Paragraphs

    • Custom Replacer: Each string in the returned slice becomes a new paragraph
    • Template: Output is split on newlines (\n), each line becomes a new paragraph
    • All new paragraphs inherit formatting from the original paragraph
  4. Examples with Templates

    // Template in document
    Dear {{.Name}},
    {{if .Premium}}Thank you for being a premium member!{{end}}
    Your balance is ${{.Balance}}.
    

    This template could produce:

    Dear John Doe,
    Thank you for being a premium member!
    Your balance is $100.
    

    Or (if not premium):

    Dear John Doe,
    Your balance is $100.
    

โš™๏ธ Technical Details

Word Run Management

Microsoft Word splits text into "runs" - segments sharing the same formatting. This creates challenges for text replacement:

Example: "Hello {{.Name}}!" might be split into:
Run 1: "Hello "
Run 2: "{{.Name"
Run 3: "}}!"

Our solution:

  1. Consolidates all runs in a paragraph into the first run
  2. Processes the complete text with a Replacer
  3. Creates new paragraphs for each line in the result

โš ๏ธ Important: Due to this approach, the entire paragraph will inherit the formatting from its beginning.

Tables and Lists
  • Tables and lists are fully supported
  • Each cell must contain at least one paragraph (even if empty)
  • Word will show an error when opening files with empty cells but can recover

๐Ÿšจ Limitations

  1. Formatting

    • Paragraph formatting is unified based on the first run
    • In-paragraph formatting variations are lost
  2. Template Boundaries

    • Templates must be contained within a single paragraph
    • Cross-paragraph templates are not supported
  3. Table Cells

    • Avoid creating completely empty cells
    • Always include at least one (empty) paragraph in cells

๐Ÿ“š Resources

๐Ÿค Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

๐Ÿ“ License

MIT License - See LICENSE file for details

Documentation ยถ

Index ยถ

Constants ยถ

View Source
const (
	AUTHOR      = "Xavier Gandillot"
	DESCRIPTION = "A simple library to modify Microsoft Word .docx documents with go templates"
	NAME        = "mydocx"
	VERSION     = "0.2.2"
	COPYRIGHT   = "(c) Xavier Gandillot 2024"
	NAMESPACE   = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
)

Variables ยถ

View Source
var (
	// if true, verbose information will be printed to stdout
	VERBOSE = false
	// If set to true, paragraphs that become empty after replacement are removed (initially empty paragraphs are never removed).
	// If false, paragraphs that bcome empty are kept.
	// Use the functions {{removeEmpty}}  or {{keepEmpty}} in the source word document to set this value.
	// You may also set this variable directly from code.
	// Default is true.
	REMOVE_EMPTY_PARAGRAPH bool = true
)

Functions ยถ

func ExtractText ยถ

func ExtractText(sourceFilePath string) (map[string][]string, error)

Extract text content from docx file for external processing. Returns a map from the container name (eg : word/footer1.xml) to a list of text contained in its paragraphs.

func ModifyText ยถ

func ModifyText(sourceFilePath string, replace Replacer, targetFilePath string) error

All text from the sourceFile is modified by applying the replace function to it. Before applying the function, the whole paragraph is collected as a single text, even if split on multiple runs. Replace function is called paragraph by paragraph. No special assumption is made for empty paragraph. If the replace function is nil, text will be copied unmodified (but paragraph format WILL be extended from the start of paragraph, removing internal paragraph formatting !). If the targetFile name is empty, the sourceFile will be used, modification will be done in place.

func RegisterTplFunction ยถ added in v0.2.1

func RegisterTplFunction(name string, function any)

Register a new function that will be available when parsing templates. Empty names or nil functions are ignored. Each function must have either a single return value, or two return values of which the second has type error. In that case, if the second (error) return value evaluates to non-nil during execution, execution terminates and Execute returns that error.

Types ยถ

type Replacer ยถ

type Replacer func(container string, original string) (replaced []string)

A replacer replaces a string with a list modified string. It is provide the container name where replacement will occur ("word/document.xm", "word/footer1.xml", ...). Only documents, headers and footers will be submitted. If the returned slice is empty, the paragraph is removed (unless the REMOVE_EMPTY_PRAGRAPHS flag was unset)) If the returned slice contains more than 1 element, new paragraphs are added, duplicated from the original paragraph. The strings will be xml-escaped later, Replacer should not escape its results.

func NewTplReplacer ยถ

func NewTplReplacer(content any) Replacer

Assume the source word document contains valid go template in each paragraph NewTplReplacer creates a replacer that will apply the provided content struct to the template in each paragraph. Container is ignored. The Replacer will behave as follows : * If initial paragraph was empty, it is left un changed. * If not empty, template is executed. * If the template execution result is empty, the paragraph is discarded. * If the template execution result is not empty, it is split around \n into lines and each line is added as a separate paragraph. (you may use the function {{nl}} to gererate new lines) * If an error occurs during template execution, an error message is added as the last paragraph of the result.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL