1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package dev.metaschema.core.model.constraint;
7   
8   import dev.metaschema.core.datatype.markup.MarkupMultiline;
9   import dev.metaschema.core.metapath.IMetapathExpression;
10  import dev.metaschema.core.model.ISource;
11  import dev.metaschema.core.model.constraint.impl.DefaultLet;
12  import dev.metaschema.core.qname.IEnhancedQName;
13  import dev.metaschema.core.util.ObjectUtils;
14  import edu.umd.cs.findbugs.annotations.NonNull;
15  import edu.umd.cs.findbugs.annotations.Nullable;
16  
17  /**
18   * Represents a variable assignment for use in Metaschema module constraints.
19   */
20  public interface ILet {
21    /**
22     * Create a new Let expression by compiling the provided Metapath expression
23     * string.
24     * <p>
25     * This method is deprecated. Callers should use
26     * {@link #of(IEnhancedQName, IMetapathExpression, ISource, MarkupMultiline)}
27     * instead.
28     *
29     * @param name
30     *          the let expression variable name
31     * @param valueExpression
32     *          a Metapath expression string representing the variable value
33     * @param source
34     *          the source descriptor for the resource containing the constraint
35     * @param remarks
36     *          remarks about the let statement
37     * @return the original let statement with the same name or {@code null}
38     */
39    @NonNull
40    @Deprecated(since = "2.2.0", forRemoval = true)
41    static ILet of(
42        @NonNull IEnhancedQName name,
43        @NonNull String valueExpression,
44        @NonNull ISource source,
45        @Nullable MarkupMultiline remarks) {
46      return of(
47          name,
48          IMetapathExpression.lazyCompile(valueExpression, source.getStaticContext()),
49          source,
50          remarks);
51    }
52  
53    /**
54     * Create a new Let expression.
55     *
56     * @param name
57     *          the let expression variable name
58     * @param valueExpression
59     *          a Metapath expression representing the variable value
60     * @param source
61     *          the source descriptor for the resource containing the constraint
62     * @param remarks
63     *          remarks about the let statement
64     * @return the original let statement with the same name or {@code null}
65     */
66    @NonNull
67    static ILet of(
68        @NonNull IEnhancedQName name,
69        @NonNull IMetapathExpression valueExpression,
70        @NonNull ISource source,
71        @Nullable MarkupMultiline remarks) {
72      return new DefaultLet(name, valueExpression, source, remarks);
73    }
74  
75    /**
76     * Get a stable identifier for this let statement, suitable for use in SARIF
77     * output and timing correlation.
78     * <p>
79     * Generates a deterministic identifier based on the variable name, source
80     * location, and value expression.
81     *
82     * @return a non-null identifier string
83     */
84    @NonNull
85    default String getInternalIdentifier() {
86      String localName = getName().getLocalName();
87      String source = getSource().getLocationHint();
88      String expression = getValueExpression().getPath();
89      int hash = (source + "|" + expression).hashCode();
90      return ObjectUtils.notNull("let-" + localName + "-" + String.format("%08x", hash));
91    }
92  
93    /**
94     * Get the name of the let variable.
95     *
96     * @return the name
97     */
98    @NonNull
99    IEnhancedQName getName();
100 
101   /**
102    * Get the Metapath expression to use to query the value.
103    *
104    * @return the Metapath expression to use to query the value
105    */
106   @NonNull
107   IMetapathExpression getValueExpression();
108 
109   /**
110    * Information about the source resource containing the let statement.
111    *
112    * @return the source information
113    */
114   @NonNull
115   ISource getSource();
116 
117   /**
118    * Get the remarks associated with the let statement.
119    *
120    * @return the remark or {@code null} if no remarks are defined
121    */
122   @Nullable
123   MarkupMultiline getRemarks();
124 }