Implement --log CLI argument

[mathiascode]

Enables additional logging, and takes an optional list of log categories to enable.

Replaces the --debug flag.

[mathiascode]

For the message categories, I was thinking we could make it possible to add a message code or code range to the end of them, to narrow down the messages, e.g. msg-55 or msg-78-85. You could then give several message values like this to log many messages, e.g. msg-2,msg-32,msg-66-72.

[slook]

we could make it possible to add a message code or code range

If we do that then the hyphen - character would be needed to identify that a range had been specified, which makes it awkward to use this character to separate other sub-arguments.

It could be better to use double-hyphen -- to split the main arguments of the line into chunks to select the case condition, then use a space character for membership checking the split sub-arguments of the chunk in this case.

Edit: On second thought, it could be best just to use membership checking all round, since none of the nested arguments would be applicable to anything other than --log so there is no need for full argument parsing.

to log many messages, e.g. msg-2,msg-32,msg-66-72.

It is non-standard syntax to expect that a comma mustn't have a space character following it.

[slook]

https://dlang.org/library/std/getopt/getopt.html

[mathiascode]

If we do that then the hyphen - character would be needed to identify that a range had been specified, which makes it awkward to use this character to separate other sub-arguments.

It could be better to use double-hyphen -- to split the main arguments of the line into chunks to select the case condition, then use a space character for membership checking the split sub-arguments of the chunk in this case.

Edit: On second thought, it could be best just to use membership checking all round, since none of the nested arguments would be applicable to anything other than --log so there is no need for full argument parsing.

Can you give an example?

to log many messages, e.g. msg-2,msg-32,msg-66-72.

It is non-standard syntax to expect that a comma mustn't have a space character following it.

The reason I made it possible to use commas like this is because spaces require quotation marks around the value. Will people remember to add those? I'm not sure.

[slook]

Can you give an example?

See my branch in PR #83 I just pushed a change to print the "inputed" and "ignored" arguments. The parser consumes options that are defined in getopt() but ignores any others that are undefined and leaves them in args for later processing by the program...

$ ./bin/soulfind --port 1234 --debug conn msg 1 2 "user name" 3-4 5 67-89 123 rx --version 45 6 etc and so on
arg inputed: ./bin/soulfind
arg inputed: --port
arg inputed: 1234
arg inputed: --debug
arg inputed: conn
arg inputed: msg
arg inputed: 1
arg inputed: 2
arg inputed: user name
arg inputed: 3-4
arg inputed: 5
arg inputed: 67-89
arg inputed: 123
arg inputed: rx
arg inputed: --version
arg inputed: 45
arg inputed: 6
arg inputed: etc
arg inputed: and
arg inputed: so
arg inputed: on
args parsed.
arg ignored: ./bin/soulfind
arg ignored: conn
arg ignored: msg
arg ignored: 1
arg ignored: 2
arg ignored: user name
arg ignored: 3-4
arg ignored: 5
arg ignored: 67-89
arg ignored: 123
arg ignored: rx
arg ignored: 45
arg ignored: 6
arg ignored: etc
arg ignored: and
arg ignored: so
arg ignored: on
Soulfind Mar-29-2026 (compiled with GNU D 2.100)
$

Notice in the above example --port 1234 and --debug and --version are not "ignored" but everything else is still in args. If you wanted to be strict then you could verify index positions to ensure categories are nested within the correct argument, but this isn't strictly necessary since the sub-arguments are all unique anyway.

So --log could be made boolean just like --debug currently is, and then the categories can be taken directly from the "ignored" args anywhere on the command line, instead of parsing them as proper shell arguments.

[mathiascode]

Do you know any other programs that do this? What concerns me is that it seems a bit like a hack, and I'm not quite sure how to document it. At first glance, I was left thinking what "user name" does. Presumably, it applies to message 1 and 2, but it's a bit difficult to see where the boundary is between categories. What if a username is the same as another category? What if I put rx before msg or conn, or in the middle of the codes, how would that behave?

[mathiascode]

One proposal to make my life a little easier parsing things, building on what's already implemented in this PR:

Categories separated by commas. Optional subarguments to categories provided after equals sign, separated by colons.

• conn
  Connections

• db
  Database operations

• msg=1:6:21:54-68:@username:@"some username"
  Messages 1, 6, 21 and 54-68 from and to users "username" and "some username"

• msg-in=1:6:21:54-68:@username:@"some username"
  Messages 1, 6, 21 and 54-68 from users "username" and "some username"

• msg-out=1:6:21:54-68:@username:@"some username"
  Messages 1, 6, 21 and 54-68 to users "username" and "some username"

• vmsg=1:6:21:54-68:@username:@"some username"
  Messages 1, 6, 21 and 54-68 from and to users "username" and "some username", verbose output (raw bytes)

• vmsg-in=1:6:21:54-68:@username:@"some username"
  Messages 1, 6, 21 and 54-68 from users "username" and "some username", verbose output (raw bytes)

• vmsg-out=1:6:21:54-68:@username:@"some username"
  Messages 1, 6, 21 and 54-68 to users "username" and "some username", verbose output (raw bytes)

[slook]

Hmm... I don't think I like the syntax of your proposal it makes my eyes go fuzzy! Also too easy to make mistake.

Do you know any other programs that do this?

Yes, MS-DOS batch scripts take positional parameters as %1 to %9 (and %0 is the filename of the script). Bash scripting does a similar thing but uses $ dollar prefix. Python scripts use the sys.argv list for this purpose. In all cases the program may process them in any order it likes or not process them at all. There's not really any rules.

thinking what "user name" does

I don't know but I suppose any part of the program where input of usernames might be useful, primarily I would imagine it would cause any additional logging to be filtered to only traffic pertaining that user or those users, unless we decide to have another purpose for taking usernames as arguments. In any case, except for the database filename they are the only thing that shall need quoting.

Presumably, it applies to message 1 and 2

No, I think it would apply to all messages that are being sent and received to and from a particular user's client.

What if a username is the same as another category?

It wouldn't matter because usernames would be the only things that are quoted, whereas all the categories are unquoted arguments. So for eg:

• --log 1 rx conn means show received bytes for all Logins, and CONN log, for all users;
• --log 1 rx "conn" means show the received Login bytes, for only a user whose named "conn".
• --log 1 rx conn "conn" means show the received Login bytes, and CONN log, for a user named "conn".
• --log 1 "rx" conn means show the Login headers, and CONN log, for only a user named "rx".
• --log "1" rx conn means show all received message bytes, and CONN log, for only a user named "1".

But it is hard to know if an argument was quoted or not. So that is a limitation, whereas your @ prefix idea might be most useful to get around that if we decide to implement that in future.

What if I put rx before msg or conn, or in the middle of the codes, how would that behave?

I think it's easiest if the order is irrelevant, both from an implementation and usage point of view. If an integer is present anywhere then that code is added into the list for filtering the message codes. If a catagory is present is anywhere then that catagory is enabled. If it isn't then it isn't enabled. Simples.

[slook]

how would that behave?

I suggest you try running my cli-getopt branch, which outputs the args so you can see how it behaves:

    foreach (arg ; args) {
        // all the args
        writeln("arg inputed: ", arg);
    }

    // do getopt(args) here for - and -- options

    foreach (arg ; args) {
        // all the left over positional arguments
        // to do log categories here
        writeln("arg ingnored: ", arg);
    }

You can achieve this in cli module by not throwing on "Unexpected positional argument" nor "Unknown option".

What concerns me is that it seems a bit like a hack, and I'm not quite sure how to document it.

It does doesn't it, and those other arguments would not appear in the --help either.