Object Mapping

MapTo<T> and MapToSignature<T> hydrate domain objects or invoke methods directly from parsed option values, as an alternative to writing handler body logic manually.

Mapping to a POCO

MapTo<T> hydrates an instance of T from parsed option values and passes it to the delegate given to Then.

// Given the following command options:
cmdDef.AddOption<string>(key: "first", help: "First name.", ("-f", "--first"));
cmdDef.AddOption<string>(key: "last",  help: "Last name.",  ("-l", "--last"));
cmdDef.AddOption<int>   (key: "age",   help: "Age.",        ("-a", "--age"));

// Map options to a POCO by explicit correlation (option key → property name)
cmdDef.MapTo<Person>(
    ("first", nameof(Person.FirstName)),
    ("last",  nameof(Person.LastName)),
    ("age",   nameof(Person.Age))
).Then(person => PersonService.Save(person));

// If option keys match property names exactly, correlation tuples can be omitted
cmdDef.MapTo<Person>().Then(person => PersonService.Save(person));

// Every option must map to a property or be explicitly excluded — unmapped options
// throw CommandMappingException at registration. Use "~" on the property side of
// the tuple to exclude an option from mapping:
cmdDef.MapTo<Person>(
    ("gender", "~")
).Then(person => PersonService.Save(person));

Mapping to a method signature

MapToSignature<T> invokes a delegate directly, mapping each option to a parameter by name. T is inferred when the target is unambiguous.

// Given the following command options:
cmdDef.AddOption<string>(key: "first", help: "First name.", ("-f", "--first"));
cmdDef.AddOption<string>(key: "last",  help: "Last name.",  ("-l", "--last"));
cmdDef.AddOption<int>   (key: "age",   help: "Age.",        ("-a", "--age"));

// Map to a method signature — T inferred when the target is unambiguous
// static void Save(string firstName, string lastName, int age) { ... }
cmdDef.MapToSignature(PersonService.Save,
    ("first", "firstName"),
    ("last",  "lastName")
).Go();

// When the target is overloaded, provide the typed delegate to select the overload
// static void Save(Person person) { ... }
// static void Save(string firstName, string lastName, int age) { ... }
cmdDef.MapToSignature<Action<string, string, int>>(PersonService.Save,
    ("first", "firstName"),
    ("last",  "lastName")
).Go();

The age option needs no correlation tuple — its key matches the age parameter exactly, so it auto-correlates. Every parameter must end up mapped, either by an explicit tuple or by this name match, or MapToSignature throws CommandMappingException at registration.

Go() discards any return value from the delegate. GoAsync() requires the delegate to return Task — a delegate with a different return type will compile but throw an InvalidCastException at runtime.

Masked Input Exceptions