From e9a6625e7621162e55c35b08e2b9f175ed6da16e Mon Sep 17 00:00:00 2001 From: Mike Brown Date: Mon, 7 Dec 2015 16:04:25 -0600 Subject: [PATCH] Clarity for commands vs global options While reviewing the `global options` section in `runtime.md`, it seemed additional clarity was needed for the `command` and `global options` requirements. Discussed and worked on wording with @wking via private IRC. Also adds uppercase RFC 2119 words for this section. With regard to the statement `Command names MUST not start with hyphens,` the rationale behind this decision is to "distinguish unrecognized commands from unrecognized options, and because we are "requiring runtimes to fail-fast for unrecognized commands" [1,2]. `[1]` https://github.com/wking/oci-command-line-api/pull/8/files#r46898167 `[2]` https://github.com/wking/oci-command-line-api/commit/527f3c629a7224144c1e5e41a8a197fe0eb5bc00#commitcomment-14835617 Signed-off-by: Mike Brown Reviewed-by: W. Trevor King --- runtime.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/runtime.md b/runtime.md index c46c91f..b7141c5 100644 --- a/runtime.md +++ b/runtime.md @@ -9,8 +9,11 @@ $ funC [global-options] [command-specific-options] ` is unambiguously an invocation of `` for any `` that does not start with a hyphen (including commands not specified in this document). +None are required, but the runtime MAY support options that start with at least one hyphen. +Global options MAY take positional arguments (e.g. `--log-level debug`). +Command names MUST not start with hyphens. +The option parsing MUST be such that `funC ` is unambiguously an invocation of `` (even for commands not specified in this document). +If the runtime is invoked with an unrecognized command, it MUST exit with a nonzero exit code and MAY log a warning to stderr. ## Character encodings