jls(8) libxo improved IP address list output

[me_cschwarz.com]

Summary

This is a differential for the Bugzilla report https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=215008.
The diff is a squash of two patches on jls(8) and its man page, aiming to improve the output style when using --libxo output.
I squashed the patches because I cannot figure out how to present a patch series in phabricator.

Below the commit messages.

Separate libxo leaf-lists for IPv4 and IPv6 addresses.


'jls -v --libxo text' does not change its output with this commit.

'jls -v --libxo json' and 'jls -v --libxo xml' however do:

{                                      {
  "__version": "1",                      "__version": "1",
  "jail-information": {                  "jail-information": {
    "jail": [                              "jail": [
      {                                      {
        "jid": 166,                            "jid": 166,
        "hostname": "foo.com",                 "hostname": "foo.com",
        "path": "/var/jail/foo",               "path": "/var/jail/foo",
        "name": "foo",                         "name": "foo",
        "state": "ACTIVE",                     "state": "ACTIVE",
        "cpusetid": 2,                         "cpusetid": 2,
        "ipv4_addrs": [                        "ipv4_addrs": [
          "10.1.1.1",                            "10.1.1.1",
          "10.1.1.2",                            "10.1.1.2",
          "10.1.1.3",                |           "10.1.1.3"
                                     >         ],
                                     >         "ipv6_addrs": [
          "fe80::1000:1",                        "fe80::1000:1",
          "fe80::1000:2"                         "fe80::1000:2"
        ]                                      ]
      }                                      }
    ]                                      ]
  }                                      }
}                                      }

Print ip4.addr and ip6.addr as lists for libxo encoded output (json, xml).

Instead of providing a comma-separated list, ip4.addr and ip6.addr are
thus represented in the encoding format's natural structure.

This patch also unifies / simplifies the IP presentation format conversion.

The XO_VERSION is not incremented because this patch builds upon a previous one.

New output format:

jls -n all --libxo json
 ...
 "ip4.addr": [
    "10.1.1.1",
    "10.1.1.2",
    "10.1.1.3"
  ],
  "ip4.saddrsel": true,
  "ip6.addr": [
    "fe80::1000:1",
    "fe80::1000:2"
  ],
  ...

jls -n all --libxo xml
  ...
  <ip4.addr>10.1.1.1</ip4.addr>
  <ip4.addr>10.1.1.2</ip4.addr>
  <ip4.addr>10.1.1.3</ip4.addr>
  <ip4.saddrsel>true</ip4.saddrsel>
  <ip6.addr>fe80::1000:1</ip6.addr>
  <ip6.addr>fe80::1000:2</ip6.addr>
  ...

Test Plan

TBD

[wblock]

usr.sbin/jls/jls.8

107 ↗

(On Diff #22846)

Please don't pluralize words with (s), it is never an improvement over just a simple "s". Just "addresses".

111 ↗

(On Diff #22846)

This is not clear, but as an imperative:

output, emit IPv4 and IPv6 addresses as separate lists.

[me_cschwarz.com]

Improve style of man page changes.

[jamie]

I don't think the man page needs to change for this. While it's different than the output used to look, there's no more reason to note such specifics of the libxo output format there than there was before.

usr.sbin/jls/jls.c

442 ↗

(On Diff #23010)

This line got somehow duplicated.

[jamie]

emit_ip_addr() is always called surrounded by calls to xo_open_list and xo_close_list. It seems cleaner to have those calls as part of emit_ip_addr() istself. It would take an extra parameter of the name that xo_open and xo_close need, but then fewer lines of code overall.

[me_cschwarz.com]

• Remove duplicated line.
• emit_ip_addr -> emit_ip_addr_list, taking the list name as a parameter

[me_cschwarz.com]

Suggestion for a commit message. Is this too long?

Improve IP address list representation in libxo output.

Extract decision-making about special-case printing of certain
jail parameters into a function.

Refactor emitting of IPv4 and IPv6 address lists into a function.

Resulting user-facing changes:

XO_VERSION is bumped to 2.

In verbose mode (-v), IPv4 and IPv6-Addresses are now properly emitted
as separate lists.
This only affects the output in encoding styles, i.e. xml and json.

{                                    {
  "__version": "1",                    "__version": "2",
  "jail-information": {                "jail-information": {
    "jail": [                            "jail": [
      {                                    {
        "jid": 166,                          "jid": 166,
        "hostname": "foo.com",               "hostname": "foo.com",
        "path": "/var/jail/foo",             "path": "/var/jail/foo",
        "name": "foo",                       "name": "foo",
        "state": "ACTIVE",                   "state": "ACTIVE",
        "cpusetid": 2,                       "cpusetid": 2,
        "ipv4_addrs": [                      "ipv4_addrs": [
          "10.1.1.1",                          "10.1.1.1",
          "10.1.1.2",                          "10.1.1.2",
          "10.1.1.3",              |           "10.1.1.3"
                                   >         ],
                                   >         "ipv6_addrs": [
          "fe80::1000:1",                      "fe80::1000:1",
          "fe80::1000:2"                       "fe80::1000:2"
        ]                                    ]
      }                                    }
    ]                                    ]
  }                                    }
}                                    }


In -n mode, ip4.addr and ip6.addr are formatted in the encoding styles'
native list types, e.g. instead of comma-separated lists, JSON arrays
are printed.

jls -n all --libxo json
 ...
 "ip4.addr": [
    "10.1.1.1",
    "10.1.1.2",
    "10.1.1.3"
  ],
  "ip4.saddrsel": true,
  "ip6.addr": [
    "fe80::1000:1",
    "fe80::1000:2"
  ],
  ...

jls -n all --libxo xml
  ...
  <ip4.addr>10.1.1.1</ip4.addr>
  <ip4.addr>10.1.1.2</ip4.addr>
  <ip4.addr>10.1.1.3</ip4.addr>
  <ip4.saddrsel>true</ip4.saddrsel>
  <ip6.addr>fe80::1000:1</ip6.addr>
  <ip6.addr>fe80::1000:2</ip6.addr>
  ...

[jamie]

In D8766#183598, @me_cschwarz.com wrote:

Suggestion for a commit message. Is this too long?
...

Well it's a good bit longer than I would have written. But it's seldom the case that a commit message is too long :-). I'll go with it.

[jamie]

I was going to commit, but noticed one thing: the "{ql:ipv4_addr}" (or ipv6_addr) in emit_ip_addr_list's emit_str doesn't ever get reflected in the output (which I think it proper). Does it need to be there at all, or am I missing something? I admit to not being close to a libxo expert.

[me_cschwarz.com]

I was going to commit, but noticed one thing: the "{ql:ipv4_addr}" (or ipv6_addr) in emit_ip_addr_list's emit_str doesn't ever get reflected in the output (which I think it proper). Does it need to be there at all, or am I missing something? I admit to not being close to a libxo expert.

I think this is intended behavior.

It is actually showing up as the tag type (? sry, am not an XML expert, in fact not even a noob :D )