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
019/**
020 * One reference found in a compiled {@link VarTemplate}: a <c>${...}</c> var, a function or operator call, an
021 * identifier, or a syntax problem.
022 *
023 * <p>
024 * Offsets are into {@link VarTemplate#getSource()}: <c>start</c> inclusive, <c>end</c> exclusive.  For a var the span is
025 * the whole <c>${...}</c> marker; a <c>${name}</c> or <c>${name:default}</c> var reference also yields an {@link Kind#IDENT}
026 * entry for its key (the text before the first top-level <c>:</c>); for a function and an identifier it is the name token; for a syntax problem it is the
027 * offending marker.
028 *
029 * <p>
030 * References are reported for markers that are evaluated at render time.  A stable var folded at compile time (and an
031 * expression folded with it) has no entry.  A <c>${...}</c> inside a nested var body is not analyzed.
032 *
033 * @param kind What was referenced.
034 * @param name The var prefix (<c>P</c> for the <c>${name}</c> shortcut), the function name (operators are
035 *    <c>$op.*</c>), the identifier, or for {@link Kind#SYNTAX} the error message.
036 * @param bound Whether the name resolves in the resolver the template was compiled against: a registered var, or a
037 *    registered function permitted by the allowlist.  Always <jk>true</jk> for identifiers.
038 * @param listName For an identifier read as a row field (inside the body of a select or projection whose target is a
039 *    top-level identifier), that identifier's name; <jk>null</jk> for a top-level identifier.  Identifiers in a body
040 *    whose target is anything else are not reported.
041 * @param start Start offset, inclusive.
042 * @param end End offset, exclusive.
043 */
044public record TemplateReference(Kind kind, String name, boolean bound, String listName, int start, int end) {
045
046   /** The kind of reference. */
047   public enum Kind {
048      /** A <c>${...}</c> var reference. */ VAR,
049      /** A function or operator call inside an expression. */ FUNCTION,
050      /** A bare identifier inside an expression. */ IDENT,
051      /** A marker that could not be compiled (lenient mode keeps it as text). */ SYNTAX
052   }
053}