Haskell ODT Writer

Overview

Haskell ODT Writer provides an interface in Haskell for reading and writing Open Document Format .odt files.

The program is set up to enable the user to compose their own .odt files using Haskell syntax.

Installing and building

So far I have only tested this process on Linux (Ubuntu), not Windows or MacOS. You can install with Stack. I installed Haskell and Stack with GHCup.

Build and test environment

Haskell ODT Writer has been built and tested on GHC 9.4.7 using Stack 2.11.1.

1. Clone and cd into the repo

$ git clone https://github.com/rsdc2/haskell-odt
$ cd haskell-odt

2. Build

$ stack build

3. Run the tests

$ stack test

4. Run the Main app

$ stack run

Composing OpenDocument Text documents

An OpenDocument Text file is a Zip archive comprising a directory structure of .xml files. From a writer's perspective the two most important files are:

• content.xml which carries the text content of the file
• styles.xml which carries the style information

These are the two files that haskell-odt-writer allows the user to write to.

In the simplest case, you want simply to write some text content into a file that can be read e.g. by LibreOffice / OpenOffice Writer. In Main.hs you will find a function with the following signature:

content :: Writer ODT ()

This functions provides the content of your document. There are two primary functions to be aware of:

• writeTextSpan
• writeNewPara
• writePara

writeTextSpan :: TextStyle -> T.Text -> Writer ODT ()

This function takes a TextStyle and a section of text, applies this style to the text, and appends it to the document. For example, the following will write out "Hello world." to the document without any formatting:

content :: Writer ODT ()
content = do
    writeTextSpan normal "Hello world."

If you want to apply some formatting, you can use a TextStyle other than normal, e.g.:

content :: Writer ODT ()
content = do
    writeTextSpan italic "Hello world."

This will write "Hello world." to the document, this time in italics.

To append further text to the document, simply add further lines to the function, e.g.:

content :: Writer ODT ()
content = do
    writeTextSpan italic "Hello world. "
    writeTextSpan bold "This is bold text."

In this case, the document will comprise a single line: "Hello world. This is bold text."

writeNewPara :: Writer ODT ()

If you want to start a new paragraph, use the writeNewPara function, which takes no arguments. You can then follow this with further TextSpans:

content :: Writer ODT ()
content = do
    writeTextSpan italic "Hello world. "
    writeTextSpan bold "This is bold text."
    writeNewPara
    writeTextSpan normal "This is normal text."

The text "This is normal text." will appear in a new paragraph.

writePara :: ParaStyle -> T.Text -> Writer ODT ()

To write a new section of text as a new paragraph with a paragraph style (as opposed to a text style), use the writePara function, e.g.:

```haskell
content :: Writer ODT ()
content = do
    writeTextSpan italic "Hello world. "
    writePara normalPara "This text is in normal paragraph style."
    writePara italicPara "This text is in italic paragraph style."

Saving the document to disk

There are two main functions which can write a new .odt file to disk, use the function writeNewODT.

writeNewODT :: Folderpath -> Filename -> Writer ODT () -> IO ()

Writes a new document to disk with all styling applied as direct formatting. For example, applying bold formatting using this function would be equivalent to pressing the B button in LibreOffice Writer, e.g.:

writeNewODT "./examples/output" "SimpleExample.odt" content

This will save the content we have described in content to a file SimpleExample.odt in the ./examples/output folder.

Acknowledgements

The inspiration for modelling an .odt file as a monoid, and for using the Writer monad for document composition, came from the HaTeX project, which provides an interface in Haskell for composing and otherwise analysing LaTeX documents.

Further information

• OpenDocument (Wikipedia)

• OpenDocument technical specification (Wikipedia)

• OpenDocument standard (OASIS Open)

Dependencies and licenses

• bytestring: BSD-style
• containers: BSD-3
• directory: BSD-3
• extra: BSD-3
• mtl: BSD-3
• text: BSD-style
• time: BSD-2
• xml: BSD-3
• xml-conduit: MIT
• zip-archive: BSD-3
• HUnit: BSD-3