001package de.monochromata.anaphors.perspectivation;
002
003import static de.monochromata.anaphors.ast.AnaphorPartsStreaming.toVariableContentsAndAnaphors;
004
005import java.util.List;
006import java.util.function.Predicate;
007
008import org.apache.commons.lang3.tuple.Pair;
009
010import de.monochromata.anaphors.ast.ASTBasedAnaphora;
011import de.monochromata.anaphors.ast.AnaphorPart;
012import de.monochromata.anaphors.ast.RelatedExpressionPart;
013import de.monochromata.anaphors.ast.relatedexp.RelatedExpression;
014import de.monochromata.anaphors.ast.relatedexp.strategy.LocalTempVariableContents;
015import de.monochromata.anaphors.ast.spi.AnaphorsSpi;
016import de.monochromata.anaphors.ast.spi.RelatedExpressionsSpi;
017
018/**
019 * Underspecification is considered a process that is a kind of perspectivation.
020 * It drops information while a conceptual-semantic representation is
021 * transformed into a textual representation. It is intended to be used when
022 * creating reader-specific textual representations that omit information that
023 * is well-known to the reader.
024 *
025 * @see Perspectivation
026 */
027public interface Underspecification {
028
029        /**
030         * @param condition Can be used to specify when to apply the perspectivations
031         *                  contained in the positions returned by this method. The
032         *                  condition will be contained in the positions. The condition
033         *                  is based on an event typically associated with a
034         *                  modification of a document to which perspectivations are
035         *                  applied. Because perspectivations modify a document, they
036         *                  can only be applied when the document is in a state (a
037         *                  precondition) that the perspectivations are based on.
038         * @param <N>       The node type in the AST
039         * @param <E>       The expression type
040         * @param <T>       The type type
041         * @param <B>       The binding type
042         * @param <MB>      The method binding type
043         * @param <TB>      The type binding type
044         * @param <S>       The scope type (optional)
045         * @param <I>       The type used to represent identifiers
046         * @param <QI>      The type used to represent qualified identifiers
047         * @param <EV>      The type of the event contained in the condition that is
048         *                  evaluated to check when the perspectivations shall be
049         *                  applied.
050         * @param <PP>      The type used for positions that carry perspectivations
051         * @param <R>       The sub-type of related expression to use
052         * @param <A>       The sub-type of AST-based anaphora to use
053         */
054        static <N, E, T, B, MB extends B, TB extends B, S, I, QI, EV, PP, R extends RelatedExpression<N, T, B, TB, S, QI, R>, A extends ASTBasedAnaphora<N, E, T, B, TB, S, I, QI, R, A>> PP underspecifyRelatedExpression(
055                        final RelatedExpressionPart<N, E, T, B, TB, S, I, QI, R> relatedExpressionPart,
056                        final List<AnaphorPart<N, E, T, B, TB, S, I, QI, R, A>> anaphorParts, final S scope,
057                        final Predicate<EV> condition,
058                        final RelatedExpressionsSpi<N, E, T, B, MB, TB, S, I, QI, EV, PP, R> relatedExpressionsSpi) {
059                final R relatedExpression = relatedExpressionPart.getRelatedExpression();
060                final var relatedExpressionStrategy = relatedExpressionPart.getRelatedExpressionStrategy();
061                final List<Pair<LocalTempVariableContents, String>> variableContentsAndAnaphors = toVariableContentsAndAnaphors(
062                                anaphorParts);
063                final var perspectivations = relatedExpressionStrategy.underspecifyRelatedExpression(relatedExpression,
064                                variableContentsAndAnaphors, scope);
065                return relatedExpressionsSpi.createPositionForNode(relatedExpression.getRelatedExpression(), condition,
066                                perspectivations);
067        }
068
069        /**
070         * @param condition Can be used to specify when to apply the perspectivations
071         *                  contained in the positions returned by this method. The
072         *                  condition will be contained in the positions. The condition
073         *                  is based on an event typically associated with a
074         *                  modification of a document to which perspectivations are
075         *                  applied. Because perspectivations modify a document, they
076         *                  can only be applied when the document is in a state (a
077         *                  precondition) that the perspectivations are based on.
078         * @param <N>       The node type in the AST
079         * @param <E>       The expression type
080         * @param <T>       The type type
081         * @param <B>       The binding type
082         * @param <TB>      The type binding type
083         * @param <S>       The scope type (optional)
084         * @param <I>       The type used to represent identifiers
085         * @param <QI>      The type used to represent qualified identifiers
086         * @param <EV>      The type of the event contained in the condition that is
087         *                  evaluated to check when the perspectivations shall be
088         *                  applied.
089         * @param <PP>      The type used for positions that carry perspectivations
090         * @param <R>       The sub-type of related expression to use
091         * @param <A>       The sub-type of AST-based anaphora to use
092         */
093        static <N, E, T, B, TB extends B, S, I, QI, EV, PP, R extends RelatedExpression<N, T, B, TB, S, QI, R>, A extends ASTBasedAnaphora<N, E, T, B, TB, S, I, QI, R, A>> PP underspecifyAnaphor(
094                        final RelatedExpressionPart<N, E, T, B, TB, S, I, QI, R> relatedExpressionPart,
095                        final AnaphorPart<N, E, T, B, TB, S, I, QI, R, A> anaphorPart, final S scope, final Predicate<EV> condition,
096                        final AnaphorsSpi<N, E, TB, S, I, QI, EV, PP> anaphorsSpi) {
097                final R relatedExpression = relatedExpressionPart.getRelatedExpression();
098                final String anaphor = anaphorPart.getAnaphor();
099                final E anaphorExpression = anaphorPart.getAnaphorExpression();
100                final var anaphorResolutionStrategy = anaphorPart.getAnaphorResolutionStrategy();
101                final var perspectivations = anaphorResolutionStrategy.underspecifyAnaphor(relatedExpression, anaphor,
102                                anaphorExpression, anaphorPart.getReferent(), scope);
103                return anaphorsSpi.createPositionForExpression(anaphorExpression, condition, perspectivations);
104        }
105
106}