mydocx

package module
v0.1.10 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2024 License: MIT Imports: 9 Imported by: 1

README

GoDoc reference example Go Report Card

mydocx

A pure Go library to extract and transform text content within Word documents, with no external dependencies or licensing fees.

Features

  • Text Extraction: Extract text from multiple document locations:
    • Main document body
    • Headers and footers
    • Table cells
  • Content Organization: Retrieve text organized by paragraphs while preserving the original Word file
  • Text Transformation: Replace text content using customizable Replacer interfaces
    • Includes a built-in Go template-based Replacer
    • Support for custom Replacer implementations
  • MIT Licence

Working with Paragraphs

Replacer
  • Replacer takes the type of container and the original string as input, and returns a replacement string and a flag to request paragraph removal. This allows to handle differently the main document or the header/footer.
Limitations
  • New paragraphs cannot be created
  • Existing paragraphs can be programmatically discarded (see test files for examples)
Template Engine Constraints

The template engine has specific boundary limitations:

  • Template directives cannot span across paragraph boundaries
  • Example of invalid usage:
    Paragraph 1: {{if condition}}
    Paragraph 2: {{end}}
    

Technical Details

Run Management

Special consideration has been given to Word's internal text structure:

  • In a word document, text is internally split across multiple "runs"
  • To handle this complexity, the library:
    1. Collects text pieces from various runs
    2. Consolidates them into the first run
    3. Maintains empty subsequent runs for structural integrity
Formatting Behavior

Due to the run consolidation process:

  • The resulting paragraph will have uniform text formatting
  • The formatting is inherited from the style applied to the beginning of the paragraph

Usage Notes

  • When implementing custom text transformations, consider the single-format limitation
  • Refer to test files for comprehensive examples of paragraph manipulation
  • The library maintains document structure while allowing powerful text modifications

Documentation

Index

Constants

View Source
const COPYRIGHT = "(c) Xavier Gandillot 2024"
View Source
const NAME = "mydocx"
View Source
const NAMESPACE = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
View Source
const VERSION = "0.1.10"

Variables

View Source
var VERBOSE = false

if true, verbose information will be printed to stdout

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.

Types

type Replacer

type Replacer func(container string, original string) (replaced string, discard bool)

A replacer replaces a string with a 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. It returns a flag that can trigger the removal of the entire paragraph. You may design your own Replacer, without relying on the go template engine (or using another one).

func NewTplReplacer

func NewTplReplacer(content any) Replacer

Assume the source word document contains valid template in each paragraph (CAUTION template logic cannot extend beyond paragraph boundaries !) NewTplReplacer creates a replacer that will apply the provided content struct to the template in each paragraph. Container is ignored. By default, this Replacer will discard the entire paragraph if it was not initially empty but becomes empty when executing the template. If an error occurs during template conversion, the text of the error is returned, together with the original text that triggered the error.

func NewTplReplacerNoDiscard

func NewTplReplacerNoDiscard(content any) Replacer

same as NewTplReplacer but will never discard empty paragraphs.

Jump to

Keyboard shortcuts

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