Skip to content

Commit

Permalink
0.6 final! Appeal can now read config files.
Browse files Browse the repository at this point in the history
* A new feature: Appeal can now read configuration files!
  Check out the new APIs `Appeal.read_mapping`,
  `Appeal.read_iterable`, and even `Appeal.read_csv`.
  This was a massive undertaking and involved a big
  overhaul of the compiler.

* The biggest change to existing behavior: Appeal now
  early-maps options.  (See issue #3.)
  In short: when options are only defined in an optional group,
  they get provisionally mapped (made available) *before* the first
  argument in that group.  Using that option enters the group just
  like specifying the first argument in that group.  You'll see
  the difference in usage; an optional group that mapped an option
  used to look like `[a [-v|--verbose] b c]` but now looks like
  `[[-v|--verbose] a b c]`.

* Appeal now handles multiple short options smashed together
  (e.g. `-ace`) *identically* to them being specified separately
  (e.g. `-a -c -e`).  This caused an observable change in behavior
  regarding when child options get unmapped.

  - Appeal only permits using child options in a limited context:
    it must be after the parent option is executed, it
    must be after the parent option has consumed all its required
    *or optional* opargs, and it must be before any top-level
    positional argument or option mapped before the parent option
    was executed.  But Appeal was lax about enforcing these rules
    when using multiple short options smashed together (e.g. `-ace`);
    it would handle all the options and *then* unmap child options
    as needed.  The good news: Appeal now enforces these rules here
    too.  (The old behavior seems to have been *intentional* on my
    part--what was I *thinking?!)*

* The usage message raised for an unknown option is now much
  better.  If the option is defined anywhere in the program
  being run, it prints a different message telling you it
  can't be used here, but also tells you where it can be used.
  For example, if you use option `-x`, but that's a child
  option mapped by `--parent`, the message would say
  `-x can't be used here, it must be used immediately after --parent`.

* Renamed `Appeal.argument` to `Appeal.parameter`.
  This was one of those "what was I *thinking?"* moments.
  The function affects the parameter, not the argument.
  The old name still works but will be removed before 1.0.

* `short_option_concatenated_oparg` is now more strictly
  enforced: it's only permitted for short options that have
  *exactly one* **optional** oparg, as specified by POSIX.
  • Loading branch information
larryhastings committed Jul 20, 2023
1 parent 58f0f6c commit a893b2e
Showing 1 changed file with 9 additions and 4 deletions.
13 changes: 9 additions & 4 deletions README.md
Expand Up @@ -2297,11 +2297,16 @@ Restrictions on Appeal command functions:

**0.6**

Rewrote options handling. Appeal's options semantics are now much
stricter and more regular, but most of what changed was about obscure
boundary conditions. You probably won't even notice the change.
A huge upgrade!

* The big change: Appeal now early-maps options. (See issue #3.)
* A new feature: Appeal can now read configuration files!
Check out the new APIs `Appeal.read_mapping`,
`Appeal.read_iterable`, and even `Appeal.read_csv`.
This was a massive undertaking and involved a big
overhaul of the compiler.

* The biggest change to existing behavior: Appeal now
early-maps options. (See issue #3.)
In short: when options are only defined in an optional group,
they get provisionally mapped (made available) *before* the first
argument in that group. Using that option enters the group just
Expand Down

0 comments on commit a893b2e

Please sign in to comment.