From 7ad14589f9e8b4a881cbbfb746c9047d4953e461 Mon Sep 17 00:00:00 2001 From: Leo Kettmeir Date: Mon, 30 Sep 2024 16:00:54 -0700 Subject: [PATCH] fix(flags): move some content from docs.deno.com into help output (#25951) --- cli/args/flags.rs | 131 +++++++++++++++++++++++++++------------------- 1 file changed, 78 insertions(+), 53 deletions(-) diff --git a/cli/args/flags.rs b/cli/args/flags.rs index 2cbf463948..b4f566810c 100644 --- a/cli/args/flags.rs +++ b/cli/args/flags.rs @@ -1258,28 +1258,7 @@ pub fn flags_from_vec(args: Vec) -> clap::error::Result { .get_arguments() .any(|arg| arg.get_id().as_str() == "unstable") { - subcommand = subcommand - .mut_arg("unstable", |arg| { - let new_help = arg - .get_help() - .unwrap() - .to_string() - .split_once("\n") - .unwrap() - .0 - .to_string(); - arg.help_heading(UNSTABLE_HEADING).help(new_help) - }) - .mut_args(|arg| { - // long_help here is being used as a metadata, see unstable args definition - if arg.get_help_heading() == Some(UNSTABLE_HEADING) - && arg.get_long_help().is_some() - { - arg.hide(false) - } else { - arg - } - }); + subcommand = enable_unstable(subcommand); } help_parse(&mut flags, subcommand); @@ -1414,6 +1393,31 @@ pub fn flags_from_vec(args: Vec) -> clap::error::Result { Ok(flags) } +fn enable_unstable(command: Command) -> Command { + command + .mut_arg("unstable", |arg| { + let new_help = arg + .get_help() + .unwrap() + .to_string() + .split_once("\n") + .unwrap() + .0 + .to_string(); + arg.help_heading(UNSTABLE_HEADING).help(new_help) + }) + .mut_args(|arg| { + // long_help here is being used as a metadata, see unstable args definition + if arg.get_help_heading() == Some(UNSTABLE_HEADING) + && arg.get_long_help().is_some() + { + arg.hide(false) + } else { + arg + } + }) +} + macro_rules! heading { ($($name:ident = $title:expr),+; $total:literal) => { $(const $name: &str = $title;)+ @@ -1852,11 +1856,15 @@ fn compile_subcommand() -> Command { "compile", cstr!("Compiles the given script into a self contained executable. - deno compile -A jsr:@std/http/file-server + deno compile --allow-read --allow-net jsr:@std/http/file-server deno compile --output file_server jsr:@std/http/file-server Any flags specified which affect runtime behavior will be applied to the resulting binary. +This allows distribution of a Deno application to systems that do not have Deno installed. +Under the hood, it bundles a slimmed down version of the Deno runtime along with your +JavaScript or TypeScript code. + Cross-compiling to different target architectures is supported using the --target flag. On the first invocation with deno will download the proper binary and cache it in $DENO_DIR. @@ -2223,6 +2231,9 @@ Supported file types which are behind corresponding unstable flags (see formatti Format stdin and write to stdout: cat file.ts | deno fmt - +Check if the files are formatted: + deno fmt --check + Ignore formatting code by preceding it with an ignore comment: // deno-fmt-ignore @@ -2373,7 +2384,7 @@ Ignore formatting a file by adding an ignore comment at the top of the file: } fn init_subcommand() -> Command { - command("init", "Initialize a new project", UnstableArgsConfig::None).defer( + command("init", "scaffolds a basic Deno project with a script, test, and configuration file", UnstableArgsConfig::None).defer( |cmd| { cmd .arg(Arg::new("dir").value_hint(ValueHint::DirPath)) @@ -2418,7 +2429,7 @@ The following information is shown: .arg( location_arg() .conflicts_with("file") - .help("Show files used for origin bound APIs like the Web Storage API when running a script with '--location='") + .help(cstr!("Show files used for origin bound APIs like the Web Storage API when running a script with --location=<>")) ) .arg(no_check_arg().hide(true)) // TODO(lucacasonato): remove for 2.0 .arg(no_config_arg()) @@ -2460,7 +2471,7 @@ If the --global flag is set, installs a script as an executable in the deno install --global --allow-net --allow-read jsr:@std/http/file-server deno install -g https://examples.deno.land/color-logging.ts -To change the executable name, use -n/--name: +To change the executable name, use -n/--name: deno install -g --allow-net --allow-read -n serve jsr:@std/http/file-server The executable name is inferred by default: @@ -2742,7 +2753,12 @@ To ignore linting on an entire file, you can add an ignore comment at the top of } fn repl_subcommand() -> Command { - command("repl", "Read Eval Print Loop", UnstableArgsConfig::ResolutionAndRuntime) + command("repl", cstr!( + "Starts a read-eval-print-loop, which lets you interactively build up program state in the global context. +It is especially useful for quick prototyping and checking snippets of code. + +TypeScript is supported, however it is not type-checked, only transpiled." + ), UnstableArgsConfig::ResolutionAndRuntime) .defer(|cmd| runtime_args(cmd, true, true) .arg(check_arg(false)) .arg( @@ -2825,8 +2841,6 @@ fn serve_subcommand() -> Command { The serve command uses the default exports of the main module to determine which servers to start. -See https://docs.deno.com/runtime/manual/tools/serve for more detailed information. - Start a server defined in server.ts: deno serve server.ts @@ -2837,7 +2851,7 @@ Start a server defined in server.ts, watching for changes and running on port 50 .arg( Arg::new("port") .long("port") - .help("The TCP port to serve on, defaulting to 8000. Pass 0 to pick a random free port") + .help(cstr!("The TCP port to serve on. Pass 0 to pick a random free port [default: 8000]")) .value_parser(value_parser!(u16)), ) .arg( @@ -3047,11 +3061,13 @@ fn parallel_arg(descr: &str) -> Arg { fn types_subcommand() -> Command { command( "types", - "Print runtime TypeScript declarations. + cstr!( + "Print runtime TypeScript declarations. deno types > lib.deno.d.ts -The declaration file could be saved and used for typing information.", +The declaration file could be saved and used for typing information." + ), UnstableArgsConfig::None, ) } @@ -3161,7 +3177,7 @@ See the Deno 1.x to 2.x Migration Guide for migration instructions: https://docs } fn publish_subcommand() -> Command { - command("publish", "Publish the current working directory's package or workspace", UnstableArgsConfig::ResolutionOnly) + command("publish", "Publish the current working directory's package or workspace to JSR", UnstableArgsConfig::ResolutionOnly) .defer(|cmd| { cmd .arg( @@ -3550,8 +3566,7 @@ fn permission_args(app: Command, requires: Option<&'static str>) -> Command { .long("allow-hrtime") .action(ArgAction::SetTrue) .help("REMOVED in Deno 2.0") - .hide(true) - ; + .hide(true); if let Some(requires) = requires { arg = arg.requires(requires) } @@ -3564,8 +3579,7 @@ fn permission_args(app: Command, requires: Option<&'static str>) -> Command { .long("deny-hrtime") .action(ArgAction::SetTrue) .help("REMOVED in Deno 2.0") - .hide(true) - ; + .hide(true); if let Some(requires) = requires { arg = arg.requires(requires) } @@ -3801,7 +3815,9 @@ fn location_arg() -> Arg { url.set_password(None).unwrap(); Ok(url) }) - .help("Value of 'globalThis.location' used by some web APIs") + .help(cstr!( + "Value of globalThis.location used by some web APIs" + )) .value_hint(ValueHint::Url) } @@ -4655,7 +4671,7 @@ fn json_reference_parse( app.build(); fn serialize_command( - command: &mut Command, + mut command: Command, top_level: bool, ) -> deno_core::serde_json::Value { let args = command @@ -4663,7 +4679,7 @@ fn json_reference_parse( .filter(|arg| { !arg.is_hide_set() && if top_level { - true + arg.is_global_set() } else { !arg.is_global_set() } @@ -4672,40 +4688,49 @@ fn json_reference_parse( let name = arg.get_id().as_str(); let short = arg.get_short(); let long = arg.get_long(); - let aliases = arg.get_visible_aliases(); let required = arg.is_required_set(); - let help = arg.get_help().map(|help| help.to_string()); + let help = arg.get_help().map(|help| help.ansi().to_string()); + let help_heading = arg + .get_help_heading() + .map(|help_heading| help_heading.to_string()); let usage = arg.to_string(); json!({ "name": name, "short": short, "long": long, - "aliases": aliases, "required": required, "help": help, + "help_heading": help_heading, "usage": usage, }) }) .collect::>(); let name = command.get_name().to_string(); - let about = command.get_about().map(|about| about.to_string()); - let visible_aliases = command - .get_visible_aliases() - .map(|s| s.to_string()) - .collect::>(); - let usage = command.render_usage().to_string(); + let about = command.get_about().map(|about| about.ansi().to_string()); + let usage = command.render_usage().ansi().to_string(); let subcommands = command - .get_subcommands_mut() - .map(|command| serialize_command(command, false)) + .get_subcommands() + .map(|command| { + serialize_command( + if command + .get_arguments() + .any(|arg| arg.get_id().as_str() == "unstable") + { + enable_unstable(command.clone()) + } else { + command.clone() + }, + false, + ) + }) .collect::>(); json!({ "name": name, "about": about, - "visible_aliases": visible_aliases, "args": args, "subcommands": subcommands, "usage": usage, @@ -4713,7 +4738,7 @@ fn json_reference_parse( } flags.subcommand = DenoSubcommand::JSONReference(JSONReferenceFlags { - json: serialize_command(&mut app, true), + json: serialize_command(app, true), }) }