Modules

.gitignore

@@ -7,6 +7,10 @@
 
 # Temporary/Generated Files
 /out/
+*/build
+
+# Log files
+junit.log
 
 # Created by https://www.gitignore.io/api/java,gradle,eclipse
 
@@ -97,8 +101,9 @@ gradle-app.setting
 
 ### Custom additions ###
 /.checkstyle
-/junit.log
+*/junit.log
 .idea/modules/*.iml
 *.tokens
 /.dbeaver
 /Scripts
+/.vscode/

RELEASE.md

@@ -47,15 +47,15 @@ as JAR files and two scripts to run Alpha on Unix-like and Windows respectively.
 To generate `alpha.jar`:
 
 ```bash
-$ ./gradlew bundledJar
-$ cp build/libs/alpha-bundled.jar alpha.jar
+$ ./gradlew alpha-cli-app:bundledJar
+$ cp alpha-cli-app/build/libs/alpha-cli*-bundled.jar alpha.jar
 ```
 
 To generate `alpha.zip`:
 
 ```bash
-$ ./gradlew distZip
-$ cp build/distributions/alpha.zip alpha.zip
+$ ./gradlew alpha-cli-app:distZip
+$ cp alpha-cli-app/build/distributions/*.zip alpha.zip
 ```
 
 Attach the two files to the release on GitHub, then publish the release. Lastly, check that everything is fine,

alpha-api/.gitignore

@@ -0,0 +1 @@
+/build/

alpha-api/build.gradle.kts

@@ -0,0 +1,3 @@
+plugins {
+	id("alpha.java-library-conventions")
+}

alpha-api/src/main/java/at/ac/tuwien/kr/alpha/api/Alpha.java

@@ -0,0 +1,149 @@
+package at.ac.tuwien.kr.alpha.api;
+
+import java.io.IOException;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Stream;
+
+import at.ac.tuwien.kr.alpha.api.common.fixedinterpretations.PredicateInterpretation;
+import at.ac.tuwien.kr.alpha.api.config.InputConfig;
+import at.ac.tuwien.kr.alpha.api.programs.ASPCore2Program;
+import at.ac.tuwien.kr.alpha.api.programs.NormalProgram;
+import at.ac.tuwien.kr.alpha.api.programs.Predicate;
+
+/**
+ * Main API entry point for the Alpha ASP system. Provides facilities for parsing, normalizing and solving ASP programs.
+ * 
+ * Copyright (c) 2021, the Alpha Team.
+ */
+public interface Alpha {
+
+	/**
+	 * Reads an ASP program using the configuration and sources specified in a given {@link InputConfig}.
+	 * 
+	 * @param cfg and {@link InputConfig} specifying program sources (strings, files) as well as config metadata (e.g. literate program,
+	 *            external atoms, etc)
+	 * @return an {@link ASPCore2Program} representing the parsed ASP code from all sources referenced in the given {@link InputConfig}
+	 * @throws IOException in case one or more program sources (e.g. files) cannot be read, or parsing fails
+	 */
+	ASPCore2Program readProgram(InputConfig cfg) throws IOException;
+
+	/**
+	 * Reads and parses an {@link ASPCore2Program} from a list of {@link String}s representing paths.
+	 * 
+	 * @param literate  flag indicating whether ASP code should be treated as "literate".
+	 * @param externals Custom {@link PredicateInterpretation}s for user-defined external atoms
+	 * @param paths     a list of {@link String}s representing paths containing all sources from which ASP code should be read
+	 * @return an {@link ASPCore2Program} representing the parsed ASP code from all given path strings
+	 * @throws IOException in case one or more program sources cannot be read, or parsing fails
+	 */
+	ASPCore2Program readProgramFiles(boolean literate, Map<String, PredicateInterpretation> externals, List<String> paths) throws IOException;
+
+	/**
+	 * see {@link Alpha#readProgramFiles(boolean, Map, List)}
+	 */
+	ASPCore2Program readProgramFiles(boolean literate, Map<String, PredicateInterpretation> externals, Path... paths) throws IOException;
+
+	/**
+	 * Parses a given String into an {@link ASPCore2Program}, using a map of custom {@link PredicateInterpretation}s to resolve external atoms
+	 * in ASP code.
+	 * 
+	 * @param aspString a string representing a valid ASP-Core2 program
+	 * @param externals a map of custom {@link PredicateInterpretation}s against which external atoms in the given code are resolved
+	 * @return an {@link ASPCore2Program} representing the parsed ASP code
+	 */
+	ASPCore2Program readProgramString(String aspString, Map<String, PredicateInterpretation> externals);
+
+	/**
+	 * Convenience method to parse ASP strings not containing any user-defined external atoms, see {@link Alpha#readProgramString(String, Map)}.
+	 */
+	ASPCore2Program readProgramString(String aspString);
+
+	/**
+	 * Prepares a {@link DebugSolvingContext} for the given {@link ASPCore2Program} to debug program preprocessing.
+	 * 
+	 * @return a {@link DebugSolvingContext} holding debug information for the given program
+	 */
+	DebugSolvingContext prepareDebugSolve(final ASPCore2Program program);
+
+	/**
+	 * Prepares a {@link DebugSolvingContext} for the given {@link NormalProgram} to debug program preprocessing.
+	 * 
+	 * @return a {@link DebugSolvingContext} holding debug information for the given program
+	 */
+	DebugSolvingContext prepareDebugSolve(final NormalProgram program);
+
+	/**
+	 * Prepares a {@link DebugSolvingContext} for the given {@link ASPCore2Program} to debug program preprocessing.
+	 * 
+	 * @param filter a {@link java.util.function.Predicate} against which {@link Predicate}s of answer sets are tested.
+	 * @return a {@link DebugSolvingContext} holding debug information for the given program
+	 */
+	DebugSolvingContext prepareDebugSolve(final ASPCore2Program program, java.util.function.Predicate<Predicate> filter);
+
+	/**
+	 * Prepares a {@link DebugSolvingContext} for the given {@link NormalProgram} to debug program preprocessing.
+	 * 
+	 * @param filter a {@link java.util.function.Predicate} against which {@link Predicate}s of answer sets are tested.
+	 * @return a {@link DebugSolvingContext} holding debug information for the given program
+	 */
+	DebugSolvingContext prepareDebugSolve(final NormalProgram program, java.util.function.Predicate<Predicate> filter);
+
+	/**
+	 * Solves the given {@link ASPCore2Program}.
+	 * @param program an input program
+	 * @return a {@link Stream} of {@link AnswerSet}s of the given program
+	 */
+	Stream<AnswerSet> solve(ASPCore2Program program);
+
+	/**
+	 * Solves the given {@link ASPCore2Program}.
+	 * @param program an input program
+	 * @param filter a {@link java.util.function.Predicate} against which {@link Predicate}s of answer sets are tested.
+	 * @return a {@link Stream} of {@link AnswerSet}s of the given program
+	 */
+	Stream<AnswerSet> solve(ASPCore2Program program, java.util.function.Predicate<Predicate> filter);
+
+	/**
+	 * Solves the given {@link NormalProgram}.
+	 * @param program an input program
+	 * @return a {@link Stream} of {@link AnswerSet}s of the given program
+	 */
+	Stream<AnswerSet> solve(NormalProgram program);
+
+	/**
+	 * Solves the given {@link NormalProgram}.
+	 * @param program an input program
+	 * @param filter a {@link java.util.function.Predicate} against which {@link Predicate}s of answer sets are tested.
+	 * @return a {@link Stream} of {@link AnswerSet}s of the given program
+	 */
+	Stream<AnswerSet> solve(NormalProgram program, java.util.function.Predicate<Predicate> filter);
+
+	/**
+	 * Normalizes a program, i.e. rewrites all syntax constructs not natively supported by Alphas back-end into semantically equivalent ASP code.
+	 * See {@link NormalProgram},
+	 * @param program An {@link ASPCore2Program} to normalize
+	 * @return a {@link NormalProgram} that is a semantic equivalent to the given input program
+	 */
+	NormalProgram normalizeProgram(ASPCore2Program program);
+
+	/**
+	 * Constructs a @{link Solver} pre-loaded with the given {@link ASPCore2Program} from which {@link AnswerSet}s can be obtained via {@link Solver#stream()}.
+	 * 
+	 * @param program the program to solve
+	 * @param filter a {@link java.util.function.Predicate} against which {@link Predicate}s of answer sets are tested.
+	 * @return a {@link Solver} pre-loaded withthe given program
+	 */
+	Solver prepareSolverFor(ASPCore2Program program, java.util.function.Predicate<Predicate> filter);
+
+	/**
+	 * Constructs a @{link Solver} pre-loaded with the given {@link NormalProgram} from which {@link AnswerSet}s can be obtained via {@link Solver#stream()}.
+	 * 
+	 * @param program the program to solve
+	 * @param filter a {@link java.util.function.Predicate} against which {@link Predicate}s of answer sets are tested.
+	 * @return a {@link Solver} pre-loaded withthe given program
+	 */
+	Solver prepareSolverFor(NormalProgram program, java.util.function.Predicate<Predicate> filter);
+
+}

