;ui: notes (#1387)

hledger-ui/Hledger/UI/Main.hs

@@ -70,28 +70,55 @@ runBrickUi uopts@UIOpts{cliopts_=copts@CliOpts{inputopts_=_iopts,reportspec_=rsp
 
   let
 
-    -- depth: is a bit different from other queries. In hledger cli,
-    -- - reportopts{depth_} indicates --depth options
-    -- - reportopts{query_} is the query arguments as a string
-    -- - the report query is based on both of these.
-    -- For hledger-ui, for now, move depth: arguments out of reportopts{query_}
-    -- and into reportopts{depth_}, so that depth and other kinds of filter query
-    -- can be displayed independently.
+    -- hledger-ui's query handling is currently in flux, mixing old and new approaches.
+    -- Related: #1340, #1383, #1387. Some notes and terminology:
+
+    -- The *startup query* is the Query generated at program startup, from
+    -- command line options, arguments, and the current date. hledger CLI
+    -- uses this.
+
+    -- hledger-ui/hledger-web allow the query to be changed at will, creating
+    -- a new *runtime query* each time.
+
+    -- The startup query or part of it can be used as a *constraint query*,
+    -- limiting all runtime queries. hledger-web does this with the startup
+    -- report period, never showing transactions outside those dates.
+    -- hledger-ui does not do this.
+
+    -- A query is a combination of multiple subqueries/terms, which are
+    -- generated from command line options and arguments, ui/web app runtime
+    -- state, and/or the current date.
+
+    -- Some subqueries are generated by parsing freeform user input, which
+    -- can fail. We don't want hledger users to see such failures except:
+
+    -- 1. at program startup, in which case the program exits
+    -- 2. after entering a new freeform query in hledger-ui/web, in which case
+    --    the change is rejected and the program keeps running
+
+    -- So we should parse those kinds of subquery only at those times. Any
+    -- subqueries which do not require parsing can be kept separate. And
+    -- these can be combined to make the full query when needed, eg when
+    -- hledger-ui screens are generating their data. (TODO)
+
+    -- hledger-ui provides special UI for controlling different parts of the query.
+    -- Eg the number/+/- keys for depth, the shift-up/down/left/right keys
+    -- for report period (date), the R and UPC keys for toggling realness
+    -- and status filters, and the / key for entering extra freeform query terms.
+    -- We generally store and show these parts separately, since it's cleaner
+    -- and less redundant/conflicting not to have date: and depth: terms in 
+    -- the query text users edit with the / key.
+
     uopts' = uopts{
       cliopts_=copts{
          reportspec_=rspec{
-            rsQuery=filteredQuery $ rsQuery rspec, -- as in ReportOptions, with same limitations
+            rsQuery=filteredQuery $ rsQuery rspec,  -- query with depth/date parts removed
             rsOpts=ropts{
-               -- incorporate any depth: query args into depth_,
-               -- any date: query args into period_
-               depth_ =queryDepth $ rsQuery rspec,
-               period_=periodfromoptsandargs,
-               -- always disable boring account name eliding, unlike the CLI, for a more regular tree
-               no_elide_=True,
-               -- flip the default for items with zero amounts, show them by default
-               empty_=not $ empty_ ropts,
-               -- show historical balances by default, unlike the CLI
-               balancetype_=HistoricalBalance
+               depth_ =queryDepth $ rsQuery rspec,  -- query's depth part
+               period_=periodfromoptsandargs,       -- query's date part
+               no_elide_=True,  -- avoid squashing boring account names, for a more regular tree (unlike hledger)
+               empty_=not $ empty_ ropts,  -- show zero items by default, hide them with -E (unlike hledger)
+               balancetype_=HistoricalBalance  -- show historical balances by default (unlike hledger)
                }
             }
          }