From 45e4d8c4316e48a3b3a84d03310dee3450b02e66 Mon Sep 17 00:00:00 2001 From: Laurence Morgan Date: Sun, 15 Sep 2024 16:30:11 +0100 Subject: [PATCH] website: subcategories for variables --- app/app.go | 4 ++-- docs/variables/argv.md | 2 +- docs/variables/columns.md | 2 +- docs/variables/hostname.md | 2 +- docs/variables/murex_argv.md | 2 ++ docs/variables/murex_exe.md | 2 +- docs/variables/numeric.md | 2 +- docs/variables/params.md | 2 +- docs/variables/self.md | 4 ++-- docs/variables/shell.md | 9 +++++---- gen/docgen.yaml | 22 ++++++++++++++++++++++ gen/includes/this-is-a-reserved-var.inc.md | 1 + gen/variables/ARGV_doc.yaml | 3 ++- gen/variables/COLUMNS_doc.yaml | 3 ++- gen/variables/EVENT_RETURN_doc.yaml | 1 + gen/variables/HOSTNAME_doc.yaml | 3 ++- gen/variables/MUREX_ARGV_doc.yaml | 3 +++ gen/variables/MUREX_EXE_doc.yaml | 3 ++- gen/variables/PARAMS_doc.yaml | 3 ++- gen/variables/PWDHIST_doc.yaml | 1 + gen/variables/PWD_doc.yaml | 1 + gen/variables/SELF_doc.yaml | 5 +++-- gen/variables/SHELL_doc.yaml | 10 ++++++---- gen/variables/meta-values_doc.yaml | 1 + gen/variables/numeric_doc.yaml | 3 ++- gen/vuepress/sidebar.ts | 2 +- version.svg | 2 +- 27 files changed, 70 insertions(+), 28 deletions(-) create mode 100644 gen/includes/this-is-a-reserved-var.inc.md diff --git a/app/app.go b/app/app.go index d79d25b01..3a55729b1 100644 --- a/app/app.go +++ b/app/app.go @@ -16,9 +16,9 @@ const Name = "murex" const ( Major = 6 Minor = 3 - Revision = 4141 + Revision = 4145 Branch = "develop" - BuildDate = "2024-09-15 15:44:46" + BuildDate = "2024-09-15 16:42:40" ) // Copyright is the copyright owner string diff --git a/docs/variables/argv.md b/docs/variables/argv.md index 3dbf506f4..6e6140ac4 100644 --- a/docs/variables/argv.md +++ b/docs/variables/argv.md @@ -9,7 +9,7 @@ scope. eg `function`, `private`, `autocomplete` or shell script. Unlike `$PARAMS`, `$ARGV` includes the function name. -This is a reserved variable so it cannot be changed. +This is a [reserved variable](/docs/user-guide/reserved-vars.md) so it cannot be changed. ## Examples diff --git a/docs/variables/columns.md b/docs/variables/columns.md index a168cc054..1642493a0 100644 --- a/docs/variables/columns.md +++ b/docs/variables/columns.md @@ -10,7 +10,7 @@ Some characters might be more than or less than 1 (one) cell in width, such as Chinese logograms and zero-width joiners. Whereas one ASCII character is the same width as one terminal cell. -This is a reserved variable so it cannot be changed. +This is a [reserved variable](/docs/user-guide/reserved-vars.md) so it cannot be changed. ## Other Reserved Variables diff --git a/docs/variables/hostname.md b/docs/variables/hostname.md index 418ac4539..ee51079e7 100644 --- a/docs/variables/hostname.md +++ b/docs/variables/hostname.md @@ -7,7 +7,7 @@ `HOSTNAME` returns the hostname of the machine (host / server / virtual machine / et al) that Murex is running from. -This is a reserved variable so it cannot be changed. +This is a [reserved variable](/docs/user-guide/reserved-vars.md) so it cannot be changed. ## Other Reserved Variables diff --git a/docs/variables/murex_argv.md b/docs/variables/murex_argv.md index d4b650ef7..474d4c543 100644 --- a/docs/variables/murex_argv.md +++ b/docs/variables/murex_argv.md @@ -7,6 +7,8 @@ `MUREX_ARGV` returns an array of the command name and parameters passed to the current running Murex shell +This is a [reserved variable](/docs/user-guide/reserved-vars.md) so it cannot be changed. + ## Examples ``` diff --git a/docs/variables/murex_exe.md b/docs/variables/murex_exe.md index 489d55fcb..8ceca553b 100644 --- a/docs/variables/murex_exe.md +++ b/docs/variables/murex_exe.md @@ -8,7 +8,7 @@ holds the full path to the running shell. The reason for defining a reserved variable is so that the shell path cannot be overridden. -This is a reserved variable so it cannot be changed. +This is a [reserved variable](/docs/user-guide/reserved-vars.md) so it cannot be changed. ## Other Reserved Variables diff --git a/docs/variables/numeric.md b/docs/variables/numeric.md index b50fb848f..be10a860f 100644 --- a/docs/variables/numeric.md +++ b/docs/variables/numeric.md @@ -6,7 +6,7 @@ Variables named `0` and above are the equivalent index value of `@ARGV`. -These are reserved variable so they cannot be changed. +These are {{link "reserved variables" "reserved-vars"}} so they cannot be changed. ## Examples diff --git a/docs/variables/params.md b/docs/variables/params.md index 4293fa134..e7235d7fa 100644 --- a/docs/variables/params.md +++ b/docs/variables/params.md @@ -9,7 +9,7 @@ eg `function`, `private`, `autocomplete` or shell script. Unlike `$ARGV`, `$PARAMS` does not include the function name. -This is a reserved variable so it cannot be changed. +This is a [reserved variable](/docs/user-guide/reserved-vars.md) so it cannot be changed. ## Examples diff --git a/docs/variables/self.md b/docs/variables/self.md index b8d37df37..cea7cc137 100644 --- a/docs/variables/self.md +++ b/docs/variables/self.md @@ -13,9 +13,9 @@ config are persistent within. In Murex, a variable declared inside an `if` or `foreach` block will be persistent outside of their blocks as long as you're still inside the same function. -Please see scoping document (link below) for more information on scoping. +Please read the {{link "scoping document" "scoping"}} for more information on scoping. -This is a reserved variable so it cannot be changed. +This is a [reserved variable](/docs/user-guide/reserved-vars.md) so it cannot be changed. ## Examples diff --git a/docs/variables/shell.md b/docs/variables/shell.md index caa61b445..db951f367 100644 --- a/docs/variables/shell.md +++ b/docs/variables/shell.md @@ -7,10 +7,11 @@ `SHELL` is an environmental variable containing the full path to the current shell -- which in our case is Murex. -This variable is set by Murex to conform to standards however, being an -environmental variable, it can be overwritten via `export`. Thus you are -recommended to use `MUREX_EXE`, which is a reserved variable, if you require -precision. +This variable is set by Murex to conform to POSIX standards. However, being an +environmental variable, it can be overwritten via `export`. + +For Murex specific code, you are recommended to use `MUREX_EXE`, which is a +reserved variable, and thus read only, if you require precision and safety. ## Other Reserved Variables diff --git a/gen/docgen.yaml b/gen/docgen.yaml index 06d51f97f..eedd518f9 100644 --- a/gen/docgen.yaml +++ b/gen/docgen.yaml @@ -225,6 +225,28 @@ Categories: CategoryTemplate: gen/variables-md-cat.tmpl DocumentTemplate: gen/variables-md-doc.tmpl + SubCategories: + - ID: vars.env + Title: Environmental Variables + VueIcon: arrows-turn-to-dots + Description: |- + Environmental variables are variables held at an operating system level and thus will get passed between running processes. + - ID: vars.scoped + Title: Scoped Variables + VueIcon: arrows-turn-to-dots + Description: |- + Scoped variables are defined within a specific function's scope. These might be reserved variables but they might also be used to provide structured returns from a particular scope. + - ID: vars.posix + Title: Defined by POSIX + VueIcon: arrows-turn-to-dots + Description: |- + These are variables defined by POSIX. In general they will be environmental variables, however in some cases Murex will follow the naming convention described in POSIX but return a reserved variable instead. + - ID: vars.reserved + Title: Reserved Variables + VueIcon: arrows-turn-to-dots + Description: |- + Reserved variables are read only values that are dynamically generated at the point of querying. They behave a little more like functions than variables, albeit the convenience of being called like a variable. + # pipes: # apis: diff --git a/gen/includes/this-is-a-reserved-var.inc.md b/gen/includes/this-is-a-reserved-var.inc.md new file mode 100644 index 000000000..886d3392c --- /dev/null +++ b/gen/includes/this-is-a-reserved-var.inc.md @@ -0,0 +1 @@ +This is a {{link "reserved variable" "reserved-vars"}} so it cannot be changed. diff --git a/gen/variables/ARGV_doc.yaml b/gen/variables/ARGV_doc.yaml index 7b93a5b67..c61dc2d2f 100644 --- a/gen/variables/ARGV_doc.yaml +++ b/gen/variables/ARGV_doc.yaml @@ -2,6 +2,7 @@ Title: >- `ARGV` (json) CategoryID: variables + SubCategoryIDs: [ vars.reserved, vars.scoped ] Summary: >- Array of the command name and parameters within a given scope @@ -11,7 +12,7 @@ Unlike `$PARAMS`, `$ARGV` includes the function name. - This is a reserved variable so it cannot be changed. + {{ include "gen/includes/this-is-a-reserved-var.inc.md" }} Examples: |- ``` » function example { $ARGV } diff --git a/gen/variables/COLUMNS_doc.yaml b/gen/variables/COLUMNS_doc.yaml index 7711a8183..4342165f1 100644 --- a/gen/variables/COLUMNS_doc.yaml +++ b/gen/variables/COLUMNS_doc.yaml @@ -2,6 +2,7 @@ Title: >- `COLUMNS` (int) CategoryID: variables + SubCategoryIDs: [ vars.reserved, vars.posix ] Summary: >- Character width of terminal Description: |- @@ -11,7 +12,7 @@ as Chinese logograms and zero-width joiners. Whereas one ASCII character is the same width as one terminal cell. - This is a reserved variable so it cannot be changed. + {{ include "gen/includes/this-is-a-reserved-var.inc.md" }} Synonyms: - columns - COLUMNS diff --git a/gen/variables/EVENT_RETURN_doc.yaml b/gen/variables/EVENT_RETURN_doc.yaml index ef6438bf5..9f3e49391 100644 --- a/gen/variables/EVENT_RETURN_doc.yaml +++ b/gen/variables/EVENT_RETURN_doc.yaml @@ -2,6 +2,7 @@ Title: >- `EVENT_RETURN` (json) CategoryID: variables + SubCategoryIDs: [ vars.scoped ] Summary: >- Return values for events Description: |- diff --git a/gen/variables/HOSTNAME_doc.yaml b/gen/variables/HOSTNAME_doc.yaml index 91defd79d..e55f03fb9 100644 --- a/gen/variables/HOSTNAME_doc.yaml +++ b/gen/variables/HOSTNAME_doc.yaml @@ -2,13 +2,14 @@ Title: >- `HOSTNAME` (str) CategoryID: variables + SubCategoryIDs: [ vars.reserved ] Summary: >- Hostname of the current machine Description: |- `HOSTNAME` returns the hostname of the machine (host / server / virtual machine / et al) that Murex is running from. - This is a reserved variable so it cannot be changed. + {{ include "gen/includes/this-is-a-reserved-var.inc.md" }} Synonyms: - hostname - HOSTNAME diff --git a/gen/variables/MUREX_ARGV_doc.yaml b/gen/variables/MUREX_ARGV_doc.yaml index 6b6b2601c..a4df62ff5 100644 --- a/gen/variables/MUREX_ARGV_doc.yaml +++ b/gen/variables/MUREX_ARGV_doc.yaml @@ -2,11 +2,14 @@ Title: >- `MUREX_ARGV` (json) CategoryID: variables + SubCategoryIDs: [ vars.reserved ] Summary: >- Array of the command name and parameters passed to the current shell Description: |- `MUREX_ARGV` returns an array of the command name and parameters passed to the current running Murex shell + + {{ include "gen/includes/this-is-a-reserved-var.inc.md" }} Examples: |- ``` » murex -trypipe -c '$MUREX_ARGV' diff --git a/gen/variables/MUREX_EXE_doc.yaml b/gen/variables/MUREX_EXE_doc.yaml index 56eedf795..bb66145a0 100644 --- a/gen/variables/MUREX_EXE_doc.yaml +++ b/gen/variables/MUREX_EXE_doc.yaml @@ -2,6 +2,7 @@ Title: >- `MUREX_EXE` (path) CategoryID: variables + SubCategoryIDs: [ vars.reserved ] Summary: >- Absolute path to running shell Description: |- @@ -9,7 +10,7 @@ holds the full path to the running shell. The reason for defining a reserved variable is so that the shell path cannot be overridden. - This is a reserved variable so it cannot be changed. + {{ include "gen/includes/this-is-a-reserved-var.inc.md" }} Synonyms: - murex_exe - MUREX_EXE diff --git a/gen/variables/PARAMS_doc.yaml b/gen/variables/PARAMS_doc.yaml index 42a27b76b..228faf8a5 100644 --- a/gen/variables/PARAMS_doc.yaml +++ b/gen/variables/PARAMS_doc.yaml @@ -2,6 +2,7 @@ Title: >- `PARAMS` (json) CategoryID: variables + SubCategoryIDs: [ vars.reserved, vars.scoped ] Summary: >- Array of the parameters within a given scope Description: |- @@ -10,7 +11,7 @@ Unlike `$ARGV`, `$PARAMS` does not include the function name. - This is a reserved variable so it cannot be changed. + {{ include "gen/includes/this-is-a-reserved-var.inc.md" }} Examples: |- ``` » function example { $PARAMS } diff --git a/gen/variables/PWDHIST_doc.yaml b/gen/variables/PWDHIST_doc.yaml index baa74f07a..0034a6102 100644 --- a/gen/variables/PWDHIST_doc.yaml +++ b/gen/variables/PWDHIST_doc.yaml @@ -2,6 +2,7 @@ Title: >- `PWDHIST` (json) CategoryID: variables + SubCategoryIDs: [ vars.env ] Summary: >- History of each change to the sessions working directory Description: |- diff --git a/gen/variables/PWD_doc.yaml b/gen/variables/PWD_doc.yaml index ecabe0c7b..d708c984e 100644 --- a/gen/variables/PWD_doc.yaml +++ b/gen/variables/PWD_doc.yaml @@ -2,6 +2,7 @@ Title: >- `PWD` (path) CategoryID: variables + SubCategoryIDs: [ vars.posix, vars.env ] Summary: >- Current working directory Description: |- diff --git a/gen/variables/SELF_doc.yaml b/gen/variables/SELF_doc.yaml index 74a505579..9177d90ff 100644 --- a/gen/variables/SELF_doc.yaml +++ b/gen/variables/SELF_doc.yaml @@ -2,6 +2,7 @@ Title: >- `SELF` (json) CategoryID: variables + SubCategoryIDs: [ vars.reserved, vars.scoped ] Summary: >- Meta information about the running scope. Description: |- @@ -14,9 +15,9 @@ `foreach` block will be persistent outside of their blocks as long as you're still inside the same function. - Please see scoping document (link below) for more information on scoping. + Please read the {{link "scoping document" "scoping"}} for more information on scoping. - This is a reserved variable so it cannot be changed. + {{ include "gen/includes/this-is-a-reserved-var.inc.md" }} Examples: |- ``` » function example { $SELF } diff --git a/gen/variables/SHELL_doc.yaml b/gen/variables/SHELL_doc.yaml index ed50d1ce8..cc8da84a4 100644 --- a/gen/variables/SHELL_doc.yaml +++ b/gen/variables/SHELL_doc.yaml @@ -2,16 +2,18 @@ Title: >- `SHELL` (str) CategoryID: variables + SubCategoryIDs: [ vars.posix, vars.env ] Summary: >- Path of current shell Description: |- `SHELL` is an environmental variable containing the full path to the current shell -- which in our case is Murex. - This variable is set by Murex to conform to standards however, being an - environmental variable, it can be overwritten via `export`. Thus you are - recommended to use `MUREX_EXE`, which is a reserved variable, if you require - precision. + This variable is set by Murex to conform to POSIX standards. However, being an + environmental variable, it can be overwritten via `export`. + + For Murex specific code, you are recommended to use `MUREX_EXE`, which is a + reserved variable, and thus read only, if you require precision and safety. Examples: Synonyms: - shell diff --git a/gen/variables/meta-values_doc.yaml b/gen/variables/meta-values_doc.yaml index 6b7e52486..dd50a0a1a 100644 --- a/gen/variables/meta-values_doc.yaml +++ b/gen/variables/meta-values_doc.yaml @@ -2,6 +2,7 @@ Title: >- `$.`, Meta Values (json) CategoryID: variables + SubCategoryIDs: [ vars.scoped ] Summary: >- State information for iteration blocks Description: |- diff --git a/gen/variables/numeric_doc.yaml b/gen/variables/numeric_doc.yaml index d0a17be37..576aa4b0e 100644 --- a/gen/variables/numeric_doc.yaml +++ b/gen/variables/numeric_doc.yaml @@ -2,12 +2,13 @@ Title: >- Numeric (str) CategoryID: variables + SubCategoryIDs: [ vars.reserved ] Summary: >- Variables who's name is a positive integer, eg `0`, `1`, `2`, `3` and above Description: |- Variables named `0` and above are the equivalent index value of `@ARGV`. - These are reserved variable so they cannot be changed. + These are {{link "reserved variables" "reserved-vars"}} so they cannot be changed. Examples: |- ``` » function example { out $0 $2 } diff --git a/gen/vuepress/sidebar.ts b/gen/vuepress/sidebar.ts index 78f1786c0..a108e0bc4 100644 --- a/gen/vuepress/sidebar.ts +++ b/gen/vuepress/sidebar.ts @@ -55,7 +55,7 @@ export default sidebar({ collapsible: true, }, { - text: "Spacial Variables", + text: "Special Variables", icon: "dollar", prefix: "variables/", children: "structure", diff --git a/version.svg b/version.svg index 0b9b1537e..54ce222b4 100644 --- a/version.svg +++ b/version.svg @@ -1 +1 @@ -Version: 6.3.4141Version6.3.4141 +Version: 6.3.4145Version6.3.4145