Update fallback style

Editing config files with things like gedit work now

README.md

@@ -2,12 +2,79 @@
 
 [![Go Reference](https://pkg.go.dev/badge/git.tebibyte.media/tomo/nasin.svg)](https://pkg.go.dev/git.tebibyte.media/tomo/nasin)
 
-Nasin provides an easy way to write applications with Tomo. To get started, take
-a look at the [examples](examples) directory and the
+Nasin builds an application framework on top of Tomo to ease and encourage the
+development of consistent and stable application software. It has these
+wonderful features, and more:
+
+- Use the Application interface to create applications with relatively low
+  boilerplate
+- CLI argument parsing and URI opening
+- Automatic setup/teardown of the backend
+- Advanced configuration system that can watch config files for changes
+- Default style and icon set, as well as a fully featured stylesheet language
+  for creating custom styles, and support for XDG icon themes
+
+## Getting Started
+Here is a basic "hello world" application, with explanations as comments:
+```go
+package main
+
+import "image"
+import "git.tebibyte.media/tomo/nasin"
+import "git.tebibyte.media/tomo/objects"
+import "git.tebibyte.media/tomo/objects/layouts"
+
+func main () {
+	nasin.RunApplication(new(Application))
+}
+
+type Application struct { }
+
+// Describe returns the application's name and ID, and optionally what type of
+// application it is.
+func (this *Application) Describe () nasin.ApplicationDescription {
+	return nasin.ApplicationDescription {
+		// This is the name of the application. New application windows
+		// will have this as their title by default.
+		Name: "Example",
+		// This is a "well-known" name, which typically is a domain name
+		// owned by the application author.
+		ID: "com.example.Example",
+	}
+}
+
+// Init performs initial setup of the application. Since this is a single-window
+// application that doesn't open any files, we create the window here.
+func (this *Application) Init () error {
+	// Passing an empty rectangle when creating a new window will cause it
+	// to auto-expand to fit the minimum size of its contents.
+	window, err := nasin.NewApplicationWindow(this, image.Rectangle { })
+	if err != nil { return err }
+	// Here we create a new container with a basic vertical layout, place a
+	// text label that says "Hello world!" in it, and set it as the root
+	// object of the window.
+	window.SetRoot(objects.NewOuterContainer (
+		layouts.ContractVertical,
+		objects.NewLabel("Hello world!")))
+	window.SetVisible(true)
+	// Nasin will not exit until all windows it is "waiting for" have
+	// been closed.
+	nasin.WaitFor(window)
+	return nil
+}
+
+// Stop cleanly closes things like system resources or background tasks. We do
+// not have any here, so nothing is done.
+func (this *Application) Stop () { }
+```
+
+To learn more, take a look at the [examples](examples) directory and the
 [online documentation](https://pkg.go.dev/git.tebibyte.media/tomo/nasin).
 
-Related repositories:
+## Related Repositories
 - [Tomo API](https://git.tebibyte.media/tomo/tomo): The API that all other parts
   of the toolkit agree on
 - [Objects](https://git.tebibyte.media/tomo/objects): A standard collection of
   re-usable objects and other GUI components
+- [Backend](https://git.tebibyte.media/tomo/backend): The software responsible
+  for managing and rendering things behind the scenes

application.go

@@ -144,15 +144,47 @@ func RunApplication (application Application) {
 	}
 	flag.Parse()
 
+	// open config
+	globalConfig, err := ApplicationConfig(GlobalApplicationDescription())
+	if err != nil { log.Fatalln("nasin: could not open config:", err) }
+	currentGlobalConfig = globalConfig
+	defer func () {
+		globalConfig.Close()
+		currentGlobalConfig = nil
+	} ()
+	styleConfigKey   := "Style"
+	iconSetConfigKey := "IconSet"
+
+	// registry
+	// TODO: rebuild registry around the config
 	reg := new(registrar.Registrar)
 	backend, err := reg.SetBackend()
 	if err != nil { log.Fatalln("nasin: could not register backend:", err) }
-	err = reg.SetTheme()
-	if err != nil { log.Fatalln("nasin: could not set theme:", err) }
-	err = reg.SetIconSet()
-	if err != nil { log.Fatalln("nasin: could not set icon set:", err) }
 	err = reg.SetFaceSet()
 	if err != nil { log.Fatalln("nasin: could not set face set:", err) }
+	updateStyle := func () {
+		value, err := globalConfig.GetString(styleConfigKey, "")
+		if err != nil { log.Fatalln("nasin: could not set theme:", err) }
+		err = reg.SetStyle(value)
+		if err != nil { log.Fatalln("nasin: could not set theme:", err) }
+	}
+	updateIconSet := func () {
+		value, err := globalConfig.GetString(iconSetConfigKey, "")
+		if err != nil { log.Fatalln("nasin: could not set icon set:", err) }
+		err = reg.SetIconSet(value)
+		if err != nil { log.Fatalln("nasin: could not set icon set:", err) }
+	}
+	updateStyle()
+	updateIconSet()
+
+	globalConfig.OnChange(func (key string) {
+		switch key {
+		case styleConfigKey:   updateStyle()
+		case iconSetConfigKey: updateIconSet()
+		}
+	})
+
+	// init application
 	err = application.Init()
 	if err != nil { log.Fatalln("nasin: could not run application:", err) }
 
@@ -172,8 +204,8 @@ func RunApplication (application Application) {
 // owned by the application. The window's icon will be automatically set by
 // looking for an icon with the name of the application's ID. If that is not
 // found, the default icon for the application's ApplicationRole will used.
-func NewApplicationWindow (application Application, bounds image.Rectangle) (tomo.Window, error) {
-	window, err := tomo.NewWindow(bounds)
+func NewApplicationWindow (application Application, kind tomo.WindowKind, bounds image.Rectangle) (tomo.Window, error) {
+	window, err := tomo.NewWindow(kind, bounds)
 	if err != nil { return nil, err }
 	description := application.Describe()
 	window.SetTitle(description.Name)
@@ -196,6 +228,14 @@ func ApplicationConfig (app ApplicationDescription) (config.ConfigCloser, error)
 	return config.NewConfig(user, system...)
 }
 
+var currentGlobalConfig config.Config
+// GlobalConfig returns the global config. It contains options that apply to
+// Tomo/Nasin itself, such as the style sheet and the icon set. This is managed
+// by Nasin and must not be closed by the application.
+func GlobalConfig () config.Config {
+	return currentGlobalConfig
+}
+
 func errorPopupf (title, format string, v ...any) func (func ()) {
 	return func (callback func ()) {
 		dialog, err := objects.NewDialogOk (

config/README.md

@@ -0,0 +1,78 @@
+# config
+Package config provides a configuration system for applications.
+
+## Config File Location
+Config files are stored in standard operating system locations. Each application
+has exactly one user-level config directory within the user-level config
+location, and a system-level subdirectory in each of the system-level config
+locations (if applicable). Each subdirectory bears the application's well-known
+name as specified in ApplicationDescription. Each subdirectory contains a file
+called config.conf, which is where the actual config data is stored.
+
+The user-level configuration file takes precendence over system configuration
+files, and system configuration files take precedence over eachother depending
+on what order they are specified in. How they are specified depends on the
+operating system.
+
+### Linux, Most Unixes
+In terms of the XDG Base Directory Specification, an application with the
+well-known name com.example.Example would have its config files stored at
+`$XDG_CONFIG_DIRS/com.example.Example/config.conf`. On most systems where this
+specification is applicable, this will result in a file at
+`/etc/xdg/com.example.Example/config.conf` and another at
+`$HOME/.config/com.example.Example/config.conf`. The location for config files
+on systems that do not make use of this specification is yet to be determined.
+
+## Config File Format
+The general format of the file is as follows:
+
+- Encoded in UTF-8
+- Consists of lines, separated by \n, or \r\n
+- Lines can be any of these:
+  - Blank line: has only whitespace
+  - Comment: begins with a '#'
+  - Entry: a key/value pair separated by an '=' sign
+
+### Entries
+For entries, all whitespace on either side of the '=' sign, the key, or the
+value is ignored. The key may contain any letter or digit, as well as '-' and
+'.'. The value is always identified by its first rune (after the preliminary
+whitespace of course) and can be one of:
+
+- String
+- Number
+- Bool
+
+#### String
+A string can be either double-quoted, or any string of runes not identifiable
+as any other kind of value. Quoted strings are always unquoted when they are
+read. Either way, these escape sequences are supported, and resolved when they
+are read:
+
+- '\\\\': a literal backslash
+- '\a': alert, bell
+- '\b': backspace
+- '\t': horizontal tab
+- '\n': line feed
+- '\v': vertical tab
+- '\f': form feed
+- '\r': carriage return
+- '\\"': double quote
+
+Be aware that some unquoted strings, within reason, are subject to being read
+as some other value in the future. For example, if there were suddenly a
+third boolean value called glorble, the unquoted string glorble would be read
+as a boolean value instead of a string.
+
+#### Number
+A number is a floating point value. It can be of the form:
+- Inf: positive infinity
+- -Inf: negative infinity
+- NaN: "not a number"
+- [0-9]+: a whole number
+- [0-9]+\.[0-9]*: a fractional number
+
+#### Bool
+A bool is a boolean value. It can be one of:
+- true
+- false

config/config.go

@@ -54,11 +54,15 @@ type Config interface {
 	// not a boolean, it will return fallback.
 	GetBool (key string, fallback bool) (bool, error)
 	// Set sets a value in the user-level config file. If the key is
-	// invalid, it returns ErrMalformedKey.
+	// invalid, it returns ErrMalformedKey. Note that calling this behavior
+	// *will* cause a write to disk, and a read from disk for whatever is
+	// watching the user file.
 	Set (key string, value Value) error
 	// Reset removes the value from the user-level config file, resetting it
 	// to what is described by the system-level config files. If the key is
-	// invalid, it returns ErrMalformedKey.
+	// invalid, it returns ErrMalformedKey. Note that calling this behavior
+	// *will* cause a write to disk if successful , and a read from disk for
+	// whatever is watching the user file.
 	Reset (key string) error
 	// OnChange specifies a function to be called whenever a value is
 	// changed. The callback is always run within the backend's event loop
@@ -84,12 +88,17 @@ var negativeZero = math.Copysign(0, -1)
 type Value interface {
 	value ()
 	fmt.Stringer
+	Equals (Value) bool
 }
 
 // ValueString is a string value.
 type ValueString string
 var _ Value = ValueString("")
 func (ValueString) value () { }
+func (value ValueString) Equals (other Value) bool {
+	other, ok := other.(ValueString)
+	return ok && value == other
+}
 func (value ValueString) String () string {
 	return fmt.Sprintf("\"%s\"", escape(string(value)))
 }
@@ -98,6 +107,10 @@ func (value ValueString) String () string {
 type ValueNumber float64
 var _ Value = ValueNumber(0)
 func (ValueNumber) value () { }
+func (value ValueNumber) Equals (other Value) bool {
+	other, ok := other.(ValueNumber)
+	return ok && value == other
+}
 func (value ValueNumber) String () string {
 	number := float64(value)
 	// the requirements I wrote said lossless in all cases. here's lossless
@@ -133,6 +146,10 @@ func (value ValueNumber) String () string {
 var _ Value = ValueBool(false)
 type ValueBool bool
 func (ValueBool) value () { }
+func (value ValueBool) Equals (other Value) bool {
+	other, ok := other.(ValueBool)
+	return ok && value == other
+}
 func (value ValueBool) String () string {
 	if value {
 		return "true"

config/file.go

@@ -13,6 +13,8 @@ type line any
 type comment string
 type entry struct { key string; value Value }
 
+var _ io.WriterTo = new(File)
+
 // File represents a config file. It preserves the order of the lines, as well
 // as blank lines and comments.
 type File struct {
@@ -29,47 +31,8 @@ func NewFile () *File {
 
 // Parse parses a config file from a reader. This function operates on a
 // best-effort basis: A file will always be returned, and any errors encountered
-// will be joined together.
-//
-// The general format of the file is as follows:
-//   - Encoded in UTF-8
-//   - Consists of lines, separated by \n, or \r\n
-//   - Lines can be any of these:
-//     - Blank line: has only whitespace
-//     - Comment: begins with a '#'
-//     - Entry: a key/value pair separated by an '=' sign
-//
-// For entries, all whitespace on either side of the '=' sign, the key, or the
-// value is ignored. The key may contain any letter or digit, as well as '-'
-// and '.'. The value is always identified by its first rune (after the
-// preliminary whitespace of course) and can be one of:
-//   - String: either a double-quoted string, or any string of runes not
-//     identifiable as any other kind of value. The quoted string is always
-//     unquoted when it is read. Either way, these escape sequences are
-//     supported, and resolved when they are read:
-//     - '\\': a literal backslash
-//     - '\a': alert, bell
-//     - '\b': backspace
-//     - '\t': horizontal tab
-//     - '\n': line feed
-//     - '\v': vertical tab
-//     - '\f': form feed
-//     - '\r': carriage return
-//     - '\"': double quote
-//   - Number: a floating point value. It can be of the form:
-//     - Inf
-//     - -Inf
-//     - NaN
-//     - [0-9]+
-//     - [0-9]+\.[0-9]*
-//   - Bool: a boolean value. It can be one of:
-//     - true
-//     - false
-//
-// Be aware that some unquoted strings, within reason, are subject to being read
-// as some other value in the future. For example, if there were suddenly a
-// third boolean value called glorble, the unquoted string glorble would be read
-// as a boolean value instead of a string.
+// will be joined together. For a description of the format, see the README.md
+// of this package.
 func Parse (reader io.Reader) (*File, error) {
 	file := &File {
 		keys: make(map[string] int),
@@ -143,12 +106,24 @@ func ParseValue (str string) (Value, error) {
 	}
 }
 
+// Has returns whether the key exists. If the key is invalid, it returns false,
+// ErrMalformedKey.
+func (this *File) Has (key string) (bool, error) {
+	if !KeyValid(key) { return false, ErrMalformedKey }
+	if index, ok := this.keys[key]; ok {
+		if _, ok := this.lines[index].(entry); ok {
+			return true, nil
+		}
+	}
+	return false, nil
+}
+
 // Get gets the keyed value. If the value is unspecified, it returns nil,
 // ErrNonexistentEntry. If the key is invalid, it returns nil, ErrMalformedKey.
 func (this *File) Get (key string) (Value, error) {
 	if !KeyValid(key) { return nil, ErrMalformedKey }
 	if index, ok := this.keys[key]; ok {
-		if lin := this.lines[index].(entry); ok {
+		if lin, ok := this.lines[index].(entry); ok {
 			return lin.value, nil
 		}
 	}
@@ -158,14 +133,16 @@ func (this *File) Get (key string) (Value, error) {
 // Set sets a value. If the key is invalid, it returns ErrMalformedKey.
 func (this *File) Set (key string, value Value) error {
 	if !KeyValid(key) { return ErrMalformedKey }
+	ent := entry {
+		key:   key,
+		value: value,
+	}
 	if index, ok := this.keys[key]; ok {
-		ent := this.lines[index].(entry)
-		ent.value = value
 		this.lines[index] = ent
 		return nil
 	}
 	this.keys[key] = len(this.lines)
-	this.lines     = append(this.lines, value)
+	this.lines     = append(this.lines, ent)
 	return nil
 }
 
@@ -186,7 +163,7 @@ func (this *File) Reset (key string) error {
 	return nil
 }
 
-// Map returns a map of keys to values.
+// Map creates and returns a map of keys to values.
 func (this *File) Map () map[string] Value {
 	mp := make(map[string] Value)
 	for key, index := range this.keys {
@@ -197,9 +174,48 @@ func (this *File) Map () map[string] Value {
 	return mp
 }
 
+// Diff returns a set of keys that are different from the other file.
+func (this *File) Diff (other *File) map[string] struct { } {
+	diff := make(map[string] struct { })
+	
+	// - keys only we have
+	// - keys we both have, but are different
+	for key, index := range this.keys {
+		thisEntry, ok := this.lines[index].(entry)
+		if !ok { continue }
+	
+		otherIndex, ok := other.keys[key]
+		if !ok {
+			diff[key] = struct { } { }
+			continue
+		}
+		otherEntry, ok := other.lines[otherIndex].(entry)
+		if !ok {
+			diff[key] = struct { } { }
+			continue
+		}
+		
+		if !thisEntry.value.Equals(otherEntry.value) {
+			diff[key] = struct { } { }
+		}
+	}
+
+	// - keys only they have
+	for key := range other.keys {
+		if otherHas, _ := other.Has(key); !otherHas {
+			continue
+		}
+		if thisHas, _ := this.Has(key); !thisHas {
+			diff[key] = struct { } { }
+		}
+	}
+
+	return diff
+}
+
 // WriteTo writes the data in this file to an io.Writer.
-func (file *File) WriteTo (writer io.Writer) (n int64, err error) {
-	for _, lin := range file.lines {
+func (this *File) WriteTo (writer io.Writer) (n int64, err error) {
+	for _, lin := range this.lines {
 		nint := 0
 		switch lin := lin.(type) {
 		case comment:

config/file_test.go

@@ -1,6 +1,7 @@
 package config
 
 import "math"
+import "maps"
 import "strings"
 import "testing"
 
@@ -103,6 +104,81 @@ key1=7
 `)
 }
 
+func TestDiffNone (test *testing.T) {
+	str := `
+thing = something
+
+otherThing  = otherValue
+# comment
+otherThing = true
+otherThing = 234
+
+yetAnotherThing = 0.23498
+`
+	file1 := parseFileString(test, str)
+	file2 := parseFileString(test, str)
+	diff := file1.Diff(file2)
+	if len(diff) != 0 {
+		test.Fatalf("diff not empty:\n%v", diff)
+	}
+}
+
+func TestDiffReset (test *testing.T) {
+	file1 := parseFileString(test,
+`key4=0
+key1=value1
+keyToDelete=true
+# comment
+key2=34`)
+	file2 := parseFileString(test,
+`key1=value2
+key2=34
+anotherKeyToDelete=false
+# comment
+
+key3=0.2`)
+	file1.Reset("keyToDelete")
+	file2.Reset("anotherKeyToDelete")
+	diff := file1.Diff(file2)
+	correct := map[string] struct { } {
+		"key1": struct { } { },
+		"key3": struct { } { },
+		"key4": struct { } { },
+	}
+	if !maps.Equal(diff, correct) {
+		test.Error("diffs do not match")
+		test.Errorf("EXPECTED:\n%v", correct)
+		test.Errorf("GOT:\n%v", diff)
+		test.Fail()
+	}
+}
+
+func TestDiff (test *testing.T) {
+	file1 := parseFileString(test,
+`key4=0
+key1=value1
+# comment
+key2=34`)
+	file2 := parseFileString(test,
+`key1=value2
+key2=34
+# comment
+
+key3=0.2`)
+	diff := file1.Diff(file2)
+	correct := map[string] struct { } {
+		"key1": struct { } { },
+		"key3": struct { } { },
+		"key4": struct { } { },
+	}
+	if !maps.Equal(diff, correct) {
+		test.Error("diffs do not match")
+		test.Errorf("EXPECTED:\n%v", correct)
+		test.Errorf("GOT:\n%v", diff)
+		test.Fail()
+	}
+}
+
 func testParseEntry (test *testing.T, str string, key string, value Value) {
 	ent, err := parseEntry(str)
 	if err != nil { test.Fatal(err) }

config/impl.go

@@ -6,6 +6,7 @@ import "sync"
 import "slices"
 import "path/filepath"
 import "github.com/fsnotify/fsnotify"
+import "git.tebibyte.media/tomo/tomo"
 import "git.tebibyte.media/tomo/tomo/event"
 
 // Goroutine model:
@@ -15,9 +16,10 @@ import "git.tebibyte.media/tomo/tomo/event"
 // directly followed by a deferred call to Unlock.
 
 type config struct {
-	open    bool
-	watcher *fsnotify.Watcher
-	lock    sync.RWMutex
+	open                 bool
+	watcher              *fsnotify.Watcher
+	lock                 sync.RWMutex
+	ignoreNextUserUpdate bool
 
 	paths struct {
 		user     string
@@ -63,19 +65,26 @@ func NewConfig (user string, system ...string) (ConfigCloser, error) {
 func (this *config) lockAndProcessEvent (event fsnotify.Event) {
 	this.lock.Lock()
 	defer this.lock.Unlock()
-	if !(event.Has(fsnotify.Write))                  { return }
-	if _, ok := this.paths.watching[event.Name]; !ok { return }
+	if !(event.Has(fsnotify.Write | fsnotify.Create)) { return }
+	if _, ok := this.paths.watching[event.Name]; !ok  { return }
 
 	if event.Name == this.paths.user {
-		this.reloadUser()
+		if !this.ignoreNextUserUpdate {
+			previousUser := this.data.user
+			this.reloadUser()
+			newUser := this.data.user
+			this.processUserDiff(newUser.Diff(previousUser))
+		}
+		this.ignoreNextUserUpdate = false
 	} else {
 		index := slices.Index(this.paths.system, event.Name)
 		if index > 0 {
+			previousSystem := this.data.system[index]
 			this.reloadSystem(index)
+			newSystem := this.data.system[index]
+			this.processSystemDiff(index, diffValueMaps(newSystem, previousSystem))
 		}
 	}
-
-	// TODO diff and call event handler if changed
 }
 
 func (this *config) init () error {
@@ -143,15 +152,44 @@ func (this *config) saveUser () error {
 	defer file.Close()
 	_, err = this.data.user.WriteTo(file)
 	if err != nil { return err }
+	this.ignoreNextUserUpdate = true
 	return nil
 }
 
-func (this *config) processUserDiff (changed []string) {
-	// TODO
+func (this *config) processUserDiff (changed map[string] struct { }) {
+	for key := range changed {
+		// this is the user file, and nothing has precedence over it, so
+		// the change always matters
+		this.broadcastChange(key)
+	}
 }
 
-func (this *config) processSystemDiff (index int, changed []string) {
-	// TODO
+func (this *config) processSystemDiff (index int, changed map[string] struct { }) {
+	for key := range changed {
+		// if specified in the user file, the change doesn't matter
+		if this.data.user != nil {
+			if has, _ := this.data.user.Has(key); has {
+				continue
+			}
+		}
+		
+		// if specified in any system files with precedence greater than
+		// this one, the change doesn't matter
+		for _, system := range this.data.system[:index] {
+			if _, has := system[key]; has {
+				continue
+			}
+		}
+
+		// the change does matter
+		this.broadcastChange(key)
+	}
+}
+
+func (this *config) broadcastChange (key string) {
+	for _, listener := range this.on.change.Listeners() {
+		tomo.Do(func () { listener(key) })
+	}
 }
 
 func (this *config) get (key string, fallback Value) (Value, error) {
@@ -229,7 +267,10 @@ func (this *config) Set (key string, value Value) error {
 	if this.data.user == nil { this.data.user = NewFile() }
 	err := this.data.user.Set(key, value)
 	if err != nil { return err }
-	return this.saveUser()
+	err = this.saveUser()
+	if err != nil { return err }
+	this.broadcastChange(key)
+	return nil
 }
 
 func (this *config) Reset (key string) error {
@@ -238,7 +279,10 @@ func (this *config) Reset (key string) error {
 	if this.data.user == nil { this.data.user = NewFile() }
 	err := this.data.user.Reset(key)
 	if err != nil { return err }
-	return this.saveUser()
+	err = this.saveUser()
+	if err != nil { return err }
+	this.broadcastChange(key)
+	return nil
 }
 
 func (this *config) OnChange (callback func (string)) event.Cookie {
@@ -246,3 +290,29 @@ func (this *config) OnChange (callback func (string)) event.Cookie {
 	defer this.lock.Unlock()
 	return this.on.change.Connect(callback)
 }
+
+func diffValueMaps (first, second map[string] Value) map[string] struct { } {
+	diff := make(map[string] struct { })
+	
+	// - keys only first has
+	// - keys both have, but are different
+	for key, firstValue := range first {
+		secondValue, ok := second[key]
+		if !ok {
+			diff[key] = struct { } { }
+			continue
+		}
+		if !firstValue.Equals(secondValue) {
+			diff[key] = struct { } { }
+		}
+	}
+
+	// - keys only second has
+	for key := range second {
+		if _, has := first[key]; !has {
+			diff[key] = struct { } { }
+		}
+	}
+
+	return diff
+}

config/impl_test.go

@@ -0,0 +1,53 @@
+package config
+
+import "maps"
+import "testing"
+
+func TestDiffValueMapsNone (test *testing.T) {
+	str := `
+thing = something
+
+otherThing  = otherValue
+# comment
+otherThing = true
+otherThing = 234
+
+yetAnotherThing = 0.23498
+`
+	file1 := parseFileString(test, str)
+	file2 := parseFileString(test, str)
+	diff := diffValueMaps(file1.Map(), file2.Map())
+	if len(diff) != 0 {
+		test.Fatalf("diff not empty:\n%v", diff)
+	}
+}
+
+func TestDiffValueMaps (test *testing.T) {
+	file1 := parseFileString(test,
+`key4=0
+key1=value1
+# comment
+key2=34`)
+	file2 := parseFileString(test,
+`key1=value2
+key2=34
+# comment
+
+key3=0.2`)
+	diff := diffValueMaps(file1.Map(), file2.Map())
+	correct := map[string] struct { } {
+		"key1": struct { } { },
+		"key3": struct { } { },
+		"key4": struct { } { },
+	}
+	if !maps.Equal(diff, correct) {
+		test.Error("diffs do not match")
+		test.Errorf("EXPECTED:\n%v", correct)
+		test.Errorf("GOT:\n%v", diff)
+		test.Fail()
+	}
+}
+
+// TODO we need way more tests!
+// need to test watching files. maybe make a temp dir and do it there. remember
+// to defer cleaning up the dir and closing of the config.

go.mod

@@ -4,16 +4,17 @@ go 1.22.2
 
 require (
 	git.tebibyte.media/sashakoshka/goparse v0.2.0
-	git.tebibyte.media/tomo/backend v0.7.0
-	git.tebibyte.media/tomo/objects v0.22.0
-	git.tebibyte.media/tomo/tomo v0.46.1
+	git.tebibyte.media/tomo/backend v0.8.0
+	git.tebibyte.media/tomo/objects v0.24.0
+	git.tebibyte.media/tomo/tomo v0.48.0
 	git.tebibyte.media/tomo/xdg v0.1.0
 	github.com/fsnotify/fsnotify v1.7.0
 	golang.org/x/image v0.11.0
 )
 
 require (
-	git.tebibyte.media/tomo/typeset v0.7.1 // indirect
+	git.tebibyte.media/sashakoshka/goutil v0.3.1 // indirect
+	git.tebibyte.media/tomo/typeset v0.8.0 // indirect
 	git.tebibyte.media/tomo/xgbkb v1.0.1 // indirect
 	github.com/BurntSushi/freetype-go v0.0.0-20160129220410-b763ddbfe298 // indirect
 	github.com/BurntSushi/graphics-go v0.0.0-20160129215708-b43f31a4a966 // indirect

go.sum

@@ -1,14 +1,16 @@
 git.tebibyte.media/sashakoshka/goparse v0.2.0 h1:uQmKvOCV2AOlCHEDjg9uclZCXQZzq2PxaXfZ1aIMiQI=
 git.tebibyte.media/sashakoshka/goparse v0.2.0/go.mod h1:tSQwfuD+EujRoKr6Y1oaRy74ZynatzkRLxjE3sbpCmk=
+git.tebibyte.media/sashakoshka/goutil v0.3.1 h1:zvAMKS+aea96q6oTttCWfNLXqOHisI3IKAwX6BWKfY0=
+git.tebibyte.media/sashakoshka/goutil v0.3.1/go.mod h1:Yo/M2sbi9IbzZCFsEj8/Fg7sNwHkDaJ6saTHOha+Dow=
 git.tebibyte.media/sashakoshka/xgbkb v1.0.0/go.mod h1:pNcE6TRO93vHd6q42SdwLSTTj25L0Yzggz7yLe0JV6Q=
-git.tebibyte.media/tomo/backend v0.7.0 h1:12A+IsbwIKCmg4jKjD9xCDz+o7R3X6Yp8cZup+wOGIM=
-git.tebibyte.media/tomo/backend v0.7.0/go.mod h1:G3Kh6N2MuiAwsnuPe3h9CwWL65vmmsaqgapA38MPyhk=
-git.tebibyte.media/tomo/objects v0.22.0 h1:2t21W32HW2xvPBICqmArVMVWxg9ohhTJw6ChZ0DcdYY=
-git.tebibyte.media/tomo/objects v0.22.0/go.mod h1:f5J5tAhO+eN5glVbCJLPSopIeTylXqLgKLVAIg8iAPQ=
-git.tebibyte.media/tomo/tomo v0.46.1 h1:/8fT6I9l4TK529zokrThbNDHGRvUsNgif1Zs++0PBSQ=
-git.tebibyte.media/tomo/tomo v0.46.1/go.mod h1:WrtilgKB1y8O2Yu7X4mYcRiqOlPR8NuUnoA/ynkQWrs=
-git.tebibyte.media/tomo/typeset v0.7.1 h1:aZrsHwCG5ZB4f5CruRFsxLv5ezJUCFUFsQJJso2sXQ8=
-git.tebibyte.media/tomo/typeset v0.7.1/go.mod h1:PwDpSdBF3l/EzoIsa2ME7QffVVajnTHZN6l3MHEGe1g=
+git.tebibyte.media/tomo/backend v0.8.0 h1:mPP6g60lL7v9GOjyUl/oGkHK/CV4ZJB8OUlw0E7WEhk=
+git.tebibyte.media/tomo/backend v0.8.0/go.mod h1:yIWW8XXDsaHfIhAuxg336oYlgX0uCn3lwgaydh8BagE=
+git.tebibyte.media/tomo/objects v0.24.0 h1:O91CxHJ1eA5/WJzDNm46lTA3Lm6t1CrLtf8gLKtuX7U=
+git.tebibyte.media/tomo/objects v0.24.0/go.mod h1:atTxG2mRqDQBFS/0KoqP9VR50BozFLi7XRz/AkFJtMo=
+git.tebibyte.media/tomo/tomo v0.48.0 h1:AE21ElHwUSPsX82ZWCnoNxJFi9Oswyd3dPDPMbxTueQ=
+git.tebibyte.media/tomo/tomo v0.48.0/go.mod h1:WrtilgKB1y8O2Yu7X4mYcRiqOlPR8NuUnoA/ynkQWrs=
+git.tebibyte.media/tomo/typeset v0.8.0 h1:4qA6oW4/3oPHj6/Zrp+JFJ53OmFSDvxs+J6BhO3DW00=
+git.tebibyte.media/tomo/typeset v0.8.0/go.mod h1:PwDpSdBF3l/EzoIsa2ME7QffVVajnTHZN6l3MHEGe1g=
 git.tebibyte.media/tomo/xdg v0.1.0 h1:6G2WYPPiM2IXleCpKKHuJA34BxumwNWuLsUoX3yu5zA=
 git.tebibyte.media/tomo/xdg v0.1.0/go.mod h1:tuaRwRkyYW7mqlxA7P2+V+e10KzcamNoUzcOgaIYKAY=
 git.tebibyte.media/tomo/xgbkb v1.0.1 h1:b3HDUopjdQp1MZrb5Vpil4bOtk3NnNXtfQW27Blw2kE=

internal/icons/fallback/assets/README.md

@@ -0,0 +1,7 @@
+# assets
+These are the assets for the fallback (Wintergreen) icon set. When making edits
+to these icons, open both the png and xcf files. When you wish to save your
+changes, delete the contents of the png file and paste in the "Icons" layer of
+the xcf file, then export the png file and save the xcf file. This is because
+the exported pngs use indexed color to save space as they are embedded into
+application binaries.

internal/icons/fallback/icon.go

@@ -6,9 +6,10 @@ import _ "embed"
 import _ "image/png"
 import "git.tebibyte.media/tomo/tomo"
 import "git.tebibyte.media/tomo/tomo/data"
-import "git.tebibyte.media/tomo/nasin/internal/util"
+import "git.tebibyte.media/tomo/tomo/event"
 import "git.tebibyte.media/tomo/tomo/canvas"
 import "git.tebibyte.media/tomo/backend/style"
+import "git.tebibyte.media/tomo/nasin/internal/util"
 
 //go:embed assets/icons-small.png
 var atlasSmallBytes []byte
@@ -35,7 +36,7 @@ const (
 	iconXOfficeSpreadsheet     = tomo.Icon("x-office-spreadsheet")
 )
 
-func generateSource (data []byte, width int) map[tomo.Icon] canvas.Texture {
+func generateSource (data []byte, width int) (canvas.TextureCloser, map[tomo.Icon] canvas.Texture) {
 	atlasImage, _, err := image.Decode(bytes.NewReader(data))
 	if err != nil { panic(err) }
 	atlasTexture := tomo.NewTexture(atlasImage)
@@ -448,23 +449,26 @@ func generateSource (data []byte, width int) map[tomo.Icon] canvas.Texture {
 	col(tomo.IconWeatherSnow)
 	col(tomo.IconWeatherStorm)
 	
-	return source
+	return atlasTexture, source
 }
 
 type iconSet struct {
+	atlasSmall canvas.TextureCloser
+	atlasLarge canvas.TextureCloser
 	texturesSmall map[tomo.Icon] canvas.Texture
 	texturesLarge map[tomo.Icon] canvas.Texture
 }
 
 // New creates a new fallback icon set.
-func New () style.IconSet {
-	return new(iconSet)
+func New () (style.IconSet, event.Cookie) {
+	iconSet := new(iconSet)
+	return iconSet, iconSet
 }
 
 func (this *iconSet) ensure () {
 	if this.texturesSmall != nil { return }
-	this.texturesSmall = generateSource(atlasSmallBytes, 16)
-	this.texturesLarge = generateSource(atlasLargeBytes, 32)
+	this.atlasSmall, this.texturesSmall = generateSource(atlasSmallBytes, 16)
+	this.atlasLarge, this.texturesLarge = generateSource(atlasLargeBytes, 32)
 }
 
 func (this *iconSet) selectSource (size tomo.IconSize) map[tomo.Icon] canvas.Texture {
@@ -500,3 +504,13 @@ func (this *iconSet) MimeIcon (mime data.Mime, size tomo.IconSize) canvas.Textur
 		return source[tomo.Icon(iconApplicationXGeneric)]
 	}
 }
+
+func (this *iconSet) Close () error {
+	if this.atlasSmall != nil {
+		this.atlasSmall.Close()
+	}
+	if this.atlasLarge != nil {
+		this.atlasLarge.Close()
+	}
+	return nil
+}

internal/icons/xdg/icon.go

@@ -9,6 +9,7 @@ import "strings"
 import _ "image/png"
 import "git.tebibyte.media/tomo/tomo"
 import "git.tebibyte.media/tomo/tomo/data"
+import "git.tebibyte.media/tomo/tomo/event"
 import "git.tebibyte.media/tomo/tomo/canvas"
 import "git.tebibyte.media/tomo/backend/style"
 import "git.tebibyte.media/tomo/nasin/internal/util"
@@ -17,27 +18,27 @@ import xdgIconTheme "git.tebibyte.media/tomo/xdg/icon-theme"
 type iconTheme struct {
 	xdg xdgIconTheme.Theme
 	fallback       style.IconSet
-	texturesSmall  map[tomo.Icon] canvas.Texture
-	texturesMedium map[tomo.Icon] canvas.Texture
-	texturesLarge  map[tomo.Icon] canvas.Texture
+	texturesSmall  map[tomo.Icon] canvas.TextureCloser
+	texturesMedium map[tomo.Icon] canvas.TextureCloser
+	texturesLarge  map[tomo.Icon] canvas.TextureCloser
 }
 
-func FindThemeWarn (name string, fallback style.IconSet, path ...string) (style.IconSet, error) {
+func FindThemeWarn (name string, fallback style.IconSet, path ...string) (style.IconSet, event.Cookie, error) {
 	this := &iconTheme {
 		fallback:       fallback,
-		texturesLarge:  make(map[tomo.Icon] canvas.Texture),
-		texturesMedium: make(map[tomo.Icon] canvas.Texture),
-		texturesSmall:  make(map[tomo.Icon] canvas.Texture),
+		texturesLarge:  make(map[tomo.Icon] canvas.TextureCloser),
+		texturesMedium: make(map[tomo.Icon] canvas.TextureCloser),
+		texturesSmall:  make(map[tomo.Icon] canvas.TextureCloser),
 	}
 	
 	xdg, err := xdgIconTheme.FindThemeWarn(name, path...)
-	if err != nil { return nil, err }
+	if err != nil { return nil, nil, err }
 	this.xdg = xdg
 	
-	return this, nil
+	return this, this, nil
 }
 
-func (this *iconTheme) selectSource (size tomo.IconSize) map[tomo.Icon] canvas.Texture {
+func (this *iconTheme) selectSource (size tomo.IconSize) map[tomo.Icon] canvas.TextureCloser {
 	switch size {
 	case tomo.IconSizeMedium: return this.texturesMedium
 	case tomo.IconSizeLarge:  return this.texturesLarge
@@ -45,7 +46,7 @@ func (this *iconTheme) selectSource (size tomo.IconSize) map[tomo.Icon] canvas.T
 	}
 }
 
-func (this *iconTheme) xdgIcon (name string, size tomo.IconSize) (canvas.Texture, bool) {
+func (this *iconTheme) xdgIcon (name string, size tomo.IconSize) (canvas.TextureCloser, bool) {
 	// TODO use scaling factor instead of 1
 	// find icon file
 	icon, err := this.xdg.FindIcon(name, iconSizePixels(size), 1, xdgIconTheme.PNG)
@@ -100,7 +101,21 @@ func (this *iconTheme) MimeIcon (mime data.Mime, size tomo.IconSize) canvas.Text
 	}
 }
 
-func (this *iconTheme) icon (icon tomo.Icon, size tomo.IconSize) canvas.Texture {
+func (this *iconTheme) Close () error {
+	closeAllIn := func (mp map[tomo.Icon] canvas.TextureCloser) {
+		for _, texture := range mp {
+			if texture != nil {
+				texture.Close()
+			}
+		}
+	}
+	closeAllIn(this.texturesSmall)
+	closeAllIn(this.texturesMedium)
+	closeAllIn(this.texturesLarge)
+	return nil
+}
+
+func (this *iconTheme) icon (icon tomo.Icon, size tomo.IconSize) canvas.TextureCloser {
 	if texture, ok := this.xdgIcon(XdgIconName(icon), size); ok {
 		return texture
 	}
@@ -110,7 +125,7 @@ func (this *iconTheme) icon (icon tomo.Icon, size tomo.IconSize) canvas.Texture
 	return nil
 }
 
-func (this *iconTheme) mimeIcon (mime data.Mime, size tomo.IconSize) canvas.Texture {
+func (this *iconTheme) mimeIcon (mime data.Mime, size tomo.IconSize) canvas.TextureCloser {
 	if texture, ok := this.xdgIcon(xdgFormatMime(mime), size); ok {
 		return texture
 	}

internal/registrar/registrar_unix.go

@@ -1,10 +1,10 @@
 //go:build unix && (!darwin)
 package registrar
 
-import "os"
 import "log"
 import "git.tebibyte.media/tomo/tomo"
 import "git.tebibyte.media/tomo/backend/x"
+import "git.tebibyte.media/tomo/tomo/event"
 import "git.tebibyte.media/sashakoshka/goparse"
 import "git.tebibyte.media/tomo/nasin/internal/icons/xdg"
 import "git.tebibyte.media/tomo/nasin/internal/styles/tss"
@@ -14,6 +14,8 @@ import "git.tebibyte.media/tomo/nasin/internal/faces/fallback"
 
 type Registrar struct {
 	backend *x.Backend
+	iconSetCookie event.Cookie
+	styleCookie   event.Cookie
 }
 
 func (this *Registrar) SetBackend () (tomo.Backend, error) {
@@ -24,38 +26,50 @@ func (this *Registrar) SetBackend () (tomo.Backend, error) {
 	return backend, nil
 }
 
-func (this *Registrar) SetTheme () error {
-	styleSheetName := os.Getenv("TOMO_STYLE_SHEET")
-	if styleSheetName != "" {
-		styl, _, err := tss.LoadFile(styleSheetName)
+func (this *Registrar) SetStyle (name string) error {
+	if this.styleCookie != nil {
+		this.styleCookie.Close()
+		this.styleCookie = nil
+	}
+
+	if name != "" {
+		styl, cookie, err := tss.LoadFile(name)
 		if err == nil {
 			this.backend.SetStyle(styl)
+			this.styleCookie = cookie
 			return nil
 		} else {
 			log.Printf (
 				"nasin: could not load style sheet '%s'\n%v",
-				styleSheetName, parse.Format(err))
+				name, parse.Format(err))
 		}
 	}
 	
-	styl, _ := fallbackStyle.New()
+	styl, cookie := fallbackStyle.New()
+	this.styleCookie = cookie
 	this.backend.SetStyle(styl)
 	return nil
 }
 
-func (this *Registrar) SetIconSet () error {
-	iconSet := fallbackIcons.New()
-	iconSetName := os.Getenv("TOMO_XDG_ICON_THEME")
-	if iconSetName != "" {
-		xdgIconSet, err := xdgIcons.FindThemeWarn(iconSetName, iconSet)
+func (this *Registrar) SetIconSet (name string) error {
+	if this.iconSetCookie != nil {
+		this.iconSetCookie.Close()
+		this.iconSetCookie = nil
+	}
+	
+	iconSet, cookie := fallbackIcons.New()
+	if name != "" {
+		xdgIconSet, xdgCookie, err := xdgIcons.FindThemeWarn(name, iconSet)
+		cookie = event.MultiCookie(cookie, xdgCookie)
 		if err == nil {
 			iconSet = xdgIconSet
 		} else {
-			log.Printf("nasin: could not load icon theme '%s': %v", iconSetName, err)
+			log.Printf("nasin: could not load icon theme '%s': %v", name, err)
 		}
 	}
 	
 	this.backend.SetIconSet(iconSet)
+	this.iconSetCookie = cookie
 	return nil
 }
 

internal/styles/aluminum/aluminum.tss

@@ -198,10 +198,6 @@ $BorderOuterShadow    = #a4afc0                        ;
 	Color:   #0000;
 }
 
-*.MenuItem[hovered] {
-	Color: $ColorDot;
-}
-
 *.MenuItem[focused] {
 	Color: $ColorDot;
 }
@@ -218,10 +214,6 @@ $BorderOuterShadow    = #a4afc0                        ;
 	Border: $BorderTearPad / 3, $BorderTear / 1;
 }
 
-*.TearLine[hovered] {
-	Border: $BorderTearPadFocused / 3, $BorderTearFocused / 1;
-}
-
 *.TearLine[focused] {
 	Border: $BorderTearPadFocused / 3, $BorderTearFocused / 1;
 }

internal/styles/fallback/wintergreen.go

@@ -1,6 +1,5 @@
 package fallbackStyle
 
-import "io"
 import "bytes"
 import "image"
 import _ "embed"
@@ -47,12 +46,6 @@ var borderColorShade    = [4]color.Color { colorShade,       colorShade,     col
 //go:embed assets/atlas.png
 var atlasBytes []byte
 
-type closerCookie struct { io.Closer }
-func (cookie closerCookie) Close () { cookie.Closer.Close() }
-func newCloserCookie (closer io.Closer) event.Cookie {
-	return closerCookie { Closer: closer }
-}
-
 // New returns Wintergreen, the default Tomo style. It is neutral-gray with
 // green and turquoise accents.
 func New () (*style.Style, event.Cookie) {
@@ -66,7 +59,7 @@ func New () (*style.Style, event.Cookie) {
 	textureHandleVertical   := atlasTexture.SubTexture(image.Rect(28,  0, 29,  2))
 	textureHandleHorizontal := atlasTexture.SubTexture(image.Rect(28,  0, 30,  1))
 
-	cookie := event.MultiCookie(newCloserCookie(atlasTexture))
+	cookie := event.MultiCookie(atlasTexture)
 
 rules := []style.Rule {
 	// *.*
@@ -152,26 +145,12 @@ rules := []style.Rule {
 		tomo.AGap(0, 0),
 	), tomo.R("", "NumberInput")),
 
-	// *.Container[sunken]
+	// *.Root
 	style.Ru(style.AS (
-		tomo.ABorder (
-			outline,
-			tomo.Border {
-				Width: tomo.I(1, 0, 0, 1),
-				Color: borderColorEngraved,
-			}),
-		tomo.AColor(tomo.ColorSunken),
-		// tomo.ATexture(textureCorkboard),
-		tomo.APadding(8),
-	), tomo.R("", "Container"), "sunken"),
+		tomo.AGap(0, 0),
+	), tomo.R("", "Root")),
 
-	// *.Container[outer]
-	style.Ru(style.AS (
-		tomo.AttrColor { Color: tomo.ColorBackground },
-		tomo.AttrPadding(tomo.I(8)),
-	), tomo.R("", "Container"), "outer"),
-
-	// *.Container[menu]
+	// *.Root[menu]
 	style.Ru(style.AS (
 		tomo.AttrBorder {
 			outline,
@@ -182,7 +161,38 @@ rules := []style.Rule {
 		},
 		tomo.AttrColor { Color: tomo.ColorBackground },
 		tomo.AttrGap { },
-	), tomo.R("", "Container"), "menu"),
+	), tomo.R("", "Root"), "menu"),
+
+	// *.Pegboard
+	style.Ru(style.AS (
+		tomo.ABorder (
+			outline,
+			tomo.Border {
+				Width: tomo.I(1, 0, 0, 1),
+				Color: borderColorEngraved,
+			}),
+		tomo.AColor(tomo.ColorSunken),
+		// tomo.ATexture(textureCorkboard),
+		tomo.APadding(8),
+	), tomo.R("", "Pegboard")),
+
+	// *.Segment
+	style.Ru(style.AS (
+		tomo.AttrBorder {
+			tomo.Border {
+				Width: tomo.I(1),
+				Color: borderColorLifted,
+			},
+		},
+		tomo.AttrColor { Color: tomo.ColorBackground },
+		tomo.AttrPadding(tomo.I(8)),
+	), tomo.R("", "Segment")),
+
+	// *.Segment[option]
+	style.Ru(style.AS (
+		tomo.AttrColor { Color: tomo.ColorSunken },
+		tomo.AttrPadding(tomo.I(8)),
+	), tomo.R("", "Segment"), "option"),
 
 	// *.Heading
 	style.Ru(style.AS (
@@ -369,11 +379,6 @@ rules := []style.Rule {
 	style.Ru(style.AS (
 		tomo.AttrColor { Color: tomo.ColorAccent },
 	), tomo.R("", "MenuItem"), "focused"),
-	
-	// *.MenuItem[hovered]
-	style.Ru(style.AS (
-		tomo.AttrColor { Color: tomo.ColorAccent },
-	), tomo.R("", "MenuItem"), "hovered"),
 
 	// *.File
 	style.Ru(style.AS (
@@ -410,16 +415,6 @@ rules := []style.Rule {
 			},
 		},
 	), tomo.R("", "TearLine"), "focused"),
-
-	// *.TearLine[hovered]
-	style.Ru(style.AS (
-		tomo.AttrBorder {
-			tomo.Border {
-				Width: tomo.I(3),
-				Color: borderColorFocused,
-			},
-		},
-	), tomo.R("", "TearLine"), "hovered"),
 	
 	// *.Calendar
 	style.Ru(style.AS (
@@ -460,11 +455,6 @@ rules := []style.Rule {
 		tomo.AttrColor { Color: colorCalendarWeekend },
 	), tomo.R("", "CalendarDay"), "weekend"),
 	
-	// *.TabbedContainer
-	style.Ru(style.AS (
-		tomo.AGap(0, 0),
-	), tomo.R("", "TabbedContainer")),
-	
 	// *.TabRow
 	style.Ru(style.AS (
 		tomo.AttrBorder {

internal/styles/tss/build.go

@@ -1,7 +1,6 @@
 package tss
 
 import "os"
-import "io"
 import "fmt"
 import "image"
 import "errors"
@@ -81,7 +80,7 @@ func (this *styleBuilder) build () (*style.Style, event.Cookie, error) {
 
 	// add each texture to the cookies list
 	for _, texture := range this.textures {
-		cookies = append(cookies, closerCookie { Closer: texture })
+		cookies = append(cookies, texture)
 	}
 	
 	return sty, event.MultiCookie(cookies...), nil
@@ -398,10 +397,3 @@ func copyBorderValue[T any, U ~[]T] (destination, source U) bool {
 		return false
 	}
 }
-
-type closerCookie struct {
-	io.Closer
-}
-func (cookie closerCookie) Close () {
-	cookie.Closer.Close()
-}

manager.go

@@ -7,11 +7,6 @@ var manager struct {
 	count int
 }
 
-type funcCookie func ()
-func (cookie funcCookie) Close () {
-	cookie()
-}
-
 // WaitFor ensures that the application will stay running while the given window
 // is open.
 func WaitFor (window tomo.Window) event.Cookie {
@@ -27,7 +22,12 @@ func WaitFor (window tomo.Window) event.Cookie {
 		}
 	}
 
+	handleWaitClose := func () error {
+		handleClose();
+		return nil
+	}
+
 	return event.MultiCookie (
 		window.OnClose(handleClose),
-		funcCookie(handleClose))
+		event.FuncCookie(handleWaitClose))
 }

path.go

@@ -11,8 +11,9 @@ func ApplicationUserDataDir (app ApplicationDescription) (string, error) {
 }
 
 // ApplicationSystemDataDirs returns a list of directory paths where an
-// application can look for its system-level data files. These directories may
-// or may not exist. This function may return an empty slice on some platforms.
+// application can look for its system-level data files. Directories returned
+// by this function may or may not actually exist. This function may return an
+// empty slice on some platforms.
 func ApplicationSystemDataDirs (app ApplicationDescription) ([]string, error) {
 	return systemDirs(app.ID, systemDataDirs)
 }
@@ -24,9 +25,9 @@ func ApplicationUserConfigDir (app ApplicationDescription) (string, error) {
 }
 
 // ApplicationSystemDataDirs returns a list of directory paths where an
-// application can look for its system-level configuration files. These
-// directories may or may not exist. This function may return an empty slice on
-// some platforms.
+// application can look for its system-level configuration files. Directories
+// returned by this function may or may not actually exist. This function may
+// return an empty slice on some platforms.
 func ApplicationSystemConfigDirs (app ApplicationDescription) ([]string, error) {
 	return systemDirs(app.ID, systemConfigDirs)
 }