API changes: use the same function signature for package funcs

[rorycl]

Hi @mnako

I've had a chance to look at how to potentially implement new package level funcs, as set out in this PR. Let me know what you think.

Cheers,
Rory

---

api: split main package ParseEmail func into several variants

Split ParseEmail into three functions with the function signature

   io.Reader (Email, error)

The three functions are

• ParseEmail (the existing main entry point)
• ParseEmailHeaders
• ParseEmailWithoutAttachments

ParseEmailHeadings replaces ParseHeadings that takes an Email parameter
instead of an io.Reader.

The existing ParseEmail function is renamed to parseEmail and the
processing options determined by the new processType type.

[rorycl]

I've run a quick benchmark to compare ParseEmail, ParseEmailHeaders and ParseEmailWithoutAttachments. The setup is 5 emails with ~20MB attachments each. The test is attached as performance_test.go.txt.

The results are as follows on my ancient thinkpad t470s:

rory:~/src/letters$ go test -run=Benchmark -bench=.  -benchtime=15s
goos: linux
goarch: amd64
pkg: github.com/mnako/letters
cpu: Intel(R) Core(TM) i7-7600U CPU @ 2.80GHz
BenchmarkParseEmail-4                     	      14	1091424774 ns/op
BenchmarkParseEmailHeadersOnly-4          	    5770	   5307012 ns/op
BenchmarkParseEmailWithoutAttachments-4   	      20	 839565841 ns/op
PASS
ok  	github.com/mnako/letters	65.073s

I'm surprised that ParseEmailWithoutAttachments is only a bit over 20% faster than ParseEmail but I guess the programme is still having to read through the MIME parts. I realise this isn't a huge performance gain but it is useful for programmes such as my mailfinder programme.

[rorycl]

Apologies, after looking at my work from the weekend I realise I hadn't put types into the structs.go file -- I'm not used to doing that.

I can provide a new PR after receiving comments, if any.