alpha-api/src/main/java/at/ac/tuwien/kr/alpha/api/AnswerSet.java

@@ -0,0 +1,35 @@
+package at.ac.tuwien.kr.alpha.api;
+
+import java.util.List;
+import java.util.SortedSet;
+
+import at.ac.tuwien.kr.alpha.api.programs.Predicate;
+import at.ac.tuwien.kr.alpha.api.programs.atoms.Atom;
+
+/**
+ * API representation of an answer set, i.e. a set of atoms that is a model of an ASP program.
+ * 
+ * Copyright (c) 2021, the Alpha Team.
+ */
+public interface AnswerSet extends Comparable<AnswerSet> {
+
+	/**
+	 * The set of all predicates contained in the answer set.
+	 */
+	SortedSet<Predicate> getPredicates();
+
+	/**
+	 * All instances of the given predicate within the answer set.
+	 */
+	SortedSet<Atom> getPredicateInstances(Predicate predicate);
+
+	/**
+	 * Boolean flag indicating whether this {@link AnswerSet} represents the empty set.
+	 */
+	boolean isEmpty();
+
+	/**
+	 * List {@link Atom}s in this answer set satisfying the given {@link AnswerSetQuery}.
+	 */
+	List<Atom> query(AnswerSetQuery query);
+}

