powershell: Parse enum labels

[b4n]

https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_enum?view=powershell-7.4

---

:warning: Beware, I don't know anything about PowerShell! Yet, this seemed easy and useful enough.

If anybody with actual PowerShell knowledge could give this an overview that'd be great. @eht16 @kumarstack55 @iaalm maybe? The thing that most likely might need changing is the kind name. I used the "common" name for this type of construct, but maybe a more PowerShell-y one would be better, I don't know.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 85.41%. Comparing base (427159a) to head (2686322).

Additional details and impacted files

```diff @@ Coverage Diff @@ ## master #3998 +/- ## ======================================= Coverage 85.41% 85.41% ======================================= Files 235 235 Lines 56647 56660 +13 ======================================= + Hits 48384 48397 +13 Misses 8263 8263 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[iaalm]

Will take a look later today😁

[masatake]

About the letter for the kind, I gave a comment at https://github.com/universal-ctags/ctags/pull/3571#discussion_r1038788932. About the name, enumlabel looks better to me though I don't know PowerShell well.

[b4n]

@masatake good suggestion, the only reason I chose enumerator was to match the C parser, but it's probably good to be a little more language-specific here.

@iaalm do you have an opinion on the kind name? enumlabel indeed sounds good to me given the PowerShell docs seem to name it label.

[masatake]

@b4n, while you were absent, I added yet another overkill feature: parser versioning, which I have not documented well yet.

This change extends the interface of the PowerShell parser. Therefore I would like you to include the following changes:

diff --git a/docs/man-pages.rst b/docs/man-pages.rst
index d4eb16ab9..232d9bd43 100644
--- a/docs/man-pages.rst
+++ b/docs/man-pages.rst
@@ -34,6 +34,7 @@ Man pages
    ctags-lang-ldscript(7) <man/ctags-lang-ldscript.7.rst>
    ctags-lang-lex(7) <man/ctags-lang-lex.7.rst>
    ctags-lang-markdown(7) <man/ctags-lang-markdown.7.rst>
+   ctags-lang-powershell(7) <man/ctags-lang-powershell.7.rst>
    ctags-lang-python(7) <man/ctags-lang-python.7.rst>
    ctags-lang-r(7) <man/ctags-lang-r.7.rst>
    ctags-lang-rmarkdown(7) <man/ctags-lang-rmarkdown.7.rst>
diff --git a/docs/man/ctags-lang-powershell.7.rst b/docs/man/ctags-lang-powershell.7.rst
new file mode 100644
index 000000000..f971d4cc9
--- /dev/null
+++ b/docs/man/ctags-lang-powershell.7.rst
@@ -0,0 +1,34 @@
+.. _ctags-lang-powershell(7):
+
+==============================================================
+ctags-lang-powershell
+==============================================================
+
+Random notes about tagging PowerShell source code with Universal Ctags
+
+:Version: 6.1.0
+:Manual group: Universal Ctags
+:Manual section: 7
+
+SYNOPSIS
+--------
+|  **ctags** ... --languages=+PowerShell ...
+|  **ctags** ... --language-force=PowerShell ...
+|  **ctags** ... --map-powershell=+.ps1 ...
+|  **ctags** ... --map-powershell=+.psm1 ...
+
+DESCRIPTION
+-----------
+This man page gathers random notes about tagging PowerShell source code.
+
+VERSIONS
+--------
+
+Change since "0.0"
+~~~~~~~~~~~~~~~~~~
+
+* New kind ``enumlabel``
+
+SEE ALSO
+--------
+:ref:`ctags(1) <ctags(1)>`
diff --git a/man/ctags-lang-powershell.7.rst.in b/man/ctags-lang-powershell.7.rst.in
new file mode 100644
index 000000000..82fe58144
--- /dev/null
+++ b/man/ctags-lang-powershell.7.rst.in
@@ -0,0 +1,34 @@
+.. _ctags-lang-powershell(7):
+
+==============================================================
+ctags-lang-powershell
+==============================================================
+-----------------------------------------------------------------------
+Random notes about tagging PowerShell source code with Universal Ctags
+-----------------------------------------------------------------------
+:Version: @VERSION@
+:Manual group: Universal Ctags
+:Manual section: 7
+
+SYNOPSIS
+--------
+|  **@CTAGS_NAME_EXECUTABLE@** ... --languages=+PowerShell ...
+|  **@CTAGS_NAME_EXECUTABLE@** ... --language-force=PowerShell ...
+|  **@CTAGS_NAME_EXECUTABLE@** ... --map-powershell=+.ps1 ...
+|  **@CTAGS_NAME_EXECUTABLE@** ... --map-powershell=+.psm1 ...
+
+DESCRIPTION
+-----------
+This man page gathers random notes about tagging PowerShell source code.
+
+VERSIONS
+--------
+
+Change since "0.0"
+~~~~~~~~~~~~~~~~~~
+
+* New kind ``enumlabel``
+
+SEE ALSO
+--------
+ctags(1)
diff --git a/parsers/powershell.c b/parsers/powershell.c
index 8b52c5473..d8b2163de 100644
--- a/parsers/powershell.c
+++ b/parsers/powershell.c
@@ -801,5 +801,9 @@ extern parserDefinition* PowerShellParser (void)
    def->parser     = findPowerShellTags;
    def->keywordTable = PowerShellKeywordTable;
    def->keywordCount = ARRAY_SIZE (PowerShellKeywordTable);
+
+   def->versionCurrent = 1;
+   def->versionAge = 1;
+
    return def;
 }
diff --git a/man/GNUmakefile.am b/man/GNUmakefile.am
index fb76b20cf..f831324d9 100644
--- a/man/GNUmakefile.am
+++ b/man/GNUmakefile.am
@@ -45,6 +45,7 @@ GEN_IN_MAN_FILES = \
    ctags-lang-ldscript.7 \
    ctags-lang-lex.7 \
    ctags-lang-markdown.7 \
+   ctags-lang-powershell.7 \
    ctags-lang-python.7 \
    ctags-lang-r.7 \
    ctags-lang-rmarkdown.7 \

With this change, you'll see:

[yamato@dev64]~/var/ctags-github% ./ctags --version=PowerShell
parser/PowerShell: 1.1
[yamato@dev64]~/var/ctags-github% echo "enum X {}" > /tmp/foo.ps1; ./ctags --extras=+'{pseudo}' --pseudo-tags='{TAG_PARSER_VERSION}'  -o - /tmp/foo.ps1 
!_TAG_PARSER_VERSION!PowerShell 1.1 /current.age/
X   /tmp/foo.ps1    /^enum X {}$/;" g

I want to say "thank you" to the person who wrote the zsh-completion rules for u-ctags.

[b4n]

I switched to enumlabel as mentioned.

@masatake I added your patch (adjusting for the leading space vs. tabs), under your name -- home that's OK.

[masatake]

Thank you.