Documentation
¶
Overview ¶
Package profile stores the local player identities twixtui plays under.
There are no passwords: a profile is a name and two timestamps, kept in one JSON file under the user's configuration directory. The store's job is to let a returning player pick the identity they used last time even when they misremember how they spelled it, which is what Search is for.
Index ¶
- Constants
- Variables
- func DefaultDir() (string, error)
- func ValidateName(name string) error
- type Match
- type Profile
- type Store
- func (s *Store) ClearCurrent() error
- func (s *Store) Create(name string) (Profile, error)
- func (s *Store) Current() (Profile, bool)
- func (s *Store) Delete(name string) error
- func (s *Store) Get(name string) (Profile, bool)
- func (s *Store) List() []Profile
- func (s *Store) MarkIntroduced(name string) error
- func (s *Store) Path() string
- func (s *Store) Rename(oldName, newName string) error
- func (s *Store) Search(query string) []Match
- func (s *Store) SetCurrent(name string) error
- func (s *Store) Touch(name string) error
- func (s *Store) UseCurrent(name string) (Profile, error)
Examples ¶
Constants ¶
const EnvConfigDir = "TWIXTUI_CONFIG_DIR"
EnvConfigDir names an environment variable that replaces the default configuration directory outright (it is used as-is, with no "twixtui" component appended). Tests and the end-to-end harness set it so a run never touches the state of the person running it.
const MaxNameRunes = 32
MaxNameRunes bounds a profile name. Thirty-two characters is long enough for a full name with spaces and short enough that a list of profiles still fits in a narrow terminal pane alongside its rating.
Variables ¶
var ( ErrNameEmpty = errors.New("name is empty") ErrNameTooLong = errors.New("name is too long") ErrNamePadded = errors.New("name has leading or trailing whitespace") ErrNameControl = errors.New("name contains a control character") ErrNameInvisible = errors.New("name contains an invisible or bidirectional control character") ErrNameNotUTF8 = errors.New("name is not valid UTF-8") )
Name rejection reasons. Callers match these with errors.Is to report the specific problem rather than a generic "invalid name".
var ( ErrNotFound = errors.New("profile not found") ErrExists = errors.New("profile already exists") )
Store errors. Callers match these with errors.Is.
Functions ¶
func DefaultDir ¶
DefaultDir returns the directory twixtui keeps player state in.
func ValidateName ¶
ValidateName reports whether a string is usable as a profile name.
The rule: valid UTF-8, one to MaxNameRunes characters, no leading or trailing whitespace, no control characters, and no invisible or bidirectional formatting characters. Interior spaces and non-Latin scripts are fine — the name is a display identity, not a filename or a shell word.
Invisible formatting characters are refused rather than stripped because a name that does not render as its own characters cannot be typed back by the person who chose it, which defeats the point of being able to find your profile again.
Types ¶
type Match ¶
type Match struct {
Profile Profile
// Score ranks the match; higher is better. Scores are only comparable
// within one result set.
Score int
// Positions are the indexes, in runes, of the characters of Profile.Name
// that the query matched, so the caller can highlight them.
Positions []int
}
Match is a profile that a search query found.
type Profile ¶
type Profile struct {
Name string `json:"name"`
Created time.Time `json:"created"`
LastUsed time.Time `json:"last_used"`
// Introduced records that this player has been through the short
// introduction the interface offers on a first run. See introduction.go for
// why it is a property of the profile rather than of the machine, and for
// why it is added without moving storeVersion.
Introduced bool `json:"introduced,omitempty"`
}
Profile is one local player identity.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is the set of profiles on this machine.
A Store is safe for concurrent use. Mutations reload the file inside an advisory lock before applying, so a second twixtui process cannot lose the first one's writes; reads reload only when the file has changed underneath.
func Open ¶
Open loads the profile store in dir, creating the directory on first use. An empty dir means the default configuration directory.
func (*Store) ClearCurrent ¶
ClearCurrent forgets which profile is playing.
func (*Store) Create ¶
Create adds a profile. The name is validated and must not collide with an existing one, case and interior spacing ignored.
func (*Store) Current ¶
Current returns the profile last chosen on this machine.
A name that no longer matches a profile reports as no choice rather than as an error: a deleted profile is an ordinary thing to find here, not a fault.
func (*Store) Delete ¶
Delete removes a profile. Recorded results are not touched: the leaderboard keeps its own history, and deleting an identity is not meant to rewrite the record of games that were played.
func (*Store) Get ¶
Get looks a profile up by name, ignoring case and whitespace differences the same way duplicate detection does.
func (*Store) List ¶
List returns every profile, most recently used first.
Example ¶
dir, cleanup := exampleDir()
defer cleanup()
store, err := Open(dir)
if err != nil {
log.Fatal(err)
}
for _, name := range []string{"Balint", "Bernadett"} {
if _, err := store.Create(name); err != nil {
log.Fatal(err)
}
}
if err := store.Touch("balint"); err != nil {
log.Fatal(err)
}
// Most recently used first, which is the order the launch prompt offers.
for _, p := range store.List() {
fmt.Println(p.Name)
}
Output: Balint Bernadett
func (*Store) MarkIntroduced ¶ added in v0.2.0
MarkIntroduced records that a profile has been through the introduction. It is called when the introduction is left, whether the player read it through or skipped it: somebody who skipped does not want it again next launch, so the two departures are the same fact.
func (*Store) Rename ¶
Rename changes a profile's name, keeping its timestamps. Changing only the capitalisation of an existing name is allowed; colliding with a different profile is not.
func (*Store) Search ¶
Search ranks profiles against a query.
An empty query returns every profile in List order, most recently used first, which is the browsable list a player scrolls when they cannot recall the name at all. A non-empty query is matched two ways:
- as a subsequence, scored by github.com/sahilm/fuzzy, which handles partial names ("lin"), dropped letters ("balnt") and any capitalisation;
- failing that, by bounded edit distance against any part of the name, which handles the typo classes a subsequence matcher structurally cannot see — a transposition ("balitn"), a doubled letter ("ballint") or a wrong letter ("balont") all put a query rune where no later occurrence exists.
Every subsequence match outranks every rescued one, and rescues are ordered by how many corrections they needed. Ties break towards the most recently used profile.
Example ¶
dir, cleanup := exampleDir()
defer cleanup()
store, err := Open(dir)
if err != nil {
log.Fatal(err)
}
for _, name := range []string{"Balint", "Bernadett", "Bella Ackland"} {
if _, err := store.Create(name); err != nil {
log.Fatal(err)
}
}
// The player transposed the last two letters of their own name.
for _, m := range store.Search("balitn") {
fmt.Println(m.Profile.Name, m.Positions)
}
Output: Balint [0 1 2 3 5]
func (*Store) SetCurrent ¶
SetCurrent records the profile that is playing. The name must already exist, so that the recorded choice cannot point at nothing.
Source Files