visualize

// suppress inspection "GrazieInspection" for whole file
// suppress inspection "GrazieInspection"
= How to use the jwz module by example
Jim Idle <jimi@gatherstars.com>
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.