// suppress inspection "GrazieInspection" for whole file // suppress inspection "GrazieInspection" = How to use the jwz module by example Jim Idle [email protected] 0.9.0, August 10, 2021: Explaining jwz module by example :toc: :icons: font :keywords: jwz email parsing threading enmime ifdef::env-github[] :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: :imagesdir: https://github.com/gatherstars-com/jwz/raw/master/docs/img/ :showtitle: endif::[] ifndef::env-github[] :imagesdir: ../../docs/img/ endif::[]

image:clonobg.png[Gather Stars Logo, 100, 100] This visualize tool is a working example showing how to use the Gather Stars, Inc. version of the widely known JWZ message threading algorithm originally written by Jamie Zawinsky - see https://www.jwz.org/doc/threading.html[his explanation here].

This example demonstrates the use of go interfaces of the package. Obviously, so long as your own structure can implement the Threadable interface, then you can implement the email inputs however you like.

The package is advertised as production quality, but the examples are obviously not.

== Following the example code

.The code is easy enough, with the main.go file showing how to:

• Parse raw .eml files in to email envelopes using the excellent https://github.com/jhillyerd/enmime[Enmime go module]
• Wrap the parsed envelopes in to a set of Threadable interfaces
• Thread the set using the jwz package
• Use the supplied Sort utility func to sort the threadable tree
• Use the https://github.com/rivo/tview[tview] package to create an ASCII display tree of the emails to show humans that threading is working. The package tests verify it is working for programs.

.The handlers.go file provides:

• Sample implementation of the interface, called Email, which you can crib from (also, see the jwz_test.go file for an example of how to thread an arbitrary data model instead of a simple slice)
• Some utility funcs ** buildEnvelopes parses all the .eml files it finds into a slice of Email structs ** byDate is an example sorting function, which obviously sorts by the email date

== Trying it out

The repo provides a publicly available email set under test/testdata. Clone this repo and then run it like this:

==== $ vizualize -emldir path/to/test/testdata

You will see some diagnostics about the quality of the test set (it is deliberately broken in some places for the unit tests), you should see a treeview in your terminal that looks like this:

image::screen2.png[Image of threaded tree]

If you don't need that testdata and just want to try the command on your own dataset, then there is no need to clone this repo. You can just install the visualize command into ${GOPATH}/bin:

==== ~/lufc/ > go install github.com/gatherstars-com/jwz/examples/visualize@latest

Where I am sure it will clash with 42 other commands called visualize.