render

Documentation

Overview

Package render turns the model into the text a person and a model read.

Two rules run through everything here (docs/architecture.md §4.1, §4.8):

• Mail content is data. Every field a sender wrote — subject, names, addresses, body, snippet, attachment names, parameters — is printed inside a delimited block that names its origin, closed by a boundary token drawn per call so the content cannot close the block itself. What the server says about the content (hidden text removed, links whose text names another site, what was collapsed or cut) is printed outside the blocks, as statements of fact. Nothing the server writes is phrased as an instruction taken from the mail.
• A read never silently returns less than it found. Every read has a budget in characters, states it, and names each omission with a way to continue.

The first rule is held by types, not by care: the writer's only way to put text outside a block is say, which takes a constant phrase and parts, and every part constructor takes a value a sender cannot shape (see writer.go).

Index

• Constants
• func FilterWrite(fw model.FilterWrite) string
• func ItemsWrite(iw model.ItemsWrite) string
• func LabelWrite(lw model.LabelWrite) string
• func Labels(ls []model.Label) string
• func Profile(p model.Profile) string
• func RandomToken() string
• type ChangeList
• type DraftList
• type MessageList
• type Options
• type Result
  • func Changes(l ChangeList, o Options) Result
  • func Download(s Saved, o Options) Result
  • func Draft(d model.Draft, o Options) Result
  • func DraftWrite(d model.DraftWrite, o Options) Result
  • func Drafts(l DraftList, o Options) Result
  • func Filters(fs []model.Filter, o Options) Result
  • func Message(m model.Message, o Options) Result
  • func Messages(l MessageList, o Options) Result
  • func SendDraft(sw model.SendWrite, o Options) Result
  • func Settings(st model.Settings, o Options) Result
  • func SignatureWrite(sw model.SignatureWrite, o Options) Result
  • func Thread(t model.Thread, o Options) Result
  • func Threads(l ThreadList, o Options) Result
  • func VacationWrite(vw model.VacationWrite, o Options) Result
• type Saved
• type ThreadList
• type TokenSource

Constants

const DefaultBudget = 24000

DefaultBudget is the character budget of a read when none is given. About 6,000 tokens: a thread read leaves room in a client capped at 25,000 (§3.8).

const MinBudget = 2000

MinBudget keeps a tiny budget from producing a read with no content.

Functions

func FilterWrite

func FilterWrite(fw model.FilterWrite) string

FilterWrite renders create_filter's and delete_filter's result, in the server's voice, the filter shown as list_filters shows it.

func ItemsWrite

func ItemsWrite(iw model.ItemsWrite) string

ItemsWrite renders modify_labels, trash or restore, item by item.

func LabelWrite

func LabelWrite(lw model.LabelWrite) string

LabelWrite renders a created, updated or deleted label.

func Labels

func Labels(ls []model.Label) string

Labels renders a label list. Label names are the account's own, not a sender's, so they are not in blocks (see labelName).

func Profile

func Profile(p model.Profile) string

Profile renders the account. Nothing in it came from a sender.

func RandomToken

func RandomToken() string

RandomToken is 16 random hex digits.

Types

type ChangeList

type ChangeList struct {
	// Start is the history id the page was read from.
	Start   string
	Changes []model.Change
	// Expired is set when Gmail no longer holds history from Start.
	Expired bool
	// HistoryID is the mailbox's current history id.
	HistoryID     string
	NextPageToken string
	// Label is the label the listing was limited to, if any.
	Label *model.LabelRef
}

ChangeList is one page of list_changes.

type DraftList

type DraftList struct {
	Drafts             []model.Draft
	NextPageToken      string
	ResultSizeEstimate int
}

DraftList is one page of list_drafts, each draft's message read with format=metadata.

type MessageList

type MessageList struct {
	Messages           []model.Message
	NextPageToken      string
	ResultSizeEstimate int
}

MessageList is one page of search_messages, messages read with format=metadata.

type Options

