Allow role refs to have an entrypoint.

Author: felixfontein

changelogs/fragments/442-extend-ansible-markup.yml

@@ -0,0 +1,2 @@
+major_changes:
+  - "Extend plugin reference ``P(...)`` to allow referencing a role's entrypoint (https://github.com/ansible-community/antsibull-docs-ts/pull/442)."

src/ansible.ts

@@ -8,6 +8,10 @@ export function isFQCN(input: string): boolean {
   return input.match(/^[A-Za-z0-9_]+\.[A-Za-z0-9_]+(?:\.[A-Za-z0-9_]+)+$/) !== null;
 }
 
+export function isEntrypoint(input: string): boolean {
+  return input.match(/^[A-Za-z0-9_]+$/) !== null;
+}
+
 export function isPluginType(input: string): boolean {
   /* We do not want to hard-code a list of valid plugin types that might be inaccurate, so we simply check whether this is a valid kind of Python identifier usually used for plugin types. If ansible-core ever adds one with digits, we'll have to update this. */
   return /^[a-z_]+$/.test(input);

src/dom.ts

@@ -52,6 +52,7 @@ export interface ModulePart extends Part {
 export interface PluginPart extends Part {
   type: PartType.PLUGIN;
   plugin: PluginIdentifier;
+  entrypoint: string | undefined; // can be present if plugin.type == 'role'
 }
 
 export interface URLPart extends Part {

src/parser.spec.ts

@@ -131,7 +131,12 @@ describe('parser', (): void => {
         { type: PartType.TEXT, text: 'foo ', source: undefined },
         { type: PartType.ENV_VARIABLE, name: 'a),b', source: undefined },
         { type: PartType.TEXT, text: ' ', source: undefined },
-        { type: PartType.PLUGIN, plugin: { fqcn: 'foo.bar.baz', type: 'bam' }, source: undefined },
+        {
+          type: PartType.PLUGIN,
+          plugin: { fqcn: 'foo.bar.baz', type: 'bam' },
+          entrypoint: undefined,
+          source: undefined,
+        },
         { type: PartType.TEXT, text: ' baz ', source: undefined },
         { type: PartType.OPTION_VALUE, value: ' b,na)\\m, ', source: undefined },
         { type: PartType.TEXT, text: ' ', source: undefined },
@@ -147,6 +152,23 @@ describe('parser', (): void => {
         { type: PartType.TEXT, text: ' ', source: undefined },
       ],
     ]);
+    expect(parse('P(foo.bar.baz#role) P(foo.bar.baz#role:entrypoint)')).toEqual([
+      [
+        {
+          type: PartType.PLUGIN,
+          plugin: { fqcn: 'foo.bar.baz', type: 'role' },
+          entrypoint: undefined,
+          source: undefined,
+        },
+        { type: PartType.TEXT, text: ' ', source: undefined },
+        {
+          type: PartType.PLUGIN,
+          plugin: { fqcn: 'foo.bar.baz', type: 'role' },
+          entrypoint: 'entrypoint',
+          source: undefined,
+        },
+      ],
+    ]);
   });
   it('semantic markup test (with source)', (): void => {
     expect(parse('foo E(a\\),b) P(foo.bar.baz#bam) baz V( b\\,\\na\\)\\\\m\\, ) O(foo) ', { addSource: true })).toEqual(
@@ -155,7 +177,12 @@ describe('parser', (): void => {
           { type: PartType.TEXT, text: 'foo ', source: 'foo ' },
           { type: PartType.ENV_VARIABLE, name: 'a),b', source: 'E(a\\),b)' },
           { type: PartType.TEXT, text: ' ', source: ' ' },
-          { type: PartType.PLUGIN, plugin: { fqcn: 'foo.bar.baz', type: 'bam' }, source: 'P(foo.bar.baz#bam)' },
+          {
+            type: PartType.PLUGIN,
+            plugin: { fqcn: 'foo.bar.baz', type: 'bam' },
+            entrypoint: undefined,
+            source: 'P(foo.bar.baz#bam)',
+          },
           { type: PartType.TEXT, text: ' baz ', source: ' baz ' },
           { type: PartType.OPTION_VALUE, value: ' b,na)\\m, ', source: 'V( b\\,\\na\\)\\\\m\\, )' },
           { type: PartType.TEXT, text: ' ', source: ' ' },
@@ -172,6 +199,23 @@ describe('parser', (): void => {
         ],
       ],
     );
+    expect(parse('P(foo.bar.baz#role) P(foo.bar.baz#role:entrypoint)')).toEqual([
+      [
+        {
+          type: PartType.PLUGIN,
+          plugin: { fqcn: 'foo.bar.baz', type: 'role' },
+          entrypoint: undefined,
+          source: undefined,
+        },
+        { type: PartType.TEXT, text: ' ', source: undefined },
+        {
+          type: PartType.PLUGIN,
+          plugin: { fqcn: 'foo.bar.baz', type: 'role' },
+          entrypoint: 'entrypoint',
+          source: undefined,
+        },
+      ],
+    ]);
   });
   it('semantic markup option name', (): void => {
     expect(parse('O(foo)')).toEqual([
@@ -432,6 +476,12 @@ describe('parser', (): void => {
     expect(async () => parse('P(foo.bar.baz#b m)', { errors: 'exception', helpfulErrors: false })).rejects.toThrow(
       'While parsing P() at index 1: Plugin type "b m" is not valid',
     );
+    expect(async () =>
+      parse('P(foo.bar.baz#module:e p)', { errors: 'exception', helpfulErrors: false }),
+    ).rejects.toThrow('While parsing P() at index 1: Entrypoint "e p" is not valid');
+    expect(async () =>
+      parse('P(foo.bar.baz#module:entrypoint)', { errors: 'exception', helpfulErrors: false }),
+    ).rejects.toThrow('While parsing P() at index 1: Only role references can have entrypoints');
   });
   it('bad option name/return value (throw error)', (): void => {
     expect(async () =>
@@ -446,6 +496,9 @@ describe('parser', (): void => {
     expect(async () => parse('O(foo.bar.baz#role:bam)', { errors: 'exception', helpfulErrors: false })).rejects.toThrow(
       'While parsing O() at index 1: Role reference is missing entrypoint',
     );
+    expect(async () =>
+      parse('O(foo.bar.baz#role:e p:bam)', { errors: 'exception', helpfulErrors: false }),
+    ).rejects.toThrow('While parsing O() at index 1: Entrypoint "e p" is not valid');
   });
   it('bad parameter parsing (no escaping, error message)', (): void => {
     expect(parse('M(', { helpfulErrors: false })).toEqual([

src/parser.ts

@@ -5,7 +5,7 @@
 */
 
 import { ParsingOptions, PluginIdentifier, Whitespace } from './opts';
-import { isFQCN, isPluginType } from './ansible';
+import { isFQCN, isPluginType, isEntrypoint } from './ansible';
 import { parseEscapedArgs, parseUnescapedArgs } from './parser-impl';
 import {
   PartType,
@@ -72,6 +72,9 @@ function parseOptionLike(
     if (idx >= 0) {
       entrypoint = text.substr(0, idx);
       text = text.substr(idx + 1);
+      if (!isEntrypoint(entrypoint)) {
+        throw Error(`Entrypoint ${repr(entrypoint)} is not valid`);
+      }
     }
     if (entrypoint === undefined) {
       throw Error('Role reference is missing entrypoint');
@@ -258,11 +261,28 @@ const PARSER: CommandParserEx[] = [
       if (!isFQCN(fqcn)) {
         throw Error(`Plugin name ${repr(fqcn)} is not a FQCN`);
       }
-      const type = m[2] as string;
+      let type = m[2] as string;
+      let entrypoint: string | undefined;
+      const m2 = /^([^:]+):([^:]+)$/.exec(type);
+      if (m2) {
+        type = m2[1] as string;
+        entrypoint = m2[2] as string;
+        if (!isEntrypoint(entrypoint)) {
+          throw Error(`Entrypoint ${repr(entrypoint)} is not valid`);
+        }
+      }
       if (!isPluginType(type)) {
         throw Error(`Plugin type ${repr(type)} is not valid`);
       }
-      return <PluginPart>{ type: PartType.PLUGIN, plugin: { fqcn: fqcn, type: type }, source: source };
+      if (entrypoint && type !== 'role') {
+        throw Error('Only role references can have entrypoints');
+      }
+      return <PluginPart>{
+        type: PartType.PLUGIN,
+        plugin: { fqcn: fqcn, type: type },
+        entrypoint: entrypoint,
+        source: source,
+      };
     },
   },
   {