powershell: Parse enum labels

[b4n]

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

---

⚠️ 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]

Codecov Report

All modified and coverable lines are covered by tests ✅

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

Additional details and impacted files

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

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[iaalm]

Will take a look later today😁

[iaalm]

LGTM

[masatake]

About the letter for the kind, I gave a comment at #3571 (comment). 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.