remove links to ShellError and ParseError docs - #8167 (#8193)

# Description

issue #8167

Remove the `(link)` to the docs for `ShellError` and `ParseError`. As
per discussion on the issue, the nu-parser version didn't update on the
docs causing deadlinks for those errors, which brought the usefullness
of these links into question and it was decided to remove all of them
that `derive(diagnostic)`.

# User-Facing Changes
Before:
```
/home/rdevenney/projects/open_source/nushell〉ls | get name}
Error: nu::parser::unbalanced_delimiter (link)

  × Unbalanced delimiter.
   ╭─[entry #1:1:1]
 1 │ ls | get name}
   ·              ▲
   ·              ╰── unbalanced { and }
   ╰────
```

After:
```
/home/rdevenney/projects/open_source/nushell〉ls | get name}
Error: nu::parser::unbalanced_delimiter

  × Unbalanced delimiter.
   ╭─[entry #1:1:1]
 1 │ ls | get name}
   ·              ▲
   ·              ╰── unbalanced { and }
   ╰────
```

# Tests + Formatting

Don't forget to add tests that cover your changes.

Make sure you've run and fixed any issues with these commands:

- `cargo fmt --all -- --check` to check standard code formatting (`cargo
fmt --all` applies these changes)
- `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used -A
clippy::needless_collect` to check that you're using the standard code
style
- `cargo test --workspace` to check that all tests pass

# After Submitting

