tests pass; tagging release

README.adoc

@@ -0,0 +1,133 @@
+= gokwallet
+Brent Saner <bts@square-r00t.net>
+:doctype: book
+:docinfo: shared
+:data-uri:
+:imagesdir: images
+:sectlinks:
+:sectnums:
+:sectnumlevels: 7
+:toc: preamble
+:toc2: left
+:idprefix:
+:toclevels: 7
+:source-highlighter: rouge
+
+image::https://pkg.go.dev/badge/r00t2.io/gokwallet.svg[link="https://pkg.go.dev/r00t2.io/gokwallet"]
+
+Package `gokwallet` serves as a Golang interface to KDE's https://utils.kde.org/projects/kwalletmanager/[KWallet^].
+
+Note that to use this library, the running machine must have both Dbus and kwalletd running.
+
+Relatedly, note also that this library interfaces with kwalletd. KWallet is in the process of moving to libsecret/SecretService
+(see https://bugs.kde.org/show_bug.cgi?id=313216[here^] and https://invent.kde.org/frameworks/kwallet/-/merge_requests/11[here^]),
+thus replacing kwalletd. While there is a pull request in place, it has not yet been merged in (and it may be a while before downstream distributions incorporate that version). However, when that time comes I highly recommend using my `gosecret` library to interface with that (module https://pkg.go.dev/r00t2.io/gosecret[`r00t2.io/gosecret`^]).
+
+== KWallet Concepts
+
+For reference, KWallet has the following structure (modified slightly to reflect this library):
+
+* A main Dbus service interface ("org.kde.kwalletd5"), `WalletManager`, allows one to retrieve and operate on/with `Wallet` items.
+
+* One or more `Wallet` items allow one to retrieve and operate on/with `Folder` items.
+
+* One or more `Folder` items allow one to retrieve and operate on/with `Passwords`, `Maps`, `BinaryData`, and `UnknownItem` `WalletItem` items.
+
+Thus, the hierarchy (as exposed by this library) looks like this:
+
+----
+WalletManager
+├─ Wallet "A"
+│	├─ Folder "A_1"
+│	│	├─ Passwords
+│	│	│	├─ Password "A_1_a"
+│	│	│	└─ Password "A_1_b"
+│	│	├─ Maps
+│	│	│	├─ Map "A_1_a"
+│	│	│	└─ Map "A_1_b"
+│	│	├─ BinaryData
+│	│	│	├─ Blob "A_1_a"
+│	│	│	└─ Blob "A_1_b"
+│	│	└─ Unknown
+│	│		├─ UnknownItem "A_1_a"
+│	│		└─ UnknownItem "A_1_b"
+│	└─ Folder "A_2"
+│		├─ Passwords
+│		│	├─ Password "A_2_a"
+│		│	└─ Password "A_2_b"
+│		├─ Maps
+│		│	├─ Map "A_2_a"
+│		│	└─ Map "A_2_b"
+│		├─ BinaryData
+│		│	├─ Blob "A_2_a"
+│		│	└─ Blob "A_2_b"
+│		└─ Unknown
+│			├─ UnknownItem "A_2_a"
+│			└─ UnknownItem "A_2_b"
+└─ Wallet "B"
+    └─ Folder "B_1"
+        ├─ Passwords
+        │	├─ Password "B_1_a"
+        │	└─ Password "B_1_b"
+        ├─ Maps
+        │	├─ Map "B_1_a"
+        │	└─ Map "B_1_b"
+        ├─ BinaryData
+        │	├─ Blob "B_1_a"
+        │	└─ Blob "B_1_b"
+        └─ Unknown
+            ├─ UnknownItem "B_1_a"
+            └─ UnknownItem "B_1_b"
+----
+
+This is an approximation, but should show a relatively accurate representation of the model.
+Note that most systems are likely to only have a single wallet, "kdewallet".
+
+== Usage
+
+Full documentation can be found via inline documentation.
+Additionally, use either https://pkg.go.dev/r00t2.io/gokwallet or https://pkg.go.dev/golang.org/x/tools/cmd/godoc (or `go doc`) in the source root.
+
+You most likely do *not* want to call any New<object> function directly;
+NewWalletManager with its RecurseOpts parameter (`recursion`) should get you everything you want/need.
+
+Here's a quick demonstration:
+
+[source,go]
+----
+package main
+
+import (
+	`fmt`
+	`log`
+
+	`r00t2.io/gokwallet`
+)
+
+func main() {
+
+	var err error
+	var r *gokwallet.RecurseOpts
+	var wm *gokwallet.WalletManager
+	var w *gokwallet.Wallet
+	var f *gokwallet.Folder
+	var p *gokwallet.Password
+
+	r = gokwallet.DefaultRecurseOpts
+	r.AllWalletItems = true
+
+	if wm, err = gokwallet.NewWalletManager(r, "ExampleKWalletApplication"); err != nil {
+		log.Panicln(err)
+	}
+
+	w = wm.Wallets["kdewallet"]
+
+	f = w.Folders["Passwords"]
+
+	if p, err = f.WritePassword("test_password", "this is a test password"); err != nil {
+		log.Panicln(err)
+	}
+
+	fmt.Println(p.Value)
+}
+----