Introduce XDG base directories built-in support in calc v3

[ccjmne]

As discussed in #195, I propose here to adhere to the XDG Base Directory specification if the user has adequately set the corresponding variables.

TL;DR:

In this implementation, the XDG_XXX environment variables are used to derive the CALCPATH, CALCRC, and CALCHISTFILE when:

• these calc-specific variables are unset, and
• the XDG paths are usable

Windows

I read up a bit on the topic of support for Windows and it seems that the problem isn't all that easy, considering that %APPDATA% and other directories seem to be well-established there. I'm frankly quite like a fish out of water when it comes to Windows, and figured I would simply disregard anything XDG on that platform, see 0ffa8aa.

We may just choose to not pull in that specific commit: I suppose that if some Windows users have set up all their XDG variables, they likely do want them to be used... I merely am not confident enough with that platform to make any semblance of educated guess.

History file

I took the liberty of automatically creating the directory structure that will point to the history file, so as to preserve the out-of-the-box experience that's well-established with calc, where the history is preserved between sessions; see 0af5e3a.

The crucial point here is that where the previous default ~/.calc_history would always point to a directory that exists, the user's home; the new $XDG_STATE_HOME/calc/history would certainly not.

This file is the only one that calc needs to create itself and would result in degraded functionality without some extra set-up from the user: I believe that this basis being covered covers all the bases that need covering :-)

Testing

A quick test I used for myself was essentially as follows:

mkdir -p /tmp/calc-xdg/{config,data,state}
env -u CALCPATH                          \
    -u CALCRC                            \
    -u CALCHISTFILE                      \
    XDG_CONFIG_HOME=/tmp/calc-xdg/config \
    XDG_DATA_HOME=/tmp/calc-xdg/data     \
    XDG_STATE_HOME=/tmp/calc-xdg/state   \
    ./calc -q 'calcpath()'

I don't recommend that simply running the test be a sufficient validation, I'm only offering some bit that I found was handy for exploration :-)

Disclaimer

I tried pretty hard to adhere to the style of the code base, but my C is very rusty and was never to a professional level in the first place.

I'm truly grateful that I get to contribute, and would have no problem changing anything: don't hesitate to share any concern or preference you may have, I would love to know better.

[lcn2]

Looks good, @ccjmne

I tried pretty hard to adhere to the style of the code base, but my C is very rusty and was never to a professional level in the first place.

You did very well, @ccjmne 👍

We plan to make a mini tweak or 2, as we have an opportunity to "sneek" this into a new calc version 2.17.0.0 as well.

Stay tuned as we tweak your PR (which happens to be a nice round number 200 😉).

[lcn2]

We will need to update calc.man accordingly too.

Stay tuned ...

[lcn2]

To test without installing:

mkdir -p /tmp/calc-xdg/{config,data,state}
env -u CALCPATH                          \
    -u CALCRC                            \
    -u CALCHISTFILE                      \
    XDG_CONFIG_HOME=/tmp/calc-xdg/config \
    XDG_DATA_HOME=/tmp/calc-xdg/data     \
    XDG_STATE_HOME=/tmp/calc-xdg/state   \
    LD_LIBRARY_PATH=. \
    DYLD_LIBRARY_PATH=. \
    CALCHELP=./help \
    CALCCUSTOMHELP=./custom
    ./calc -q 'calcpath()'

This PR #200 passes the above test as well as the calc regression test:

mkdir -p /tmp/calc-xdg/{config,data,state}
env -u CALCPATH                          \
   -u CALCRC                            \
   -u CALCHISTFILE                      \
   XDG_CONFIG_HOME=/tmp/calc-xdg/config \
   XDG_DATA_HOME=/tmp/calc-xdg/data     \
   XDG_STATE_HOME=/tmp/calc-xdg/state   \
   LD_LIBRARY_PATH=. \
   DYLD_LIBRARY_PATH=. \
   CALCHELP=./help \
   CALCCUSTOMHELP=./custom
   ./calc -q 'read regress.cal'

[lcn2]

We need to tweak the calc man page, as per GH pullrequestreview-4260884475 before we push a commit onto this nice PR #200.

However, it is late, and so we will try this when we are not sleepy 😴

[ccjmne]

Good catches! I think we missed these two:

-                    .:./cal:${XDG_DATA_HOME}/calc:$XDG_CONFIG_HOME/calc:${CALC_SHAREDIR}:${CUSTOMCALDIR}
+                    .:./cal:${XDG_DATA_HOME}/calc:${XDG_CONFIG_HOME}/calc:${CALC_SHAREDIR}:${CUSTOMCALDIR}

-        $XDG_STATE_HOME and uses $XDG_STATE_HOME/calc/history
+        $XDG_STATE_HOME and uses ${XDG_STATE_HOME}/calc/history

... which may be better surrounded with ${} as well: I re-committed your change with this addition, I hope you won't mind: https://github.com/lcn2/calc/compare/f4771878232306e6c56e5a7f18020300f00b01d6..a02eaa7ccec3418321027a888b3ecbc6a7c322ca

--

I'm going over Beej's Guide to C Programming and a few other resources, while playing around on my own... and already having my mind blown: I can "instantiate" a sparse struct by specifying the "subobject to initialise", (struct person) { .name = "Éric" }?! Toying with -Wpedantic, it seems that's been well-established since c99. Welp; that's already more syntactic sugar for "objects" than even Java gets ;-)

And creating X11 windows is that simple? I've got first-class libraries for everything enormously many things! "Duh", right? And yet, wow. The libraries' docs are already here, browsable via man 3, and at least the standard ones are pretty stellar, too.

And people have come up with creative ways to work out the more tricky bits...

• "arena" allocation, brilliant (in some cases)!
• Valgrind? I vaguely recall this being incomprehensibly finicky and dense back in my University days, but maybe some decades of looking at stack traces squashed these uncertainties away: what a bliss.

I'm not saying I'll soon contribute anything of any interest to the IOCCC, but I'm definitely having a blast taking my "first steps" (for the second time) in C ;-)

[ccjmne]

If we're gonna "sneak" that into calc v2, I think we should consider favouring the "legacy" default CALCHISTFILE location, ~/.calc_history, if XDG_STATE_HOME is set and valid (points to an existing, writable directory), but ~/.calc_history already exists: as the code currently works, I believe that users would lose their previous history when upgrading, which is inappropriate.

Well, no data would actually be lost, they could still simply mv ~/.calc_history $XDG_STATE_HOME/calc; maybe making that note would be sufficient? I'll look into rather implementing the consideration above first—but maybe the note would still be a very interesting thing to have.

(I'm assuming there's no explicit CALCHISTFILE configured by the user, and that there's no XDG_STATE_HOME/calc/history either)

[ccjmne]

Hey @lcn2,

I went ahead and implemented the gymnastics I alluded to above, whereby we'd favour preserving a preexisting ~/.calc_history rather than blindly using the XDG Base Dirs, if they're configured.

I think it'll probably make for the smoothest transition: I believe the intersection of users that are interested in organising their configurations according to that spec but have no time to stop and investigate what is going on whenever a tool they use for work isn't behaving like it used to it far from empty.

I made sure to document what is going on, so that even the longstanding users that would now choose to adhere to the XDG spec could make sense of what is going on (and know how to "correct course" themselves).

I may be way overstepping, however—don't hesitate to push back :-)

[lcn2]

👍

[lcn2]

Hello @ccjmne ,

Please download the latest version of calc off of the master branch, which will be calc v2.17.0.0, as this now contains an XDG Base Directory conforming implementation of calc v2.

Thanks.