If your PR had any user-facing changes, update [the
documentation](https://github.com/nushell/nushell.github.io) after the
PR is merged, if necessary. This will help us keep the docs up to date.
This commit is contained in:
Ryan Devenney
2023-02-24 12:26:31 -05:00
committed by GitHub
parent 585e104608
commit b572b4ecbd
3 changed files with 140 additions and 168 deletions

View File

@ -8,48 +8,43 @@ pub enum ParseError {
/// finished. You should remove these or finish adding what you intended
/// to add.
#[error("Extra tokens in code.")]
#[diagnostic(
code(nu::parser::extra_tokens),
url(docsrs),
help("Try removing them.")
)]
#[diagnostic(code(nu::parser::extra_tokens), help("Try removing them."))]
ExtraTokens(#[label = "extra tokens"] Span),
#[error("Extra positional argument.")]
#[diagnostic(code(nu::parser::extra_positional), url(docsrs), help("Usage: {0}"))]
#[diagnostic(code(nu::parser::extra_positional), help("Usage: {0}"))]
ExtraPositional(String, #[label = "extra positional argument"] Span),
#[error("Required positional parameter after optional parameter")]
#[diagnostic(code(nu::parser::required_after_optional), url(docsrs))]
#[diagnostic(code(nu::parser::required_after_optional))]
RequiredAfterOptional(
String,
#[label = "required parameter {0} after optional parameter"] Span,
),
#[error("Unexpected end of code.")]
#[diagnostic(code(nu::parser::unexpected_eof), url(docsrs))]
#[diagnostic(code(nu::parser::unexpected_eof))]
UnexpectedEof(String, #[label("expected closing {0}")] Span),
#[error("Unclosed delimiter.")]
#[diagnostic(code(nu::parser::unclosed_delimiter), url(docsrs))]
#[diagnostic(code(nu::parser::unclosed_delimiter))]
Unclosed(String, #[label("unclosed {0}")] Span),
#[error("Unbalanced delimiter.")]
#[diagnostic(code(nu::parser::unbalanced_delimiter), url(docsrs))]
#[diagnostic(code(nu::parser::unbalanced_delimiter))]
Unbalanced(String, String, #[label("unbalanced {0} and {1}")] Span),
#[error("Parse mismatch during operation.")]
#[diagnostic(code(nu::parser::parse_mismatch), url(docsrs))]
#[diagnostic(code(nu::parser::parse_mismatch))]
Expected(String, #[label("expected {0}")] Span),
#[error("Type mismatch during operation.")]
#[diagnostic(code(nu::parser::type_mismatch), url(docsrs))]
#[diagnostic(code(nu::parser::type_mismatch))]
Mismatch(String, String, #[label("expected {0}, found {1}")] Span), // expected, found, span
#[error("The '&&' operator is not supported in Nushell")]
#[diagnostic(
code(nu::parser::shell_andand),
url(docsrs),
help("use ';' instead of the shell '&&', or 'and' instead of the boolean '&&'")
)]
ShellAndAnd(#[label("instead of '&&', use ';' or 'and'")] Span),
@ -57,19 +52,17 @@ pub enum ParseError {
#[error("The '||' operator is not supported in Nushell")]
#[diagnostic(
code(nu::parser::shell_oror),
url(docsrs),
help("use 'try' instead of the shell '||', or 'or' instead of the boolean '||'")
)]
ShellOrOr(#[label("instead of '||', use 'try' or 'or'")] Span),
#[error("The '2>' shell operation is 'err>' in Nushell.")]
#[diagnostic(code(nu::parser::shell_err), url(docsrs))]
#[diagnostic(code(nu::parser::shell_err))]
ShellErrRedirect(#[label("use 'err>' instead of '2>' in Nushell")] Span),
#[error("The '2>&1' shell operation is 'out+err>' in Nushell.")]
#[diagnostic(
code(nu::parser::shell_outerr),
url(docsrs),
help("Nushell redirection will write all of stdout before stderr.")
)]
ShellOutErrRedirect(#[label("use 'out+err>' instead of '2>&1' in Nushell")] Span),
@ -77,7 +70,6 @@ pub enum ParseError {
#[error("Types mismatched for operation.")]
#[diagnostic(
code(nu::parser::unsupported_operation),
url(docsrs),
help("Change {2} or {4} to be the right types and try again.")
)]
UnsupportedOperation(
@ -89,23 +81,22 @@ pub enum ParseError {
),
#[error("Capture of mutable variable.")]
#[diagnostic(code(nu::parser::expected_keyword), url(docsrs))]
#[diagnostic(code(nu::parser::expected_keyword))]
CaptureOfMutableVar(#[label("capture of mutable variable")] Span),
#[error("Expected keyword.")]
#[diagnostic(code(nu::parser::expected_keyword), url(docsrs))]
#[diagnostic(code(nu::parser::expected_keyword))]
ExpectedKeyword(String, #[label("expected {0}")] Span),
#[error("Unexpected keyword.")]
#[diagnostic(
code(nu::parser::unexpected_keyword),
url(docsrs),
help("'{0}' keyword is allowed only in a module.")
)]
UnexpectedKeyword(String, #[label("unexpected {0}")] Span),
#[error("Unknown operator")]
#[diagnostic(code(nu::parser::unknown_operator), url(docsrs), help("{1}"))]
#[diagnostic(code(nu::parser::unknown_operator), help("{1}"))]
UnknownOperator(
&'static str,
&'static str,
@ -115,7 +106,6 @@ pub enum ParseError {
#[error("Statement used in pipeline.")]
#[diagnostic(
code(nu::parser::unexpected_keyword),
url(docsrs),
help(
"'{0}' keyword is not allowed in pipeline. Use '{0}' by itself, outside of a pipeline."
)
@ -125,7 +115,6 @@ pub enum ParseError {
#[error("{0} statement used in pipeline.")]
#[diagnostic(
code(nu::parser::unexpected_keyword),
url(docsrs),
help(
"Assigning '{1}' to '{2}' does not produce a value to be piped. If the pipeline result is meant to be assigned to '{2}', use '{0} {2} = ({1} | ...)'."
)
@ -135,7 +124,6 @@ pub enum ParseError {
#[error("Let used with builtin variable name.")]
#[diagnostic(
code(nu::parser::let_builtin_var),
url(docsrs),
help("'{0}' is the name of a builtin Nushell variable. `let` cannot assign to it.")
)]
LetBuiltinVar(String, #[label("already a builtin variable")] Span),
@ -143,7 +131,6 @@ pub enum ParseError {
#[error("Const used with builtin variable name.")]
#[diagnostic(
code(nu::parser::let_builtin_var),
url(docsrs),
help("'{0}' is the name of a builtin Nushell variable. `const` cannot assign to it.")
)]
ConstBuiltinVar(String, #[label("already a builtin variable")] Span),
@ -151,35 +138,34 @@ pub enum ParseError {
#[error("Mut used with builtin variable name.")]
#[diagnostic(
code(nu::parser::let_builtin_var),
url(docsrs),
help("'{0}' is the name of a builtin Nushell variable. `mut` cannot assign to it.")
)]
MutBuiltinVar(String, #[label("already a builtin variable")] Span),
#[error("Incorrect value")]
#[diagnostic(code(nu::parser::incorrect_value), url(docsrs), help("{2}"))]
#[diagnostic(code(nu::parser::incorrect_value), help("{2}"))]
IncorrectValue(String, #[label("unexpected {0}")] Span, String),
#[error("Multiple rest params.")]
#[diagnostic(code(nu::parser::multiple_rest_params), url(docsrs))]
#[diagnostic(code(nu::parser::multiple_rest_params))]
MultipleRestParams(#[label = "multiple rest params"] Span),
#[error("Variable not found.")]
#[diagnostic(code(nu::parser::variable_not_found), url(docsrs))]
#[diagnostic(code(nu::parser::variable_not_found))]
VariableNotFound(#[label = "variable not found"] Span),
#[error("Variable name not supported.")]
#[diagnostic(code(nu::parser::variable_not_valid), url(docsrs))]
#[diagnostic(code(nu::parser::variable_not_valid))]
VariableNotValid(#[label = "variable name can't contain spaces or quotes"] Span),
#[error("Alias name not supported.")]
#[diagnostic(code(nu::parser::variable_not_valid), url(docsrs))]
#[diagnostic(code(nu::parser::variable_not_valid))]
AliasNotValid(
#[label = "alias name can't be a number, a filesize, or contain a hash # or caret ^"] Span,
),
#[error("Command name not supported.")]
#[diagnostic(code(nu::parser::variable_not_valid), url(docsrs))]
#[diagnostic(code(nu::parser::variable_not_valid))]
CommandDefNotValid(
#[label = "command name can't be a number, a filesize, or contain a hash # or caret ^"]
Span,
@ -188,19 +174,17 @@ pub enum ParseError {
#[error("Module not found.")]
#[diagnostic(
code(nu::parser::module_not_found),
url(docsrs),
help("module files and their paths must be available before your script is run as parsing occurs before anything is evaluated")
)]
ModuleNotFound(#[label = "module not found"] Span),
#[error("Cyclical module import.")]
#[diagnostic(code(nu::parser::cyclical_module_import), url(docsrs), help("{0}"))]
#[diagnostic(code(nu::parser::cyclical_module_import), help("{0}"))]
CyclicalModuleImport(String, #[label = "detected cyclical module import"] Span),
#[error("Can't export {0} named same as the module.")]
#[diagnostic(
code(nu::parser::named_as_module),
url(docsrs),
help("Module {1} can't export {0} named the same as the module. Either change the module name, or export `main` custom command.")
)]
NamedAsModule(
@ -212,19 +196,17 @@ pub enum ParseError {
#[error("Can't export alias defined as 'main'.")]
#[diagnostic(
code(nu::parser::export_main_alias_not_allowed),
url(docsrs),
help("Exporting aliases as 'main' is not allowed. Either rename the alias or convert it to a custom command.")
)]
ExportMainAliasNotAllowed(#[label = "can't export from module"] Span),
#[error("Active overlay not found.")]
#[diagnostic(code(nu::parser::active_overlay_not_found), url(docsrs))]
#[diagnostic(code(nu::parser::active_overlay_not_found))]
ActiveOverlayNotFound(#[label = "not an active overlay"] Span),
#[error("Overlay prefix mismatch.")]
#[diagnostic(
code(nu::parser::overlay_prefix_mismatch),
url(docsrs),
help("Overlay {0} already exists {1} a prefix. To add it again, do it {1} the --prefix flag.")
)]
OverlayPrefixMismatch(
@ -236,7 +218,6 @@ pub enum ParseError {
#[error("Module or overlay not found.")]
#[diagnostic(
code(nu::parser::module_or_overlay_not_found),
url(docsrs),
help("Requires either an existing overlay, a module, or an import pattern defining a module.")
)]
ModuleOrOverlayNotFound(#[label = "not a module or an overlay"] Span),
@ -244,7 +225,6 @@ pub enum ParseError {
#[error("Cannot remove the last overlay.")]
#[diagnostic(
code(nu::parser::cant_remove_last_overlay),
url(docsrs),
help("At least one overlay must always be active.")
)]
CantRemoveLastOverlay(#[label = "this is the last overlay, can't remove it"] Span),
@ -252,57 +232,55 @@ pub enum ParseError {
#[error("Cannot hide default overlay.")]
#[diagnostic(
code(nu::parser::cant_hide_default_overlay),
url(docsrs),
help("'{0}' is a default overlay. Default overlays cannot be hidden.")
)]
CantHideDefaultOverlay(String, #[label = "can't hide overlay"] Span),
#[error("Cannot add overlay.")]
#[diagnostic(code(nu::parser::cant_add_overlay_help), url(docsrs), help("{0}"))]
#[diagnostic(code(nu::parser::cant_add_overlay_help), help("{0}"))]
CantAddOverlayHelp(String, #[label = "cannot add this overlay"] Span),
#[error("Not found.")]
#[diagnostic(code(nu::parser::not_found), url(docsrs))]
#[diagnostic(code(nu::parser::not_found))]
NotFound(#[label = "did not find anything under this name"] Span),
#[error("Duplicate command definition within a block.")]
#[diagnostic(code(nu::parser::duplicate_command_def), url(docsrs))]
#[diagnostic(code(nu::parser::duplicate_command_def))]
DuplicateCommandDef(#[label = "defined more than once"] Span),
#[error("Unknown command.")]
#[diagnostic(
code(nu::parser::unknown_command),
url(docsrs),
// TODO: actual suggestions like "Did you mean `foo`?"
)]
UnknownCommand(#[label = "unknown command"] Span),
#[error("Non-UTF8 string.")]
#[diagnostic(code(nu::parser::non_utf8), url(docsrs))]
#[diagnostic(code(nu::parser::non_utf8))]
NonUtf8(#[label = "non-UTF8 string"] Span),
#[error("The `{0}` command doesn't have flag `{1}`.")]
#[diagnostic(code(nu::parser::unknown_flag), url(docsrs), help("{3}"))]
#[diagnostic(code(nu::parser::unknown_flag), help("{3}"))]
UnknownFlag(String, String, #[label = "unknown flag"] Span, String),
#[error("Unknown type.")]
#[diagnostic(code(nu::parser::unknown_type), url(docsrs))]
#[diagnostic(code(nu::parser::unknown_type))]
UnknownType(#[label = "unknown type"] Span),
#[error("Missing flag argument.")]
#[diagnostic(code(nu::parser::missing_flag_param), url(docsrs))]
#[diagnostic(code(nu::parser::missing_flag_param))]
MissingFlagParam(String, #[label = "flag missing {0} argument"] Span),
#[error("Batches of short flags can't take arguments.")]
#[diagnostic(code(nu::parser::short_flag_arg_cant_take_arg), url(docsrs))]
#[diagnostic(code(nu::parser::short_flag_arg_cant_take_arg))]
ShortFlagBatchCantTakeArg(#[label = "short flag batches can't take args"] Span),
#[error("Missing required positional argument.")]
#[diagnostic(code(nu::parser::missing_positional), url(docsrs), help("Usage: {2}"))]
#[diagnostic(code(nu::parser::missing_positional), help("Usage: {2}"))]
MissingPositional(String, #[label("missing {0}")] Span, String),
#[error("Missing argument to `{1}`.")]
#[diagnostic(code(nu::parser::keyword_missing_arg), url(docsrs))]
#[diagnostic(code(nu::parser::keyword_missing_arg))]
KeywordMissingArgument(
String,
String,
@ -310,39 +288,39 @@ pub enum ParseError {
),
#[error("Missing type.")]
#[diagnostic(code(nu::parser::missing_type), url(docsrs))]
#[diagnostic(code(nu::parser::missing_type))]
MissingType(#[label = "expected type"] Span),
#[error("Type mismatch.")]
#[diagnostic(code(nu::parser::type_mismatch), url(docsrs))]
#[diagnostic(code(nu::parser::type_mismatch))]
TypeMismatch(Type, Type, #[label("expected {0:?}, found {1:?}")] Span), // expected, found, span
#[error("Missing required flag.")]
#[diagnostic(code(nu::parser::missing_required_flag), url(docsrs))]
#[diagnostic(code(nu::parser::missing_required_flag))]
MissingRequiredFlag(String, #[label("missing required flag {0}")] Span),
#[error("Incomplete math expression.")]
#[diagnostic(code(nu::parser::incomplete_math_expression), url(docsrs))]
#[diagnostic(code(nu::parser::incomplete_math_expression))]
IncompleteMathExpression(#[label = "incomplete math expression"] Span),
#[error("Unknown state.")]
#[diagnostic(code(nu::parser::unknown_state), url(docsrs))]
#[diagnostic(code(nu::parser::unknown_state))]
UnknownState(String, #[label("{0}")] Span),
#[error("Internal error.")]
#[diagnostic(code(nu::parser::unknown_state), url(docsrs))]
#[diagnostic(code(nu::parser::unknown_state))]
InternalError(String, #[label("{0}")] Span),
#[error("Parser incomplete.")]
#[diagnostic(code(nu::parser::parser_incomplete), url(docsrs))]
#[diagnostic(code(nu::parser::parser_incomplete))]
IncompleteParser(#[label = "parser support missing for this expression"] Span),
#[error("Rest parameter needs a name.")]
#[diagnostic(code(nu::parser::rest_needs_name), url(docsrs))]
#[diagnostic(code(nu::parser::rest_needs_name))]
RestNeedsName(#[label = "needs a parameter name"] Span),
#[error("Parameter not correct type.")]
#[diagnostic(code(nu::parser::parameter_mismatch_type), url(docsrs))]
#[diagnostic(code(nu::parser::parameter_mismatch_type))]
ParameterMismatchType(
String,
String,
@ -351,39 +329,38 @@ pub enum ParseError {
),
#[error("Extra columns.")]
#[diagnostic(code(nu::parser::extra_columns), url(docsrs))]
#[diagnostic(code(nu::parser::extra_columns))]
ExtraColumns(
usize,
#[label("expected {0} column{}", if *.0 == 1 { "" } else { "s" })] Span,
),
#[error("Missing columns.")]
#[diagnostic(code(nu::parser::missing_columns), url(docsrs))]
#[diagnostic(code(nu::parser::missing_columns))]
MissingColumns(
usize,
#[label("expected {0} column{}", if *.0 == 1 { "" } else { "s" })] Span,
),
#[error("{0}")]
#[diagnostic(code(nu::parser::assignment_mismatch), url(docsrs))]
#[diagnostic(code(nu::parser::assignment_mismatch))]
AssignmentMismatch(String, String, #[label("{1}")] Span),
#[error("Missing import pattern.")]
#[diagnostic(code(nu::parser::missing_import_pattern), url(docsrs))]
#[diagnostic(code(nu::parser::missing_import_pattern))]
MissingImportPattern(#[label = "needs an import pattern"] Span),
#[error("Wrong import pattern structure.")]
#[diagnostic(code(nu::parser::missing_import_pattern), url(docsrs))]
#[diagnostic(code(nu::parser::missing_import_pattern))]
WrongImportPattern(#[label = "invalid import pattern structure"] Span),
#[error("Export not found.")]
#[diagnostic(code(nu::parser::export_not_found), url(docsrs))]
#[diagnostic(code(nu::parser::export_not_found))]
ExportNotFound(#[label = "could not find imports"] Span),
#[error("File not found")]
#[diagnostic(
code(nu::parser::sourced_file_not_found),
url(docsrs),
help("sourced files need to be available before your script is run")
)]
SourcedFileNotFound(String, #[label("File not found: {0}")] Span),
@ -391,13 +368,12 @@ pub enum ParseError {
#[error("File not found")]
#[diagnostic(
code(nu::parser::registered_file_not_found),
url(docsrs),
help("registered files need to be available before your script is run")
)]
RegisteredFileNotFound(String, #[label("File not found: {0}")] Span),
#[error("File not found")]
#[diagnostic(code(nu::parser::file_not_found), url(docsrs))]
#[diagnostic(code(nu::parser::file_not_found))]
FileNotFound(String, #[label("File not found: {0}")] Span),
/// Error while trying to read a file
@ -406,7 +382,7 @@ pub enum ParseError {
///
/// The error will show the result from a file operation
#[error("Error trying to read file")]
#[diagnostic(code(nu::shell::error_reading_file), url(docsrs))]
#[diagnostic(code(nu::shell::error_reading_file))]
ReadingFile(String, #[label("{0}")] Span),
/// Tried assigning non-constant value to a constant
@ -417,7 +393,6 @@ pub enum ParseError {
#[error("Not a constant.")]
#[diagnostic(
code(nu::parser::not_a_constant),
url(docsrs),
help("Only a subset of expressions are allowed constants during parsing. Try using the 'let' command or typing the value literally.")
)]
NotAConstant(#[label = "Value is not a parse-time constant"] Span),