feat: add @meta version and @meta author

README.md

@@ -101,16 +101,14 @@ It's how the argc parser identifies configuration.
 
 | Tag                                             | Description                          |
 | :---------------------------------------------- | ------------------------------------ |
+| [`@describe`](./docs/specification.md#describe) | Set the description for the command. |
 | [`@cmd`](./docs/specification.md#cmd)           | Define a subcommand.                 |
 | [`@alias`](./docs/specification.md#alias)       | Set aliases for the subcommand.      |
 | [`@arg`](./docs/specification.md#arg)           | Define a positional argument.        |
 | [`@option`](./docs/specification.md#option)     | Define an option argument.            |
 | [`@flag`](./docs/specification.md#flag)         | Define a flag argument.              |
 | [`@env`](./docs/specification.md#env)           | Define an environment variable.      |
 | [`@meta`](./docs/specification.md#meta)         | Add a metadata.                      |
-| [`@describe`](./docs/specification.md#describe) | Set the description for the command. |
-| [`@version`](./docs/specification.md#version)   | Set the version for the command.     |
-| [`@author`](./docs/specification.md#author)     | Set the author for the command.      |
 
 See [specification](https://github.com/sigoden/argc/blob/main/docs/specification.md) for the grammar and usage of all the comment tags.
 

docs/specification.md

@@ -1,5 +1,24 @@
 # Specification
 
+### `@describe`
+
+Set the description for the command.
+
+> **<sup>Syntax</sup>**\
+> `@describe` string
+
+```sh
+# @describe A demo CLI
+```
+
+```sh
+# @describe Multi-line auto-wrapped help text
+#
+# Extra lines after the @cmd or @describe, which don't start with an @, are 
+# treated as the long description. A line which is not a comment ends
+# the block.
+```
+
 ## `@cmd`
 
 Define a subcommand.
@@ -150,49 +169,49 @@ Add a metadata.
 
 | syntax                       | scope  | description                                                          |
 | :--------------------------- | ------ | :------------------------------------------------------------------- |
-| `@meta dotenv [<path>]`      | root   | Load a `.env` file from a custom path, if persent.                   |
+| `@meta version <value>`      | any    | Set the version for the command.                                     |
+| `@meta author <value>`       | any    | Set the author for the command.                                      |
+| `@meta dotenv [<path>]`      | root   | Load a dotenv file from a custom path, if persent.                   |
+| `@meta symbol <param>`       | any    | Define a symbolic parameter, e.g. `+toolchain`, `@argument-file`.    |
+| `@meta man-section <1-8>`    | root   | Override the section for the man page, defaulting to 1.              |
 | `@meta default-subcommand`   | subcmd | Set the current subcommand as the default.                           |
 | `@meta inherit-flag-options` | root   | Subcommands will inherit the flags/options from their parent.        |
-| `@meta no-inherit-env`       | root   | Subcommands don't inherit the env vars from their parent.            |
-| `@meta symbol <param>`       | anycmd | Define a symbolic parameter, e.g. `+toolchain`, `@argument-file`.    |
+| `@meta no-inherit-env`       | root   | Subcommands will not inherit the env vars from their parent.         |
 | `@meta combine-shorts`       | root   | Short flags/options can be combined, e.g. `prog -xf => prog -x -f `. |
-| `@meta man-section <1-8>`    | root   | Override the default section the man page.                           |
-
 
-### `@describe`
-
-Set the description for the command.
-
-> **<sup>Syntax</sup>**\
-> `@describe` string
 
 ```sh
-# @describe A demo cli
+# @meta version 1.0.0
+# @meta author nobody <[email protected]>
+# @meta dotenv .env.local                         # Load .env.local
+# @meta dotenv                                    # Load .env
+# @meta symbol +toolchain[`_choice_fn`]
+# @meta man-section 8                             # Generate to man section 8
 ```
 
-## `@version`
+## Deprecated Tags
 
-Set the version for the command.
+Deprecated tags can still be used, but are not recommended and may be completely abandoned in subsequent versions.
 
-> **<sup>Syntax</sup>**\
-> `@version` string
+### `@version`
 
-```sh
-# @version 2.17.1 
+Set the version for the command.
+
+```diff
+-- # @version 2.17.1
+++ # @meta version 2.17.1 
 ```
 
-## `@author`
+### `@author`
 
 Set the author for the command.
 
-```sh
-# @author alice <[email protected]>
+```diff
+-- # @author nobody <[email protected]>
+++ # @meta author nobody <[email protected]>
 ```
 
-> **<sup>Syntax</sup>**\
-> `@author` string
-
-## Component
+## Internal components
 
 ### short
 

src/command/mod.rs

@@ -12,9 +12,9 @@ use crate::param::{
 };
 use crate::parser::{parse, parse_symbol, Event, EventData, EventScope, Position};
 use crate::utils::{
-    AFTER_HOOK, BEFORE_HOOK, INTERNAL_SYMBOL, MAIN_NAME, META_COMBINE_SHORTS,
+    AFTER_HOOK, BEFORE_HOOK, INTERNAL_SYMBOL, MAIN_NAME, META_AUTHOR, META_COMBINE_SHORTS,
     META_DEFAULT_SUBCOMMAND, META_DOTENV, META_INHERIT_FLAG_OPTIONS, META_NO_INHERIT_ENV,
-    META_SYMBOL, ROOT_NAME,
+    META_SYMBOL, META_VERSION, ROOT_NAME,
 };
 use crate::Result;
 
@@ -150,12 +150,29 @@ impl Command {
                 }
                 EventData::Meta(key, value) => {
                     let cmd = Self::get_cmd(&mut root_cmd, "@meta", position)?;
-                    if key == META_SYMBOL {
-                        let (ch, name, choice_fn) = parse_symbol(&value).ok_or_else(|| {
-                            anyhow!("@meta(line {}) invalid symbol value", position)
-                        })?;
-                        cmd.symbols
-                            .insert(ch, (name.to_string(), choice_fn.map(|v| v.to_string())));
+                    match key.as_str() {
+                        META_SYMBOL => {
+                            let (ch, name, choice_fn) = parse_symbol(&value).ok_or_else(|| {
+                                anyhow!("@meta(line {}) invalid symbol value", position)
+                            })?;
+                            cmd.symbols
+                                .insert(ch, (name.to_string(), choice_fn.map(|v| v.to_string())));
+                        }
+                        META_VERSION => {
+                            if value.is_empty() {
+                                bail!("@meta(line {}) invalid version value", position)
+                            } else {
+                                cmd.version = Some(value.clone());
+                            }
+                        }
+                        META_AUTHOR => {
+                            if value.is_empty() {
+                                bail!("@meta(line {}) invalid version value", position)
+                            } else {
+                                cmd.author = Some(value.clone());
+                            }
+                        }
+                        _ => {}
                     }
                     cmd.metadata.push((key, value, position));
                 }

src/utils.rs

@@ -14,6 +14,8 @@ pub const AFTER_HOOK: &str = "_argc_after";
 pub const ROOT_NAME: &str = "prog";
 pub const MAIN_NAME: &str = "main";
 
+pub(crate) const META_VERSION: &str = "version";
+pub(crate) const META_AUTHOR: &str = "author";
 pub(crate) const META_DOTENV: &str = "dotenv";
 pub(crate) const META_DEFAULT_SUBCOMMAND: &str = "default-subcommand";
 pub(crate) const META_INHERIT_FLAG_OPTIONS: &str = "inherit-flag-options";

tests/snapshots/integration__validate__help_version_legacy.snap

@@ -0,0 +1,123 @@
+---
+source: tests/validate.rs
+expression: data
+---
+************ RUN ************
+prog help
+
+# OUTPUT
+command cat >&2 <<-'EOF' 
+prog 1.0.0
+nobody <[email protected]>
+Test argc
+
+USAGE: prog
+
+EOF
+exit 0
+
+# RUN_OUTPUT
+prog 1.0.0
+nobody <[email protected]>
+Test argc
+
+USAGE: prog
+
+************ RUN ************
+prog --help
+
+# OUTPUT
+command cat >&2 <<-'EOF' 
+prog 1.0.0
+nobody <[email protected]>
+Test argc
+
+USAGE: prog
+
+EOF
+exit 0
+
+# RUN_OUTPUT
+prog 1.0.0
+nobody <[email protected]>
+Test argc
+
+USAGE: prog
+
+************ RUN ************
+prog -help
+
+# OUTPUT
+command cat >&2 <<-'EOF' 
+prog 1.0.0
+nobody <[email protected]>
+Test argc
+
+USAGE: prog
+
+EOF
+exit 0
+
+# RUN_OUTPUT
+prog 1.0.0
+nobody <[email protected]>
+Test argc
+
+USAGE: prog
+
+************ RUN ************
+prog -h
+
+# OUTPUT
+command cat >&2 <<-'EOF' 
+prog 1.0.0
+nobody <[email protected]>
+Test argc
+
+USAGE: prog
+
+EOF
+exit 0
+
+# RUN_OUTPUT
+prog 1.0.0
+nobody <[email protected]>
+Test argc
+
+USAGE: prog
+
+************ RUN ************
+prog --version
+
+# OUTPUT
+command cat >&2 <<-'EOF' 
+prog 1.0.0
+EOF
+exit 0
+
+# RUN_OUTPUT
+prog 1.0.0
+
+************ RUN ************
+prog -version
+
+# OUTPUT
+command cat >&2 <<-'EOF' 
+prog 1.0.0
+EOF
+exit 0
+
+# RUN_OUTPUT
+prog 1.0.0
+
+************ RUN ************
+prog -V
+
+# OUTPUT
+command cat >&2 <<-'EOF' 
+prog 1.0.0
+EOF
+exit 0
+
+# RUN_OUTPUT
+prog 1.0.0

tests/snapshots/integration__validate__version.snap → tests/snapshots/integration__validate__version_missing.snap

@@ -28,5 +28,3 @@ argc__args=([0]="prog" [1]="cmd" [2]="--version")
 argc__fn=cmd
 argc__positionals=([0]="--version")
 cmd --version
-
-

tests/validate.rs

@@ -4,8 +4,29 @@ use crate::*;
 fn help_version() {
     let script = r###"
 # @describe Test argc
-# @version    1.0.0
-# @author     nobody <[email protected]>
+# @meta version 1.0.0
+# @meta author nobody <[email protected]>
+"###;
+    snapshot_multi!(
+        script,
+        [
+            vec!["prog", "help"],
+            vec!["prog", "--help"],
+            vec!["prog", "-help"],
+            vec!["prog", "-h"],
+            vec!["prog", "--version"],
+            vec!["prog", "-version"],
+            vec!["prog", "-V"],
+        ]
+    );
+}
+
+#[test]
+fn help_version_legacy() {
+    let script = r###"
+# @describe Test argc
+# @version 1.0.0
+# @author nobody <[email protected]>
 "###;
     snapshot_multi!(
         script,
@@ -25,7 +46,7 @@ fn help_version() {
 fn help_version_shadow() {
     let script = r###"
 # @describe Test argc
-# @version    1.0.0
+# @meta version 1.0.0
 
 # @flag -h --host
 # @flag -V --verify
@@ -37,7 +58,7 @@ fn help_version_shadow() {
 fn help_version_exist() {
     let script = r###"
 # @describe Test argc
-# @version    1.0.0
+# @meta version 1.0.0
 
 # @flag -h --help
 # @flag -V --version
@@ -56,7 +77,7 @@ fn help_notations() {
 }
 
 #[test]
-fn version() {
+fn version_missing() {
     let script = r###"
 # @cmd
 cmd() { :; }