YAML flow syntax would benefit from some examples

[tobinjt]

G'day.

Thanks for writing keep-sorted, I love it :)

I'm trying to sort a list of "key" = "value" pairs by value, then key. I want to use by_regex, but I cannot figure out the escaping. Here's my input (pre-sorting):

    ["UAA"] = "STOP",
    ["UAC"] = "Tyrosine",
    ["UAG"] = "STOP",
    ["UAU"] = "Tyrosine",
    ["UCA"] = "Serine",
    ["UCC"] = "Serine",
    ["UCG"] = "Serine",
    ["UCU"] = "Serine",
    ["UGA"] = "STOP",
    ["UGC"] = "Cysteine",
    ["UGG"] = "Tryptophan",
    ["UGU"] = "Cysteine",
    ["UUA"] = "Leucine",
    ["UUC"] = "Phenylalanine",
    ["UUG"] = "Leucine",
    ["UUU"] = "Phenylalanine"

I'm trying to include the double quotes to anchor the regex, and include a comma in {4,} to match 4 or more. Here are some attempts and error messages:

by_regex=["\\w{4,}," "..."]
WRN while parsing option "by_regex": yaml: did not find expected ',' or ']'

by_regex=["\w{4,}, "..."]
WRN while parsing option "by_regex": content appears to be an unterminated YAML list: "[\"\\w{4,}, \"...\"]"

by_regex=["\w{4}, "..."]
WRN while parsing option "by_regex": content appears to be an unterminated YAML list: "[\"\\w{4}, \"...\"]"

I've read https://yaml.org/spec/1.2.2/#flow-sequences and I can't see how to apply it here :( The examples for by_regex are really helpful, perhaps someone who understands the flow sequences could add some examples please? Commas and double quotes in the examples would be very helpful.

Thanks,

[JeffFaer]

What sort of example do you think would be most beneficial in the documentation?

---

For your specific question:

• Since you want to match " explicitly, I'd recommend using ' for the string literals
• Since you're using ', the backslash for \w wouldn't need to be escaped

Something like by_regex=['"(\w{4,})",', '\["(\w{3,})"]'] works

If you wanted to use " instead of ' for the string literal, you would need a lot more escaping: "\"(\\w{4,})\","

[JeffFaer]

Oh, I forgot to mention, #100 just documented a new feature that I think would help you here. You can name your capturing groups and reference them in a template so that you could have just one regex for the entire line

[tobinjt]

Hey Jeff,

Thanks for the pointer to #100, that would indeed work for me I think.

Thinking about examples, I think I'd start by documenting the metacharacters so readers know what they would need to escape. I'd continue with something really simple and build up the complexity. Maybe a sequence like this?

• The following characters are metacharacters for keep-sorted: ... # Now I know what I need to escape or avoid.
• The following characters are metacharacters for YAML flow sequences: ... # Likewise.
• A simple example without YAML: ... and with YAML: ['...'] or ["..."] # This shows me the general format.
• I want to match spaces: [' ... '] # A simple example.
• I want to match double quotes: ['"..."'] or single quotes: ["'...'"] # Because they're part of YAML flow sequences, but oh look that's not too hard.
• I want to match commas: ... # Because by_regex=… takes a comma-separated list of RE2 regular expressions so I expect I'll need to escape them?
• I want to use square brackets in my regex: ... # Because they're part of YAML flow sequences.
• I want to match single and double quotes: ... # A more complex example.
• Maybe something intermediate before the next bullet point so it's less of a jump?
• I want to use quotes, commas, square brackets, spaces, maybe more, in my regex: ... # Putting it all together.
• Maybe some examples like a Python dict where you want to sort by value, then key, and values are repeated? That and some other relatable examples might really help, I found the examples earlier in the docs very helpful.
• A pony! No, a unicorn! 😁

I'm happy to help write this if that's any use, though as you can see I lack some of the essential knowledge 😢

Thanks