001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.commons.svl;
018
019import java.util.*;
020
021/**
022 * SPI for SVL {@code #{...}} script-evaluation functions.
023 *
024 * <p>
025 * A {@code VarFunction} is invoked when an SVL template contains a
026 * <c>#{name(arg1, arg2, ...)}</c> reference — distinct from {@code ${X:...}} variables. Functions
027 * compose freely with {@code ${...}} lookups and other {@code #{...}} calls; arguments are
028 * pre-resolved by the runtime before {@link #invoke(VarResolverSession, List) invoke} is called.
029 *
030 * <h2 class='section'>Naming note:</h2>
031 * <p>
032 * Named {@code VarFunction} rather than the shorter {@code Function} because Juneau's
033 * serializer/parser/test code makes heavy use of {@link java.util.function.Function} and
034 * routinely co-imports {@code org.apache.juneau.commons.svl.*}; a bare {@code Function} type in
035 * this package would trigger ambiguous-reference errors across many callers. The chosen name
036 * also matches the existing {@code Var}/{@code VarResolver}/{@code VarTemplate}/{@code VarResolverSession}
037 * naming family.
038 *
039 * <p>
040 * Implementations can register through any of four discovery channels (later wins on name
041 * collision, except that {@code ServiceLoader} entries never replace an existing function):
042 * <ol>
043 *    <li>The built-in catalog auto-registered by {@link VarResolver#DEFAULT}.
044 *    <li>{@code META-INF/services/org.apache.juneau.commons.svl.VarFunction} (Java {@link ServiceLoader}),
045 *       only when the resolver is built with {@code VarResolver.Builder.loadServices()}.
046 *    <li>{@code BeanStore.getBeans(VarFunction.class)} on the resolver's bean store.
047 *    <li>Explicit registrations via {@code VarResolver.Builder.functions(...)}.
048 * </ol>
049 *
050 * <p>
051 * For typed reflection-based dispatch (the recommended path), extend
052 * {@link TypedFunction} — it derives {@link #minArity()}, {@link #maxArity()}, and per-arg
053 * coercion automatically from the subclass's {@code invoke(...)} method signature, eliminating
054 * the per-function plumbing.
055 *
056 * <h2 class='section'>Example:</h2>
057 * <p class='bjava'>
058 *    <jc>// Direct VarFunction impl (less common — TypedFunction is preferred).</jc>
059 *    <jk>public class</jk> Reverse <jk>implements</jk> VarFunction {
060 *       <ja>@Override</ja> <jk>public</jk> String name() { <jk>return</jk> <js>"reverse"</js>; }
061 *       <ja>@Override</ja> <jk>public int</jk> minArity() { <jk>return</jk> 1; }
062 *       <ja>@Override</ja> <jk>public int</jk> maxArity() { <jk>return</jk> 1; }
063 *       <ja>@Override</ja> <jk>public</jk> String invoke(VarResolverSession <jv>session</jv>, List&lt;Object&gt; <jv>args</jv>) {
064 *          <jk>return new</jk> StringBuilder((String) <jv>args</jv>.get(0)).reverse().toString();
065 *       }
066 *    }
067 * </p>
068 *
069 * <h2 class='section'>See Also:</h2><ul>
070 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/MarshallSimpleVariableLanguage">Marshall Simple Variable Language</a>
071 *    <li class='jc'>{@link TypedFunction}
072 * </ul>
073 */
074public interface VarFunction {
075
076   /**
077    * The function's invocation name as it appears between {@code #{}} and the opening
078    * parenthesis in the template. Must consist of ASCII letters, digits, and underscores; must
079    * begin with a letter.
080    *
081    * @return The invocation name. Never {@code null} or empty.
082    */
083   String name();
084
085   /**
086    * Minimum argument count this function accepts.
087    *
088    * @return The minimum number of args. {@code 0} means the function may be called with no
089    *  args. Returns {@code -1} for "any number of args" — equivalent to declaring
090    *  {@code minArity == 0 && maxArity == Integer.MAX_VALUE}.
091    */
092   int minArity();
093
094   /**
095    * Maximum argument count this function accepts.
096    *
097    * @return The maximum number of args, or {@link Integer#MAX_VALUE} for unbounded variadic
098    *  functions.
099    */
100   int maxArity();
101
102   /**
103    * Invokes this function with already-resolved, type-coerced arguments.
104    *
105    * <p>
106    * The runtime resolves each {@code #{...}} arg template against the session, then coerces
107    * the resolved string to the target Java type via {@code ArgCoercer}. The resulting
108    * {@code List<Object>} is passed in here.
109    *
110    * @param session The current resolver session. Must not be {@code null}.
111    * @param args The coerced arguments. Size is in {@code [minArity(), maxArity()]}. Each
112    *  element is the type the function expects per its signature; for variadic /
113    *  {@code Object}-typed slots, elements remain {@link String}.
114    * @return The function's result as a {@link String}. May be empty but should not be
115    *  {@code null} (the runtime treats {@code null} as the empty string for SVL output).
116    */
117   String invoke(VarResolverSession session, List<Object> args);
118
119   /**
120    * Typed variant of {@link #invoke(VarResolverSession, List)} used by <c>#{...}</c> expressions.
121    *
122    * <p>
123    * The default delegates to {@link #invoke(VarResolverSession, List)}.
124    *
125    * @param session The session.
126    * @param args The already-evaluated arguments (typed values, not necessarily strings).
127    * @return The result; <jk>null</jk> means absent.
128    * @throws Exception Function-specific failure.
129    */
130   @SuppressWarnings({
131      "java:S112" // Functions may fail with any checked exception; this is the public contract
132   })
133   default Object invokeValue(VarResolverSession session, List<Object> args) throws Exception {
134      return invoke(session, args);
135   }
136}