001package de.monochromata.anaphors.cog.transform;
002
003import de.monochromata.Strategy;
004import de.monochromata.anaphors.ast.ASTBasedAnaphora;
005import de.monochromata.anaphors.ast.relatedexp.RelatedExpression;
006import de.monochromata.anaphors.cog.memory.Chunk;
007
008/**
009 * A transformation used to prepare the introduction of an
010 * {@link ASTBasedAnaphora} relation.
011 *
012 * @param <N>  The node type in the AST
013 * @param <E>  The expression type
014 * @param <T>  The type type
015 * @param <B>  The binding type
016 * @param <TB> The type binding type
017 * @param <S>  The scope type (optional)
018 * @param <I>  The type used to represent identifiers
019 * @param <QI> The type used to represent qualified identifiers
020 * @param <R>  The sub-type of related expression to use
021 * @param <A>  The sub-type of AST-based anaphora to use
022 */
023public interface PreparatoryTransformation<N, E, T, B, TB extends B, S, I, QI, R extends RelatedExpression<N, T, B, TB, S, QI, R>, A extends ASTBasedAnaphora<N, E, T, B, TB, S, I, QI, R, A>>
024                extends Strategy {
025
026        /**
027         * Check whether the transformation can be performed.
028         * <p>
029         * Note that the applicability of preparatory transformations must be mutually
030         * exclusive: only one out of all preparatory transformations can be applicable
031         * to a combination of chunk, definite expression and scope.
032         *
033         * @param chunk              The chunk that contains the node that may function
034         *                           as related expression.
035         * @param definiteExpression The definite expression that can potentially
036         *                           function as anaphor.
037         * @param scope              The scope containing the definite expression. May
038         *                           be null if not required by the AST implementation
039         *                           configured via the service provider interfaces.
040         * @return the result of a check that might contain (hidden)
041         *         implementation-specific cached information to speed up
042         *         {@link #perform(CheckResult, ASTBasedAnaphora)}.
043         */
044        public CheckResult<N, E, S> canPerform(final Chunk<N> chunk, final E definiteExpression, final S scope);
045
046        /**
047         * Perform the preparatory transformation and return a potential Anaphora
048         * relation thereafter.
049         *
050         * @param checkResult         the result of an invocation of check that might
051         *                            contain (hidden) implementation-specific cached
052         *                            information to speed up
053         *                            {@link #perform(CheckResult, ASTBasedAnaphora)}
054         * @param preliminaryAnaphora a preliminary anaphora relation that will be used
055         *                            as a blue-print to create the potential anaphora.
056         *                            (The preliminary anaphora is based on the AST
057         *                            before the preparatory transformation - its
058         *                            related expression might be unreachable from its
059         *                            the definite expression.)
060         * @return a potential anaphora relation that in valid in the AST after the
061         *         preparatory transformation has been applied.
062         * @throws IllegalArgumentException If the given check result has not been
063         *                                  created by this strategy or if the given
064         *                                  check result's
065         *                                  {@link CheckResult#canPerformTransformation()}
066         *                                  returns false.
067         */
068        public A perform(final CheckResult<N, E, S> checkResult, final A preliminaryAnaphora);
069
070}