type Options struct {
	// Budget in characters; 0 means DefaultBudget.
	Budget int
	// Tokens draws the boundary token; nil means RandomToken.
	Tokens TokenSource
	// Location renders dates; nil means UTC.
	Location *time.Location
	// AllHeaders shows every header rather than the fixed set (§7.2).
	AllHeaders bool
	// ShowQuoted keeps quoted text and signatures instead of collapsing
	// them.
	ShowQuoted bool
	// Cursor skips this many of a thread's newest messages.
	Cursor int
	// Offset starts a message's body at this character.
	Offset int
}

Options shape a read.

type Result

type Result struct {
	Text string
	// Token is the boundary token the blocks use.
	Token  string
	Budget int
	// Truncated is set when anything found was left out.
	Truncated bool
	// NextCursor continues a thread; 0 when nothing is left.
	NextCursor int
	// NextOffset continues a cut body; 0 when the body was whole.
	NextOffset int
	// Omitted lists the ids of messages or rows not shown.
	Omitted []string
}

Result is a rendered read and what it left for later.

func Changes

func Changes(l ChangeList, o Options) Result

Changes renders changes since a history id. Nothing in a change was written by a sender: ids, kinds and the account's label names. An expired cursor is said plainly and never shown as an empty page (§7.6).

func Download

func Download(s Saved, o Options) Result

Download renders a written attachment. The file name is the sender's, so it is shown only inside a block; what the server did is said outside it.

func Draft

func Draft(d model.Draft, o Options) Result

Draft renders one draft: both ids, then the message as get_message renders it. A draft's text is treated as untrusted too: it may have been shaped by someone other than the person reading it (§4.2).

func DraftWrite

func DraftWrite(d model.DraftWrite, o Options) Result

DraftWrite renders a created, updated or deleted draft.

func Drafts

func Drafts(l DraftList, o Options) Result

Drafts renders a draft listing. Both ids are named on every row (§6.1).

func Filters

func Filters(fs []model.Filter, o Options) Result

Filters renders the account's filters within the budget. A filter that forwards is flagged on its own line: it sends matching mail out of the account.

func Message

func Message(m model.Message, o Options) Result

Message renders one message under the budget, starting its body at o.Offset.

func Messages

func Messages(l MessageList, o Options) Result

Messages renders a message listing.

func SendDraft

func SendDraft(sw model.SendWrite, o Options) Result

SendDraft renders a sent draft, or what a dry run would send (§4.2): every recipient, whether the guard clears it, the subject, the files and the thread. Addresses, the subject and file names are in a block, one recipient per line under its field and position, which is how the guard's refusal names them.

func Settings

func Settings(st model.Settings, o Options) Result

Settings renders the account's settings, forwarding first: whether mail is leaving the account is the reason to read them (§7.7).

func SignatureWrite

func SignatureWrite(sw model.SignatureWrite, o Options) Result

SignatureWrite renders update_signature's result: the signature before and after, each in a block, since either may hold text the account's owner did not write here.

func Thread

func Thread(t model.Thread, o Options) Result

Thread renders a conversation newest first under the budget, starting o.Cursor messages from the newest. Messages that do not fit are listed by id and date with the cursor that reads them, and their senders in a block. When even the first message does not fit, its body is cut and the result says where to continue. The thread's drafts follow the conversation in a section of their own, on the first read only, and the cursor counts only what was said (§17.2).

func Threads

func Threads(l ThreadList, o Options) Result

Threads renders a thread listing.

func VacationWrite

func VacationWrite(vw model.VacationWrite, o Options) Result

VacationWrite renders set_vacation's result: the reply before and after, its audience and dates in the server's voice and its text in a block, as get_settings shows it.

type Saved

type Saved struct {
	MessageID string
	PartID    string
	// Path is where it was written. Its base name came from the sender.
	Path string
	// DeclaredName is the name the sender gave, when it was unsafe as a
	// file name and was changed.
	DeclaredName string
	// Suffixed is set when the name was taken and a number was added.
	Suffixed bool
	MimeType string
	Bytes    int64
	SHA256   string
}

Saved is one attachment written to disk.

type ThreadList

type ThreadList struct {
	Threads            []model.Thread
	NextPageToken      string
	ResultSizeEstimate int
}

ThreadList is one page of search_threads. Threads carry their messages read with format=metadata.

type TokenSource

type TokenSource func() string

TokenSource draws a boundary token. Tests inject a fixed one.