txt: ## dist_cpan-HANENKAMP-Getopt-ForClass.md
  # NAME
  
  Getopt::ForClass - Use MAIN to dispatch to a class
  
  # SYNOPSIS
  
  ```
  #!/usr/bin/env perl6
  use Getopt::ForClass;
  
  class MyApp {
      has $.token;
  
      method BUILD(:$!token) { }
  
      method list-things(:$filter) { ... }
      method add-thing($name) { ... }
      method remove-thing($name, Bool :$cascade) { ... }
  }
  
  our &MAIN := build-main-for-class(
      class => MyApp,
  );
  
  # On the command-line:
  # % myapp --token=abc123 list-things --filter red
  # % myapp --token=abc123 add-thing socks
  # % myapp --token=abc123 remove-thing shrubbery --cascade
  
  ```
  
  # DESCRIPTION
  
  This module exports a function, `build-main-for-class`, which takes a class type and uses it to setup a `MAIN` function that is able to execut the various methods of that class as sub-commands of the script.
  
  # METHODS
  
  ## sub build-main-for-class
  
  ```
  sub build-main-for-class(:$class!, :$methods = *) returns Routine:D
  
  ```
  
  This routine is exported by default. Given a `$class`, it will inspect that class and generate a `MAIN` function that is able to execute one of the methods of that class per run. It does this by generating a multisub, which may be assigned to `MAIN` in your program.
  
  Specifically, it does the following:
  
  * 1. One `MAIN` multisub candidate is generated for each method in the class (limited by the smartmatch in `$methods`, see below).
  * 1. Each `MAIN` candidate will provide command-line options based upon the `BUILD` submethod for the class. If no `BUILD` is provided, then no attributes will be set during construction.
  * 1. The first positional argument accepted by each `MAIN` candidate is the name of one of the methods in the class.
  * 1. The remaining positional and named arguments for each `MAIN` candidate are those taken from `BUILD` and those taken from the method of the class this candidate is associated with.
  
  When run, the `MAIN` method will first construct an object by calling the `new` method and passing to that method the same parameters as are defined in `BUILD`. It will then call the method for the selected candidate passing to that method all the arguments given on the command-line.
  
  ## sub MAIN\_HELPER
  
  ```
  sub MAIN_HELPER($retval = 0)
  
  ```
  
  In addition to generating the `MAIN` routine, this module also provides a `MAIN_HELPER`, which will parse the command-line arguments to call the generated `MAIN` subroutine.
  
  This implementation will attempt to locate the most appropriate `MAIN` candidate using parameters given on the command-line. It will then organize and pass the command-line parameters to the `MAIN` candidate. This works somewhat differently from the Perl6 native `MAIN_HELPER` (at least as of this writing):
  
  * * Any parameter of the form `--NAME=VALUE` will be treated as a named parameter. If the candidate explicitly defines that named parameter with a numeric type, the value will be converted to a number before being passed. If it defines a boolean type, the value will be converted to False if it matches "1", "y", "yes", or "true" (using a case insensitive match) and True otherwise. Otherwise, the string will be passed as is.
  * * Any parameter of the form `--NAME` will be treated as a named parameter. If the candidate explicityly defines that named parameter as boolean, it will be set to a True value. Any other type is assumed to require a parameter so the next argument on the command-line must be a parameter. If the type of the named parameter is numeric, the value will be coerced into a number before being passed.
  * * Any parameter of the form `--no-NAME` will be treated as a named parameter. The named parameter will be set to False.
  * * Any parameter following `--` will be treated as a positional parameter, even if it takes on one of the forms named above.
  * * Any other parameter is treated as a positional parameter. Positional parameters will be converted to boolean or numbers based upon type.
  
  This implementation is less picky about the ordering of parameters than the built-in Perl 6 implementation that is in place as of this writing.
  
  # AUTHOR
  
  Sterling Hanenkamp `<hanenkamp@cpan.org>`
  
  # COPYRIGHT & LICENSE
  
  Copyright 2016 Sterling Hanenkamp.
  
  This software is licensed under the same terms as Perl 6.
  