path: root/configreader.vala

// What follows is arguably the least readily understandable part of
// weltschmerz; some pointers and design notes shall follow.
//
// The purpose of this class is to read the key-value configuration file from
// disk and turn it into an in-memory representation of GLib's KeyFile
// structure. We do not stray from this format, yet the error handling and some
// design implications make it a bit harder than *just* parsing a file.
//
// In particular, a core design decision is to provide reasonable defaults to
// the user and to, wherever possible, fall back to a configuration that is at
// least useable. Short of a bug in GLib's KeyFile implementation, this code
// *should* gracefully deal with any sort of input: a missing configuration
// file, a corrupted or wrongly encoded configuration file, etc.
//
// Another decision is to report any noteworthy error to the user, and to make
// sure that issues with the configuration file are reported as accurately as
// possible. This includes particularly the reporting of entries that were
// *not* accessed by the program at all, which can indicate a small oversight
// like a typo, or a deprecated config entry.
//
// Most of the information in this file based on the official documentation,
// but a few parts (the ones there is no documentation for) are based on my
// reading of the GLib C code and live testing. Therefore, I cannot guarantee
// complete accuracy.
//
// Notable GLib resources:
// https://valadoc.org/glib-2.0/GLib.KeyFile.html
// https://valadoc.org/glib-2.0/GLib.KeyFileError.html

class ConfigReader {
	KeyFile keyfile = new KeyFile();
	string[] warnings;

	public ConfigReader (string path) {
		try {
			keyfile.load_from_file(path, NONE);
		} catch (Error e) {
			// The GLib documentation does not make this clear, but the only
			// KeyFileErrors that will be reported when loading the file from
			// disk are KeyFileError.PARSE and KeyFileError.UNKNOWN_ENCODING
			//
			// KeyFileError.NOT_FOUND will never be returned, FileError.NOENT
			// takes its place instead. Since we can gracefully fall back to
			// default values, we specifically ignore this error.
			if (e is FileError.NOENT)
				return;

			// We want to warn the user about any other error, and set keyfile
			// to null.  At this point the file has already been fully parsed
			// by GLib, but we do not trust it to have read anything correctly
			// at this point, so we destroy the in-memory representation.
			append_warning(e.message);
			keyfile = null;
		}
	}

	public string[] get_warnings() {
		return warnings;
	}

	void append_warning(string message) {
		warning(message);
		warnings += "• " + Markup.escape_text(message);
	}

	// This method is called from all three read_* methods if they encountered
	// any KeyFileErrors whilst accessing keys in keyfile. At this point, the
	// following KeyFileErrors are possible: INVALID_VALUE, UNKNOWN_ENCODING,
	// KEY_NOT_FOUND, and GROUP_NOT_FOUND.
	//
	// The latter two are insignificant since we can fall back to default
	// values.
	//
	// INVALID_VALUE is treated specially here to remove a potentially
	// confusing warning message about unknown keys (see log_unknown_keys).
	//
	// Finally, UNKNOWN_ENCODING is treated normally.
	void handle_error(KeyFileError e, string group, string key) {
		if (e is KeyFileError.INVALID_VALUE) {
			try {
				// Remove a known key with an invalid value
				keyfile.remove_key(group, key);
			} catch (KeyFileError e) {
				debug("Could not remove existing and valid key entry");
			}
		} else if (e is KeyFileError.UNKNOWN_ENCODING) {
			append_warning(e.message);
		}
	}

	// In order to keep track of entries that were not accessed by the program
	// at all, we remove all successfully read entries from the KeyFile. Any
	// entries that are left over have not been used and can then be reported
	// to the user.
	public void log_unknown_keys() {
		if (keyfile == null)
			return;

		string[] keys = {};
		try {
			foreach(var group in keyfile.get_groups()) {
				foreach(var key in keyfile.get_keys(group)) {
					keys += string.join(".", group, key);
				}
			}
		} catch (KeyFileError e) {}

		if (keys.length > 0) {
			var keylist = string.joinv(", ", keys);
			// TRANSLATORS: %s is the list of unknown keys joined with ', '
			var warning = ngettext("unknown key in config: %s",
								   "unknown keys in config: %s", keys.length).printf(keylist);

			append_warning(warning);
		}
	}

	public string? read_string(string group, string key, string? default) {
		if (keyfile == null)
			return default;

		try {
			string str = keyfile.get_string(group, key);
			keyfile.remove_key(group, key);
			return str;
		} catch (KeyFileError e) {
			handle_error(e, group, key);
			return default;
		}
	}

	public int? read_integer(string group, string key, int? default) {
		if (keyfile == null)
			return default;

		try {
			int integer = keyfile.get_integer(group, key);
			keyfile.remove_key(group, key);
			return integer;
		} catch (KeyFileError e) {
			handle_error(e, group, key);
			return default;
		}
	}

	public bool? read_boolean(string group, string key, bool? default) {
		if (keyfile == null)
			return default;

		try {
			bool boolean = keyfile.get_boolean(group, key);
			keyfile.remove_key(group, key);
			return boolean;
		} catch (KeyFileError e) {
			handle_error(e, group, key);
			return default;
		}
	}

	public Gdk.RGBA? read_colour(string group, string key, string? default) {
		string str = read_string(group, key, default);

		if (str == null)
			return null;

		var rgba = Gdk.RGBA();
		if (!rgba.parse(str)) {
			// TRANSLATORS: First %s is parsed colour, %s.%s is <group>.<key> from the config file
			append_warning(_("invalid colour '%s' in %s.%s").printf(str, group, key));

			rgba.parse(default);
			return rgba;
		}

		return rgba;
	}

	public Vte.CursorShape read_cursor(string group, string key, string default) {
		string cursor = read_string(group, key, default);

		switch (cursor) {
			case "block":
				return BLOCK;
			case "beam":
				return IBEAM;
			case "underline":
				return UNDERLINE;
			default:
				// TRANSLATORS: First %s is parsed shape, %s.%s is <group>.<key> from the config file
				append_warning(_("invalid cursor shape '%s' in %s.%s").printf(cursor, group, key));
				return BLOCK;
		}
	}

	public Vte.CursorBlinkMode read_blink(string group, string key, string default) {
		string blink = read_string(group, key, default);

		switch(blink) {
			case "true":
				return ON;
			case "false":
				return OFF;
			case "system":
				return SYSTEM;
			default:
				// TRANSLATORS: First %s is parsed blink setting, %s.%s is <group>.<key> from the config file
				append_warning(_("invalid cursor blink setting '%s' in %s.%s").printf(blink, group, key));
				return SYSTEM;
		}
	}
}