feat: add nameless identity function

Author: iamgio

docs/syntax-of-a-function-call.qd

@@ -98,6 +98,18 @@ You can append additional arguments to any function in the chain. Just keep in m
 
 Many core functions are designed to be called in a chain, for example [`None` operations](none.qd#examples).
 
+### Identity function
+
+A nameless function call uses the syntax `.{value}`, omitting the function name entirely. It acts as an identity function, passing its argument through unchanged. This is especially useful as a starting point for a chain when you want to begin with a literal value:
+
+.examplemirror
+    .{30}::multiply {2}
+
+.examplemirror
+    .{Hello}::text variant:{smallcaps}
+
+Without the nameless call, you would need to either use a variable or nest the calls manually.
+
 ## Tight function calls
 
 A function call must normally be surrounded by whitespace, a symbol, or the beginning or end of a line. This means that a call directly adjacent to a word character is not recognized:

quarkdown-core/src/main/kotlin/com/quarkdown/core/lexer/patterns/FunctionCallPatterns.kt

@@ -24,9 +24,10 @@ class FunctionCallPatterns {
             wrap = { error("Inline function call tokens are constructed by the walker") },
             // The name of the function prefixed by a dot.
             regex =
-                RegexBuilder("(?:(?<=before)(?=call))|(?:(?=wrapcall))")
+                RegexBuilder("(?:(?<=before)(?=call))|(?:(?<=before)(?=beginarg))|(?:(?=wrapcall))|(?:(?=wrapbeginarg))")
                     .withReference("before", FUNCTION_CALL_PATTERN_BEFORE)
                     .withReference("call", "begin(name)")
+                    .withReference("beginarg", "begin" + Regex.escape(FunctionCallGrammar.ARGUMENT_BEGIN.toString()))
                     .withReference("wrap", Regex.escape(FunctionCallGrammar.ARGUMENT_BEGIN.toString()))
                     .withReference("begin", Regex.escape(FunctionCallGrammar.BEGIN.toString()))
                     .withReference("name", FunctionCallGrammar.IDENTIFIER_PATTERN)

quarkdown-core/src/main/kotlin/com/quarkdown/core/parser/walker/funcall/FunctionCallGrammar.kt

@@ -241,31 +241,41 @@ class FunctionCallGrammar(
         }
 
     /**
-     * Parses a single function call.
-     * A function call consists of a function name, inline arguments and an optional body argument.
+     * Parses the arguments and optional body of a function call, shared by both [namedCallParser] and [namelessCallParser].
      */
-    private val callParser =
-        (
-            // Function name.
-            identifier and
-                // Inline arguments.
-                zeroOrMore(argumentParser) and
-                // Body argument.
-                optional(-optional(whitespace) and bodyArgumentParser)
-        ) map { (id, args, body) ->
-            WalkedFunctionCall(
-                id.text,
-                args,
-                body,
-            )
+    private val argumentsParser =
+        // Inline arguments.
+        zeroOrMore(argumentParser) and
+            // Body argument.
+            optional(-optional(whitespace) and bodyArgumentParser)
+
+    /**
+     * Parses a named function call, where the function name is required.
+     * This is used for chained calls (after `::`) where a name is mandatory.
+     */
+    private val namedCallParser =
+        (identifier and argumentsParser) map { (id, argsAndBody) ->
+            val (args, body) = argsAndBody
+            WalkedFunctionCall(id.text, args, body)
+        }
+
+    /**
+     * Parses a nameless (identity) function call, where the function name is omitted (e.g. `.{value}`).
+     * This is only allowed as the first call in a chain, not after `::`.
+     */
+    private val namelessCallParser =
+        argumentsParser map { (args, body) ->
+            WalkedFunctionCall("", args, body)
         }
 
     /**
      * Parses a chain of function calls, separated by [chainSeparator].
+     * The first call in the chain may be nameless (e.g. `.{value}::bar`),
+     * but subsequent calls after `::` must have a name.
      * The result is an ordered linked list of [WalkedFunctionCall]s, and the first of them is returned.
      */
     private val chainCallParser =
-        callParser and zeroOrMore(-chainSeparator and callParser) map { (first, rest) ->
+        (namedCallParser or namelessCallParser) and zeroOrMore(-chainSeparator and namedCallParser) map { (first, rest) ->
             var current = first
             for (next in rest) {
                 current.next = next

quarkdown-core/src/test/kotlin/com/quarkdown/core/BlockParserTest.kt

@@ -1222,6 +1222,21 @@ class BlockParserTest {
                 )
             }
         }
+
+        // Nameless (identity) function calls.
+
+        with(nodes.next()) {
+            assertEquals("", name)
+            assertEquals(1, arguments.size)
+            assertEquals("hello", arguments[0].value.unwrappedValue)
+        }
+
+        with(nodes.next()) {
+            assertEquals("", name)
+            assertEquals(2, arguments.size)
+            assertEquals("arg1", arguments[0].value.unwrappedValue)
+            assertEquals("arg2", arguments[1].value.unwrappedValue)
+        }
     }
 
     /**
@@ -1314,6 +1329,50 @@ class BlockParserTest {
             assertEquals("bar", (arguments.first().expression as UncheckedFunctionCall<*>).name)
         }
 
+        // .{x}::bar {y}
+        with(nodes.next()) {
+            assertEquals("bar", name)
+            assertEquals(2, arguments.size)
+            assertEquals("", (arguments.first().expression as UncheckedFunctionCall<*>).name)
+            assertEquals("y", arguments[1].value.unwrappedValue)
+        }
+
+        // .{10}::multiply {2}::sum {5}
+        with(nodes.next()) {
+            assertEquals("sum", name)
+            assertEquals(2, arguments.size)
+            assertEquals("5", arguments[1].value.unwrappedValue)
+            val multiply = arguments.first().expression as UncheckedFunctionCall<*>
+            assertEquals("multiply", multiply.name)
+        }
+
         assertFalse(nodes.hasNext())
     }
+
+    /**
+     * Verifies that nameless (identity) function calls are parsed correctly
+     * as inline function calls within paragraphs.
+     */
+    @Test
+    fun namelessInlineFunctionCall() {
+        // Nameless call between text.
+        with(blocksIterator<Paragraph>("hello .{x} world").next()) {
+            val children = children.iterator()
+            assertEquals("hello ", assertIs<Text>(children.next()).text)
+            with(assertIs<FunctionCallNode>(children.next())) {
+                assertEquals("", name)
+                assertEquals(1, arguments.size)
+                assertEquals("x", arguments[0].value.unwrappedValue)
+            }
+            assertEquals(" world", assertIs<Text>(children.next()).text)
+            assertFalse(children.hasNext())
+        }
+
+        // Wrapped nameless call.
+        with(blocksIterator<FunctionCallNode>("{.{x}}").next()) {
+            assertEquals("", name)
+            assertEquals(1, arguments.size)
+            assertEquals("x", arguments[0].value.unwrappedValue)
+        }
+    }
 }

quarkdown-core/src/test/kotlin/com/quarkdown/core/LexerTest.kt

@@ -672,6 +672,50 @@ class LexerTest {
             assertEquals("bar", value.next!!.name)
             assertEquals(1, value.next!!.arguments.size)
         }
+
+        // Nameless (identity) function calls.
+
+        with(walk(".{x}")) {
+            assertEquals("", value.name)
+            assertEquals(".{x}".length, endIndex)
+            with(value.arguments.single()) {
+                assertEquals("x", value)
+                assertNull(name)
+            }
+        }
+
+        with(walk(".{x} {y}")) {
+            assertEquals("", value.name)
+            assertEquals("x", value.arguments[0].value)
+            assertEquals("y", value.arguments[1].value)
+        }
+
+        with(walk(".{x}::bar {y}")) {
+            assertEquals("", value.name)
+            assertEquals(1, value.arguments.size)
+            assertEquals("bar", value.next!!.name)
+            assertEquals(1, value.next!!.arguments.size)
+        }
+
+        // Trailing `::` should not produce a nameless chained call.
+        with(walk(".foo::")) {
+            assertEquals("foo", value.name)
+            assertNull(value.next)
+            // The `::` is not consumed: the walker stops at the end of the named call.
+            assertEquals(".foo".length, endIndex)
+        }
+
+        with(walk(".{x}::bar {y}::baz {z}")) {
+            assertEquals("", value.name)
+            assertEquals("bar", value.next!!.name)
+            assertEquals("baz", value.next!!.next!!.name)
+        }
+
+        with(walk("{.{x}}")) {
+            assertEquals("", value.name)
+            assertEquals("{.{x}}".length, endIndex)
+            assertEquals("x", value.arguments.single().value)
+        }
     }
 
     /**
@@ -851,4 +895,50 @@ class LexerTest {
         assertEquals("second", tokens[1].walkerResult.value.name)
         assertEquals("third", tokens[2].walkerResult.value.name)
     }
+
+    /**
+     * Verifies that nameless (identity) function calls are tokenized correctly at the inline level.
+     */
+    @Test
+    fun namelessInlineFunctionCall() {
+        with(inlineLex(".{x}")) {
+            assertIs<FunctionCallToken>(next())
+            assertFalse(hasNext())
+        }
+
+        with(inlineLex("hello .{x} world")) {
+            assertIs<PlainTextToken>(next())
+            assertIs<FunctionCallToken>(next())
+            assertIs<PlainTextToken>(next())
+            assertFalse(hasNext())
+        }
+
+        with(inlineLex("{.{x}}")) {
+            assertIs<FunctionCallToken>(next())
+            assertFalse(hasNext())
+        }
+    }
+
+    /**
+     * Verifies that nameless (identity) function calls are tokenized correctly at the block level.
+     */
+    @Test
+    fun namelessBlockFunctionCall() {
+        val tokens =
+            blockLexer(".{hello}")
+                .tokenize()
+                .filterIsInstance<FunctionCallToken>()
+                .toList()
+
+        assertEquals(1, tokens.size)
+        with(tokens.single()) {
+            assertEquals("", walkerResult.value.name)
+            assertEquals(
+                "hello",
+                walkerResult.value.arguments
+                    .single()
+                    .value,
+            )
+        }
+    }
 }

