ENB: A new file format and a new uA policy

[Edward K. Ream]

This Engineering Notebook post explains why  #3474 (reforming uAs) must wait until Leo 6.7.5. 

The present code that handles uAs is too complex to understand or change. New unit tests won't change this situation.

Instead,  #3472 will enforce a new uA policy as part of the proposed flat-json file format:

1. All uAs must have valid json values.

2. Plugins (not Leo's core) must encode and decode uAs.

Yes, this policy may affect existing plugins. I'll update Leo's existing plugins as necessary. 

This new policy will collapse the complexity of uA-related code: uA setters can immediately warn if values aren't valid json. In contrast, Leo's existing code checks uAs when writing .leo files.

Summary

A new uA policy will be part of Leo's proposed flat-json file format. This policy may affect some plugins. This new policy will collapse the complexity of uA-related code.

Your comments, please.

Edward

[Edward K. Ream]

On Wednesday, August 2, 2023 at 5:21:54 AM UTC-5 Edward K. Ream wrote:

This Engineering Notebook post explains why  #3474 (reforming uAs) must wait until Leo 6.7.5. 

The present code that handles uAs is too complex to understand or change. New unit tests won't change this situation.

This statement will always be true, so Leo's old, ugly, inscrutable legacy file code must remain even in Leo 6.7.5.

Otoh, the new uA policy will simplify how the flat-json file format handles uAs.

Edward

[Edward K. Ream]

I won't completely rule out potential simplifications, but we'll want to ensure unchanged legacy operation.

Edward

[Edward K. Ream]

On Wednesday, August 2, 2023, Edward K. Ream wrote:

> Leo's old, ugly, inscrutable, legacy file code must remain even in Leo 6.7.5.

PR #3473 shows that I must change my mind. Leo 6.7.5 will likely use json for uAs, copy-node, and paste-node. Here are my reasons.

1. The present code is intolerable.

2. Continuing to support legacy operation will add even more complexity.

3. A new command, check-uas (aka show-uas), will show all existing uAs.

This command has already shown how to improve the bookmarks plugin.

Summary

PR #3473 will:

- Represent uAs only as json.

- Convert legacy uAs to json-based uAs when reading .leo files.

- Use json for copy-node and paste-node commands.

- Define the check-uas command.

- Retain various helpers that read and write xml for compatibility with scripts and plugins.

  However, Leo will not call these helpers.

Edward