From 8b4c55e2fb9f3c7431261e74621af29e54adaa16 Mon Sep 17 00:00:00 2001 From: Kyle Bowman Date: Sat, 11 Jan 2025 15:43:25 -0500 Subject: [PATCH] plan tables and consider cli implications --- cli.md | 14 +++++++++-- tables.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+), 2 deletions(-) create mode 100644 tables.md diff --git a/cli.md b/cli.md index cc48e0f..89fabc5 100644 --- a/cli.md +++ b/cli.md @@ -10,6 +10,7 @@ Separate by things that act on `feed` and things that act on `entry`. 2. Remove feed from feed list. 3. List (unread) entries from feed list. + ## Feed Actions Feed options: @@ -75,11 +76,20 @@ Needs to pull CSS as well as HTML. Or, define your own styling... ## Filters -**Remember** Feed filters are not necessarily the same as entry filters. - **Remember**, you can always `grep` as a way of filtering rows. You can always `cut` as a way of filtering columns. +This requires a good deal of CLI design. + +* Do I want to specify entry/feed number as positional arguments? Do I want to + specify them as a filter? + * Maybe "filter" is the wrong term. Maybe "selector" is better. And I don't + see why number should be any different than any other selector. + * If we use the notion of selectors, how do we handle and/or/not? +* Since entry filters ~= feed filters, do I want to put the filters on each + command (ex: `nom entry show [filters]`) or do I want to put them on `entry` + and `show` (ex: `nom entry [filters] show`)? + Hmm... It would be cool to batch update using filters. For example, ``` bash diff --git a/tables.md b/tables.md new file mode 100644 index 0000000..aecebf1 --- /dev/null +++ b/tables.md @@ -0,0 +1,75 @@ +# Tables + +Nom needs to maintain state, such as what feeds are you tracking, what aliases +you have associated with each feed, what entries, you have read, and so on. +This page specs out the design of tables that manage that information. + +For simplicity, transparency, and portability, we will start with file-based +IO. Something like CSV format. If performance becomes an issue, we can switch +to a SQLite database or something like that. + +## Feed List + +A feed list curates which feeds to poll. At its most basic, it contains a URL. +But some additional metadata could be helpful too. + +| Feed Number | URL | Alias | ... | +| ------------| -------------------- | ----- | --- | +| 1 | https://url/to/feed1 | feed1 | ... | +| 2 | https://url/to/feed2 | feed2 | ... | + +For now, let's focus on URLs and Aliases: + +1. A URL is an unambiguous specification to a feed. +2. An alias is a user-specified handle for a feed. It's helpful in commands + when you need to reference a feed, but don't want to type the entire URL. + +## Entry List + +An entry list is more involved than a feed list because it considers state, +such as whether or not an entry has been viewed or not. + +| Entry Number | Feed Url | Feed Alias | Url | Date (Updated) | Summary | Viewed | +| ------------ | -------------------- | ---------- | --------------------- | -------------- | ------- | ------ | +| 1 | https://url/to/feed1 | feed1 | https://url/to/entry1 | ISO-8601 | This entry expands upon this summary! | True | +| 2 | https://url/to/feed1 | feed1 | https://url/to/entry2 | ISO-8601 | This entry's for another summary! | False | + +There are three scenarios that determine whether an entry shows up in our +reading list or not: + +1. The entry is not in the entry list. (It does NOT appear in our reading list.) +2. The entry is in our list; it is marked "viewed." (It does NOT appear + in our reading list.) +3. The entry is in our list; it is marked "unviewed". (It appears in our + reading list.) + +You might think, "Great! we could just delete an entry from the entry list +when we have read the article!" But the usual way to create an entry list is +to read one or more feeds and add items to the entry list. If we simply remove +an item, it will reappear when we update the list. So we need to keep a record +of the entry (at least until it has been dropped from the feed's buffer). + +## Feed/Entry Number + +Sometimes you need to interact with a single feed or entry. Feeds have aliases, +which make sense because you will interact with the same feed many times over +the course of its lifetime. Entries, however, are short-lived. Adding an alias +to an entry isn't generally worth it. This is where the entry number comes into +play. + +Whenever you need to specify an individual entry, you can do so by specifying +its entry number. Think of an entry number as an *ad hoc* alias. For example, +consider the entry list from earlier. Then + +`nom entry mark viewed 1` + +is equivalent to + +`nom entry mark viewed https://url/to/entry1`. + +**NOTE:** An entry number is subject to change whenever the number of entries +changes. Before performing an operation, ensure that the entry number aligns +with the entry that you *think* that you are operatingon. + +As entries are added to the entry list, you use up more entry numbers. As +entries are removed from the entry list, you reclaim entry numbers. \ No newline at end of file -- 2.39.5