quarkdown-core/src/test/resources/parsing/functioncall-chain.md

@@ -2,4 +2,8 @@
 
 .foo {x}::bar name:{y}
 
-.foo {x}::bar {y}::baz {z}
+.foo {x}::bar {y}::baz {z}
+
+.{x}::bar {y}
+
+.{10}::multiply {2}::sum {5}

quarkdown-core/src/test/resources/parsing/functioncall.md

@@ -42,4 +42,8 @@ not body
 .function {arg{1}} {arg2}}
 
 .function {arg{1} arg} { { arg2 } }
-    body content
+    body content
+
+.{hello}
+
+.{arg1} {arg2}

quarkdown-lsp/src/main/kotlin/com/quarkdown/lsp/cache/CacheableFunctionCatalogue.kt

@@ -63,5 +63,5 @@ object CacheableFunctionCatalogue {
         nameQuery: String,
     ): Sequence<DocumentedFunction> =
         getCatalogue(docsDirectory)
-            .filter { it.data.name.startsWith(nameQuery, ignoreCase = true) }
+            .filter { it.data.name.isNotEmpty() && it.data.name.startsWith(nameQuery, ignoreCase = true) }
 }

quarkdown-lsp/src/test/kotlin/com/quarkdown/lsp/FunctionCallTokenizerTest.kt

