Skip to content

Commit 21d074a

Browse files
lorenzleutgebmadmike200590AntoniusW
authored
Modules (#274)
Resolves #108. See #300 for further suggestions to improve code quality. Summary: - New Gradle modules. - Hide implementations, provide API. - Move CLI to separate module, consuming API. Co-authored-by: Michael Langowski <[email protected]> Co-authored-by: Antonius Weinzierl <[email protected]>
1 parent aa75756 commit 21d074a

File tree

430 files changed

+9491
-6675
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

430 files changed

+9491
-6675
lines changed

‎.gitignore

+6-1
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@
77

88
# Temporary/Generated Files
99
/out/
10+
*/build
11+
12+
# Log files
13+
junit.log
1014

1115
# Created by https://www.gitignore.io/api/java,gradle,eclipse
1216

@@ -97,8 +101,9 @@ gradle-app.setting
97101

98102
### Custom additions ###
99103
/.checkstyle
100-
/junit.log
104+
*/junit.log
101105
.idea/modules/*.iml
102106
*.tokens
103107
/.dbeaver
104108
/Scripts
109+
/.vscode/

‎RELEASE.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -47,15 +47,15 @@ as JAR files and two scripts to run Alpha on Unix-like and Windows respectively.
4747
To generate `alpha.jar`:
4848

4949
```bash
50-
$ ./gradlew bundledJar
51-
$ cp build/libs/alpha-bundled.jar alpha.jar
50+
$ ./gradlew alpha-cli-app:bundledJar
51+
$ cp alpha-cli-app/build/libs/alpha-cli*-bundled.jar alpha.jar
5252
```
5353

5454
To generate `alpha.zip`:
5555

5656
```bash
57-
$ ./gradlew distZip
58-
$ cp build/distributions/alpha.zip alpha.zip
57+
$ ./gradlew alpha-cli-app:distZip
58+
$ cp alpha-cli-app/build/distributions/*.zip alpha.zip
5959
```
6060

6161
Attach the two files to the release on GitHub, then publish the release. Lastly, check that everything is fine,

‎alpha-api/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/build/

‎alpha-api/build.gradle.kts

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
plugins {
2+
id("alpha.java-library-conventions")
3+
}

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

+149
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
package at.ac.tuwien.kr.alpha.api;
2+
3+
import java.io.IOException;
4+
import java.nio.file.Path;
5+
import java.util.List;
6+
import java.util.Map;
7+
import java.util.stream.Stream;
8+
9+
import at.ac.tuwien.kr.alpha.api.common.fixedinterpretations.PredicateInterpretation;
10+
import at.ac.tuwien.kr.alpha.api.config.InputConfig;
11+
import at.ac.tuwien.kr.alpha.api.programs.ASPCore2Program;
12+
import at.ac.tuwien.kr.alpha.api.programs.NormalProgram;
13+
import at.ac.tuwien.kr.alpha.api.programs.Predicate;
14+
15+
/**
16+
* Main API entry point for the Alpha ASP system. Provides facilities for parsing, normalizing and solving ASP programs.
17+
*
18+
* Copyright (c) 2021, the Alpha Team.
19+
*/
20+
public interface Alpha {
21+
22+
/**
23+
* Reads an ASP program using the configuration and sources specified in a given {@link InputConfig}.
24+
*
25+
* @param cfg and {@link InputConfig} specifying program sources (strings, files) as well as config metadata (e.g. literate program,
26+
* external atoms, etc)
27+
* @return an {@link ASPCore2Program} representing the parsed ASP code from all sources referenced in the given {@link InputConfig}
28+
* @throws IOException in case one or more program sources (e.g. files) cannot be read, or parsing fails
29+
*/
30+
ASPCore2Program readProgram(InputConfig cfg) throws IOException;
31+
32+
/**
33+
* Reads and parses an {@link ASPCore2Program} from a list of {@link String}s representing paths.
34+
*
35+
* @param literate flag indicating whether ASP code should be treated as "literate".
36+
* @param externals Custom {@link PredicateInterpretation}s for user-defined external atoms
37+
* @param paths a list of {@link String}s representing paths containing all sources from which ASP code should be read
38+
* @return an {@link ASPCore2Program} representing the parsed ASP code from all given path strings
39+
* @throws IOException in case one or more program sources cannot be read, or parsing fails
40+
*/
41+
ASPCore2Program readProgramFiles(boolean literate, Map<String, PredicateInterpretation> externals, List<String> paths) throws IOException;
42+
43+
/**
44+
* see {@link Alpha#readProgramFiles(boolean, Map, List)}
45+
*/
46+
ASPCore2Program readProgramFiles(boolean literate, Map<String, PredicateInterpretation> externals, Path... paths) throws IOException;
47+
48+
/**
49+
* Parses a given String into an {@link ASPCore2Program}, using a map of custom {@link PredicateInterpretation}s to resolve external atoms
50+
* in ASP code.
51+
*
52+
* @param aspString a string representing a valid ASP-Core2 program
53+
* @param externals a map of custom {@link PredicateInterpretation}s against which external atoms in the given code are resolved
54+
* @return an {@link ASPCore2Program} representing the parsed ASP code
55+
*/
56+
ASPCore2Program readProgramString(String aspString, Map<String, PredicateInterpretation> externals);
57+
58+
/**
59+
* Convenience method to parse ASP strings not containing any user-defined external atoms, see {@link Alpha#readProgramString(String, Map)}.
60+
*/
61+
ASPCore2Program readProgramString(String aspString);
62+
63+
/**
64+
* Prepares a {@link DebugSolvingContext} for the given {@link ASPCore2Program} to debug program preprocessing.
65+
*
66+
* @return a {@link DebugSolvingContext} holding debug information for the given program
67+
*/
68+
DebugSolvingContext prepareDebugSolve(final ASPCore2Program program);
69+
70+
/**
71+
* Prepares a {@link DebugSolvingContext} for the given {@link NormalProgram} to debug program preprocessing.
72+
*
73+
* @return a {@link DebugSolvingContext} holding debug information for the given program
74+
*/
75+
DebugSolvingContext prepareDebugSolve(final NormalProgram program);
76+
77+
/**
78+
* Prepares a {@link DebugSolvingContext} for the given {@link ASPCore2Program} to debug program preprocessing.
79+
*
80+
* @param filter a {@link java.util.function.Predicate} against which {@link Predicate}s of answer sets are tested.
81+
* @return a {@link DebugSolvingContext} holding debug information for the given program
82+
*/
83+
DebugSolvingContext prepareDebugSolve(final ASPCore2Program program, java.util.function.Predicate<Predicate> filter);
84+
85+
/**
86+
* Prepares a {@link DebugSolvingContext} for the given {@link NormalProgram} to debug program preprocessing.
87+
*
88+
* @param filter a {@link java.util.function.Predicate} against which {@link Predicate}s of answer sets are tested.
89+
* @return a {@link DebugSolvingContext} holding debug information for the given program
90+
*/
91+
DebugSolvingContext prepareDebugSolve(final NormalProgram program, java.util.function.Predicate<Predicate> filter);
92+
93+
/**
94+
* Solves the given {@link ASPCore2Program}.
95+
* @param program an input program
96+
* @return a {@link Stream} of {@link AnswerSet}s of the given program
97+
*/
98+
Stream<AnswerSet> solve(ASPCore2Program program);
99+
100+
/**
101+
* Solves the given {@link ASPCore2Program}.
102+
* @param program an input program
103+
* @param filter a {@link java.util.function.Predicate} against which {@link Predicate}s of answer sets are tested.
104+
* @return a {@link Stream} of {@link AnswerSet}s of the given program
105+
*/
106+
Stream<AnswerSet> solve(ASPCore2Program program, java.util.function.Predicate<Predicate> filter);
107+
108+
/**
109+
* Solves the given {@link NormalProgram}.
110+
* @param program an input program
111+
* @return a {@link Stream} of {@link AnswerSet}s of the given program
112+
*/
113+
Stream<AnswerSet> solve(NormalProgram program);
114+
115+
/**
116+
* Solves the given {@link NormalProgram}.
117+
* @param program an input program
118+
* @param filter a {@link java.util.function.Predicate} against which {@link Predicate}s of answer sets are tested.
119+
* @return a {@link Stream} of {@link AnswerSet}s of the given program
120+
*/
121+
Stream<AnswerSet> solve(NormalProgram program, java.util.function.Predicate<Predicate> filter);
122+
123+
/**
124+
* Normalizes a program, i.e. rewrites all syntax constructs not natively supported by Alphas back-end into semantically equivalent ASP code.
125+
* See {@link NormalProgram},
126+
* @param program An {@link ASPCore2Program} to normalize
127+
* @return a {@link NormalProgram} that is a semantic equivalent to the given input program
128+
*/
129+
NormalProgram normalizeProgram(ASPCore2Program program);
130+
131+
/**
132+
* Constructs a @{link Solver} pre-loaded with the given {@link ASPCore2Program} from which {@link AnswerSet}s can be obtained via {@link Solver#stream()}.
133+
*
134+
* @param program the program to solve
135+
* @param filter a {@link java.util.function.Predicate} against which {@link Predicate}s of answer sets are tested.
136+
* @return a {@link Solver} pre-loaded withthe given program
137+
*/
138+
Solver prepareSolverFor(ASPCore2Program program, java.util.function.Predicate<Predicate> filter);
139+
140+
/**
141+
* Constructs a @{link Solver} pre-loaded with the given {@link NormalProgram} from which {@link AnswerSet}s can be obtained via {@link Solver#stream()}.
142+
*
143+
* @param program the program to solve
144+
* @param filter a {@link java.util.function.Predicate} against which {@link Predicate}s of answer sets are tested.
145+
* @return a {@link Solver} pre-loaded withthe given program
146+
*/
147+
Solver prepareSolverFor(NormalProgram program, java.util.function.Predicate<Predicate> filter);
148+
149+
}

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

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
package at.ac.tuwien.kr.alpha.api;
2+
3+
import java.util.List;
4+
import java.util.SortedSet;
5+
6+
import at.ac.tuwien.kr.alpha.api.programs.Predicate;
7+
import at.ac.tuwien.kr.alpha.api.programs.atoms.Atom;
8+
9+
/**
10+
* API representation of an answer set, i.e. a set of atoms that is a model of an ASP program.
11+
*
12+
* Copyright (c) 2021, the Alpha Team.
13+
*/
14+
public interface AnswerSet extends Comparable<AnswerSet> {
15+
16+
/**
17+
* The set of all predicates contained in the answer set.
18+
*/
19+
SortedSet<Predicate> getPredicates();
20+
21+
/**
22+
* All instances of the given predicate within the answer set.
23+
*/
24+
SortedSet<Atom> getPredicateInstances(Predicate predicate);
25+
26+
/**
27+
* Boolean flag indicating whether this {@link AnswerSet} represents the empty set.
28+
*/
29+
boolean isEmpty();
30+
31+
/**
32+
* List {@link Atom}s in this answer set satisfying the given {@link AnswerSetQuery}.
33+
*/
34+
List<Atom> query(AnswerSetQuery query);
35+
}

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

+82
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
package at.ac.tuwien.kr.alpha.api;
2+
3+
import java.util.List;
4+
5+
import at.ac.tuwien.kr.alpha.api.programs.atoms.Atom;
6+
import at.ac.tuwien.kr.alpha.api.terms.Term;
7+
8+
/**
9+
* A {@link java.util.function.Predicate} testing {@link Atom}s in order to query {@link AnswerSet}s for {@link Atom}s satisfying a specific
10+
* query.
11+
*
12+
* Copyright (c) 2021, the Alpha Team.
13+
*/
14+
public interface AnswerSetQuery extends java.util.function.Predicate<Atom> {
15+
16+
/**
17+
* Adds a filter predicate to apply on terms at the given index position.
18+
*
19+
* @param termIdx the term index on which to apply the new filter
20+
* @param filter a filter predicate
21+
* @return this answer set query withthe given filter added
22+
*/
23+
AnswerSetQuery withFilter(int termIdx, java.util.function.Predicate<Term> filter);
24+
25+
/**
26+
* Convenience method - adds a filter to match names of symbolic constants against a string.
27+
*
28+
* @param termIdx
29+
* @param str
30+
* @return
31+
*/
32+
AnswerSetQuery withConstantEquals(int termIdx, String str);
33+
34+
/**
35+
* Convenience method - adds a filter to match values of constant terms against a string.
36+
*
37+
* @param termIdx
38+
* @param str
39+
* @return
40+
*/
41+
AnswerSetQuery withStringEquals(int termIdx, String str);
42+
43+
/**
44+
* Convenience method - adds a filter to check for function terms with a given function symbol and arity.
45+
*
46+
* @param termIdx
47+
* @param funcSymbol
48+
* @param funcArity
49+
* @return
50+
*/
51+
AnswerSetQuery withFunctionTerm(int termIdx, String funcSymbol, int funcArity);
52+
53+
/**
54+
* Convenience method - adds a filter to check whether a term is equal to a given term.
55+
*
56+
* @param termIdx
57+
* @param otherTerm
58+
* @return
59+
*/
60+
AnswerSetQuery withTermEquals(int termIdx, Term otherTerm);
61+
62+
/**
63+
* Applies this query to an atom. Filters are worked off in
64+
* order of ascending term index in a conjunctive fashion, i.e. for an atom
65+
* to match the query, all of its terms must satisfy all filters on these
66+
* terms
67+
*
68+
* @param atom the atom to which to apply the query
69+
* @return true iff the atom satisfies the query
70+
*/
71+
@Override
72+
boolean test(Atom atom);
73+
74+
/**
75+
* Applies this query to an {@link AnswerSet}.
76+
*
77+
* @param as
78+
* @return
79+
*/
80+
List<Atom> applyTo(AnswerSet as);
81+
82+
}

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

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
package at.ac.tuwien.kr.alpha.api;
2+
3+
import at.ac.tuwien.kr.alpha.api.programs.ASPCore2Program;
4+
import at.ac.tuwien.kr.alpha.api.programs.Predicate;
5+
import at.ac.tuwien.kr.alpha.api.terms.Term;
6+
7+
/**
8+
* A comparison operator that can be used in {@link ASPCore2Program}s.
9+
*
10+
* Copyright (c) 2021, the Alpha Team.
11+
*/
12+
public interface ComparisonOperator {
13+
14+
/**
15+
* The operator symbol, i.e. the operator's string representation.
16+
*/
17+
String getSymbol();
18+
19+
/**
20+
* The {@link Predicate} associated with this operator.
21+
*/
22+
Predicate toPredicate();
23+
24+
/**
25+
* The inverse of this operator (e.g. the inverse of "=" is "!=")
26+
*/
27+
ComparisonOperator negate();
28+
29+
/**
30+
* Tests whether two terms are in the relation defined by this operator.
31+
*/
32+
boolean compare(Term t1, Term t2);
33+
34+
}

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

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
package at.ac.tuwien.kr.alpha.api;
2+
3+
import at.ac.tuwien.kr.alpha.api.programs.ASPCore2Program;
4+
import at.ac.tuwien.kr.alpha.api.programs.NormalProgram;
5+
import at.ac.tuwien.kr.alpha.api.programs.analysis.ComponentGraph;
6+
import at.ac.tuwien.kr.alpha.api.programs.analysis.DependencyGraph;
7+
8+
/**
9+
* Wrapper object for debug information on program preprocessing produced by {@link Alpha}.
10+
*
11+
* Copyright (c) 2021, the Alpha Team.
12+
*/
13+
public interface DebugSolvingContext {
14+
15+
/**
16+
* The normalized version of the {@link ASPCore2Program} that is being solved.
17+
* See {@link Alpha#normalizeProgram(ASPCore2Program)}.
18+
*/
19+
NormalProgram getNormalizedProgram();
20+
21+
/**
22+
* The fully preprocessed version of the {@link ASPCore2Program} that is being solved.
23+
* This differs from the value of {@link DebugSolvingContext#getNormalizedProgram()} in the stratified part of the normalized program may
24+
* already be evaluated depending on the respective configuration of {@link Alpha}.
25+
*/
26+
NormalProgram getPreprocessedProgram();
27+
28+
/**
29+
* The {@link DependencyGraph} of the program being solved.
30+
*/
31+
DependencyGraph getDependencyGraph();
32+
33+
/**
34+
* The {@link ComponentGraph} of the program being solved.
35+
*/
36+
ComponentGraph getComponentGraph();
37+
38+
/**
39+
* A {@link Solver} instance pre-loaded with the program being solved, from which {@link AnswerSet}s can be streamed.
40+
*/
41+
Solver getSolver();
42+
43+
}

0 commit comments

Comments
 (0)