alpha-api/src/main/java/at/ac/tuwien/kr/alpha/api/AnswerSetQuery.java

@@ -0,0 +1,82 @@
+package at.ac.tuwien.kr.alpha.api;
+
+import java.util.List;
+
+import at.ac.tuwien.kr.alpha.api.programs.atoms.Atom;
+import at.ac.tuwien.kr.alpha.api.terms.Term;
+
+/**
+ * A {@link java.util.function.Predicate} testing {@link Atom}s in order to query {@link AnswerSet}s for {@link Atom}s satisfying a specific
+ * query.
+ * 
+ * Copyright (c) 2021, the Alpha Team.
+ */
+public interface AnswerSetQuery extends java.util.function.Predicate<Atom> {
+
+	/**
+	 * Adds a filter predicate to apply on terms at the given index position.
+	 * 
+	 * @param termIdx the term index on which to apply the new filter
+	 * @param filter  a filter predicate
+	 * @return this answer set query withthe given filter added
+	 */
+	AnswerSetQuery withFilter(int termIdx, java.util.function.Predicate<Term> filter);
+
+	/**
+	 * Convenience method - adds a filter to match names of symbolic constants against a string.
+	 * 
+	 * @param termIdx
+	 * @param str
+	 * @return
+	 */
+	AnswerSetQuery withConstantEquals(int termIdx, String str);
+
+	/**
+	 * Convenience method - adds a filter to match values of constant terms against a string.
+	 * 
+	 * @param termIdx
+	 * @param str
+	 * @return
+	 */
+	AnswerSetQuery withStringEquals(int termIdx, String str);
+
+	/**
+	 * Convenience method - adds a filter to check for function terms with a given function symbol and arity.
+	 * 
+	 * @param termIdx
+	 * @param funcSymbol
+	 * @param funcArity
+	 * @return
+	 */
+	AnswerSetQuery withFunctionTerm(int termIdx, String funcSymbol, int funcArity);
+
+	/**
+	 * Convenience method - adds a filter to check whether a term is equal to a given term.
+	 * 
+	 * @param termIdx
+	 * @param otherTerm
+	 * @return
+	 */
+	AnswerSetQuery withTermEquals(int termIdx, Term otherTerm);
+
+	/**
+	 * Applies this query to an atom. Filters are worked off in
+	 * order of ascending term index in a conjunctive fashion, i.e. for an atom
+	 * to match the query, all of its terms must satisfy all filters on these
+	 * terms
+	 * 
+	 * @param atom the atom to which to apply the query
+	 * @return true iff the atom satisfies the query
+	 */
+	@Override
+	boolean test(Atom atom);
+
+	/**
+	 * Applies this query to an {@link AnswerSet}.
+	 * 
+	 * @param as
+	 * @return
+	 */
+	List<Atom> applyTo(AnswerSet as);
+
+}