@@ -249,4 +249,86 @@ class FunctionCallTokenizerTest {
         assertNotNull(paramNameToken)
         assertEquals("param", paramNameToken.lexeme)
     }
+
+    @Test
+    fun `nameless function call`() {
+        val text = ".{hello}"
+        val calls = tokenizer.getFunctionCalls(text)
+
+        assertEquals(1, calls.size)
+
+        val call = calls.first()
+        assertEquals(0..text.length, call.range)
+
+        // No FUNCTION_NAME token should be present.
+        val nameToken = call.tokens.find { it.type == FunctionCallToken.Type.FUNCTION_NAME }
+        assertEquals(null, nameToken)
+
+        // The BEGIN token is still present.
+        val beginToken = call.tokens.find { it.type == FunctionCallToken.Type.BEGIN }
+        assertNotNull(beginToken)
+        assertEquals(0..1, beginToken.range)
+
+        // The argument is tokenized normally.
+        val argValueToken = call.tokens.find { it.type == FunctionCallToken.Type.INLINE_ARGUMENT_VALUE }
+        assertNotNull(argValueToken)
+        assertEquals("hello", argValueToken.lexeme)
+    }
+
+    @Test
+    fun `nameless function call with chaining`() {
+        val text = ".{x}::bar {y}"
+        val calls = tokenizer.getFunctionCalls(text)
+
+        assertEquals(1, calls.size)
+
+        val call = calls.first()
+        val tokens = call.tokens.iterator()
+
+        assertEquals(FunctionCallToken.Type.BEGIN, tokens.next().type)
+        // No FUNCTION_NAME for the nameless part — argument follows directly.
+        assertEquals(FunctionCallToken.Type.INLINE_ARGUMENT_BEGIN, tokens.next().type)
+        assertEquals(FunctionCallToken.Type.INLINE_ARGUMENT_VALUE, tokens.next().type)
+        assertEquals(FunctionCallToken.Type.INLINE_ARGUMENT_END, tokens.next().type)
+        assertEquals(FunctionCallToken.Type.CHAINING_SEPARATOR, tokens.next().type)
+        // The chained function has a name.
+        with(tokens.next()) {
+            assertEquals(FunctionCallToken.Type.FUNCTION_NAME, type)
+            assertEquals("bar", lexeme)
+        }
+        assertEquals(FunctionCallToken.Type.INLINE_ARGUMENT_BEGIN, tokens.next().type)
+        assertEquals(FunctionCallToken.Type.INLINE_ARGUMENT_VALUE, tokens.next().type)
+        assertEquals(FunctionCallToken.Type.INLINE_ARGUMENT_END, tokens.next().type)
+        assertFalse(tokens.hasNext())
+    }
+
+    @Test
+    fun `nameless function call in text`() {
+        val text = "hello .{world} goodbye"
+        val calls = tokenizer.getFunctionCalls(text)
+
+        assertEquals(1, calls.size)
+
+        val call = calls.first()
+        val nameToken = call.tokens.find { it.type == FunctionCallToken.Type.FUNCTION_NAME }
+        assertEquals(null, nameToken)
+
+        val argValueToken = call.tokens.find { it.type == FunctionCallToken.Type.INLINE_ARGUMENT_VALUE }
+        assertNotNull(argValueToken)
+        assertEquals("world", argValueToken.lexeme)
+    }
+
+    @Test
+    fun `wrapped nameless function call`() {
+        val text = "{.{x}}"
+        val calls = tokenizer.getFunctionCalls(text)
+
+        assertEquals(1, calls.size)
+
+        val call = calls.first()
+        assertEquals(0..text.length, call.range)
+
+        val nameToken = call.tokens.find { it.type == FunctionCallToken.Type.FUNCTION_NAME }
+        assertEquals(null, nameToken)
+    }
 }