1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
|
// 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.
|