alpha-api/src/main/java/at/ac/tuwien/kr/alpha/api/ComparisonOperator.java

@@ -0,0 +1,34 @@
+package at.ac.tuwien.kr.alpha.api;
+
+import at.ac.tuwien.kr.alpha.api.programs.ASPCore2Program;
+import at.ac.tuwien.kr.alpha.api.programs.Predicate;
+import at.ac.tuwien.kr.alpha.api.terms.Term;
+
+/**
+ * A comparison operator that can be used in {@link ASPCore2Program}s.
+ * 
+ * Copyright (c) 2021, the Alpha Team.
+ */
+public interface ComparisonOperator {
+
+	/**
+	 * The operator symbol, i.e. the operator's string representation.
+	 */
+	String getSymbol();
+
+	/**
+	 * The {@link Predicate} associated with this operator.
+	 */
+	Predicate toPredicate();
+
+	/**
+	 * The inverse of this operator (e.g. the inverse of "=" is "!=")
+	 */
+	ComparisonOperator negate();
+
+	/**
+	 * Tests whether two terms are in the relation defined by this operator.
+	 */
+	boolean compare(Term t1, Term t2);
+
+}

alpha-api/src/main/java/at/ac/tuwien/kr/alpha/api/DebugSolvingContext.java

@@ -0,0 +1,43 @@
+package at.ac.tuwien.kr.alpha.api;
+
+import at.ac.tuwien.kr.alpha.api.programs.ASPCore2Program;
+import at.ac.tuwien.kr.alpha.api.programs.NormalProgram;
+import at.ac.tuwien.kr.alpha.api.programs.analysis.ComponentGraph;
+import at.ac.tuwien.kr.alpha.api.programs.analysis.DependencyGraph;
+
+/**
+ * Wrapper object for debug information on program preprocessing produced by {@link Alpha}.
+ * 
+ * Copyright (c) 2021, the Alpha Team.
+ */
+public interface DebugSolvingContext {
+
+	/**
+	 * The normalized version of the {@link ASPCore2Program} that is being solved.
+	 * See {@link Alpha#normalizeProgram(ASPCore2Program)}.
+	 */
+	NormalProgram getNormalizedProgram();
+
+	/**
+	 * The fully preprocessed version of the {@link ASPCore2Program} that is being solved.
+	 * This differs from the value of {@link DebugSolvingContext#getNormalizedProgram()} in the stratified part of the normalized program may
+	 * already be evaluated depending on the respective configuration of {@link Alpha}.
+	 */
+	NormalProgram getPreprocessedProgram();
+
+	/**
+	 * The {@link DependencyGraph} of the program being solved.
+	 */
+	DependencyGraph getDependencyGraph();
+
+	/**
+	 * The {@link ComponentGraph} of the program being solved.
+	 */
+	ComponentGraph getComponentGraph();
+
+	/**
+	 * A {@link Solver} instance pre-loaded with the program being solved, from which {@link AnswerSet}s can be streamed.
+	 */
+	Solver getSolver();
+
+}