Argument groups

Commands can contain argument groups. Groups allow you to organize the arguments in the command in a more structured way so that the user can understand the purpose of each argument better.

Groups are mostly useful for the help message generation, where they can be seen visually affecting the representation of how arguments are displayed.

Creating a group and adding Arguments

Wrap the arguments you want to group in an Group:

var cmd = new ArgumentParser("MyProgram") {{
	addGroup(new Group("stuff") {{
		addArgument(Argument.create(new StringArgumentType(), "arg1"));
		addArgument(Argument.create(new StringArgumentType(), "arg2"));
	}});
}}

In this case the arguments are added before the group is added to the command (Group instantiation > Arguments added to group > Group added to command). However, this doesn't mean that the arguments have to be added before the group is added to the command. This is also allowed:

var cmd = new ArgumentParser("MyProgram") {{
	var group = new Group("stuff");
	addGroup(group);
	group.addArgument(Argument.create(new StringArgumentType(), "arg1"));
	group.addArgument(Argument.create(new StringArgumentType(), "arg2"));
}}

Creating a group

Use the group() attribute in the @Argument.Define annotation to specify the group that an argument belongs to.

// adding both arguments to the same group
@Command.Define
class MyCommand extends CommandTemplate {
	@Argument.Define(group = "stuff")
	public String arg1;

	@Argument.Define(group = "stuff")
	public String arg2;
}

Group hierarchy

Just like commands, groups can be nested inside other groups. This allows you to create a hierarchy of groups:

var cmd = new ArgumentParser("MyProgram") {{
	addGroup(new Group("stuff") {{
		addArgument(Argument.create(new StringArgumentType(), "arg1"));
		addArgument(Argument.create(new StringArgumentType(), "arg2"));
		
		addGroup(new Group("more-stuff") {{
			addArgument(Argument.create(new StringArgumentType(), "another"));
		}});
	}});
}}

Restrictive groups

Groups can be set to be restrictive. This means that only a single argument inside that group (or any of its sub-groups) can be used at a time. This is useful for commands that have mutually exclusive arguments.

To make a group restrictive, set the restricted property of the group to true:

var cmd = new ArgumentParser("MyProgram") {{
	addGroup(new Group("stuff") {{
		setRestricted(true);
		addArgument(Argument.create(new StringArgumentType(), "arg1"));
		addArgument(Argument.create(new StringArgumentType(), "arg2"));
	}});
}}

@InitDef
public static void afterInit(Command cmd) {
	cmd.getGroup("stuff").setRestricted(true);
}

Example

Given the following group tree (lime colored groups are restrictive):

If Argument 1 is used, then none of the arguments in the child groups can be used, because Group 1 is restricted.
If Argument 3.1 is used, then none of the arguments in the rest of the tree can be used, because both Group 3 and its parent Group 1 are restricted.
If Argument 2.1 is used, Argument 2.2 can still be used, because Group 2 is not restricted. No other arguments in the tree can be used though.

Last modified: 25 April 2024