Skip to content

Commit bbba6ab

Browse files
Meng6Meng6
committed
(1) Add Clingo docs; (2) suppress warnings for Clingo
1 parent 9d7c5d9 commit bbba6ab

20 files changed

Lines changed: 616 additions & 64 deletions

File tree

‎docs/cli/create.md‎

Lines changed: 65 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
The *create* command has two subcommands, both of which create a new dataset on disk. The dataset name `:memory:` is a reserved value for datasets that exist only in memory and is not allowed in the CLI.
1+
The *create* command has three subcommands, all of which create a new dataset on disk. The dataset name `:memory:` is a reserved value for datasets that exist only in memory and is not allowed in the CLI.
22

33
```
44
Usage: geist create [OPTIONS] COMMAND [ARGS]...
@@ -9,10 +9,74 @@ Options:
99
--help Show this message and exit.
1010
1111
Commands:
12+
clingo Create a new ASP dataset using Clingo
1213
duckdb Create a new SQL dataset using DuckDB
1314
rdflib Create a new RDF dataset using RDFLib
1415
```
1516

17+
??? info "geist create clingo [OPTIONS]"
18+
19+
```
20+
Usage: geist create clingo [OPTIONS]
21+
22+
Create a new ASP dataset using Clingo
23+
24+
Options:
25+
-d, --dataset TEXT Name of ASP dataset to create (default "kb")
26+
-ifile, --inputfile FILENAME Path of the file to be loaded as facts,
27+
rules, and contraints [required]
28+
-iformat, --inputformat [lp|csv|json]
29+
Format of the file to be loaded as facts,
30+
rules, and constraints. Note that "csv" only
31+
supports facts (default "lp"). If multiple
32+
possibilities are provided (as a list), only
33+
the first one will be considered.
34+
-pred, --predicate TEXT "isfirstcol" for using the first column as
35+
the predicate name; strings other than
36+
"isfirstcol" are used as the predicate name
37+
directly (default: "isfirstcol")
38+
-prog, --programname TEXT Name of the program (default: "base")
39+
--help Show this message and exit.
40+
```
41+
42+
??? example "Example 1: create a `test` ASP dataset from stdin with LP format"
43+
44+
```
45+
geist create clingo --dataset test --inputformat lp << __END_INPUT__
46+
friends(a, b).
47+
friends(a, c).
48+
__END_INPUT__
49+
```
50+
51+
??? example "Example 2: create a `test` ASP dataset from a file with LP format"
52+
53+
Here is the `friends.lp` file:
54+
55+
```file
56+
friends(a, b).
57+
friends(a, c).
58+
```
59+
60+
Code:
61+
```
62+
geist create clingo --dataset test --inputfile friends.lp --inputformat lp
63+
```
64+
65+
??? example "Example 3: create a `test` ASP dataset from a CSV file"
66+
67+
Here is the `friends.csv` file:
68+
69+
```file
70+
arg1,arg2
71+
a,b
72+
a,c
73+
```
74+
75+
Code:
76+
```
77+
geist create clingo --dataset test --inputfile friends.csv --inputformat csv --predicate friends
78+
```
79+
1680
??? info "geist create duckdb [OPTIONS]"
1781

1882
```

‎docs/cli/destroy.md‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
*destroy* command can delete a dataset. The `.duckdb` or the `.pkl` file of the corresponding dataset will be discarded.
22

3-
There are two subcommands for *destroy*:
3+
There are three subcommands for *destroy*:
44
```
55
Usage: geist destroy [OPTIONS] COMMAND [ARGS]...
66
@@ -10,10 +10,37 @@ Options:
1010
--help Show this message and exit.
1111
1212
Commands:
13+
clingo Delete an ASP dataset
1314
duckdb Delete a SQL dataset
1415
rdflib Delete an RDF dataset
1516
```
1617

18+
??? info "geist destroy clingo [OPTIONS]"
19+
20+
```
21+
Usage: geist destroy clingo [OPTIONS]
22+
23+
Delete an ASP dataset
24+
25+
Options:
26+
-d, --dataset TEXT Name of an ASP dataset to be removed (default "kb")
27+
-q, --quiet Suppress error messages if the provided dataset does not
28+
exist
29+
--help Show this message and exit.
30+
```
31+
32+
??? example "Example: delete the `test` ASP dataset"
33+
34+
```
35+
geist destroy clingo --dataset test
36+
```
37+
38+
The `.geistdata/clingo/test.pkl` file will be removed after this operation. By default, you will get an error message if the provided dataset (in this case, it is the `test` dataset) does not exist. To suppress this error message, you can add `--quiet`:
39+
40+
```
41+
geist destroy clingo --dataset test --quiet
42+
```
43+
1744
??? info "geist destroy duckdb [OPTIONS]"
1845

1946
```

‎docs/cli/export.md‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
*export* command can export a dataset.
22

3-
There are two subcommands for *export*:
3+
There are three subcommands for *export*:
44
```
55
Usage: geist export [OPTIONS] COMMAND [ARGS]...
66
@@ -10,10 +10,44 @@ Options:
1010
--help Show this message and exit.
1111
1212
Commands:
13+
clingo Export an ASP dataset
1314
duckdb Export a SQL dataset
1415
rdflib Export an RDF dataset
1516
```
1617

18+
??? info "geist export clingo [OPTIONS]"
19+
20+
```
21+
Usage: geist export clingo [OPTIONS]
22+
23+
Export an ASP dataset
24+
25+
Options:
26+
-d, --dataset TEXT Name of an ASP dataset to be exported
27+
(default "kb")
28+
-oroot, --outputroot TEXT Path of the directory to store the exported
29+
data (default: current directory). If the
30+
given path (i.e., --outputfile) is None or a
31+
relative path, it will be ignored.
32+
-ofile, --outputfile TEXT Path of the file to store the exported data
33+
(default: None). This file can be reused to
34+
create a dataset by setting
35+
inputformat=json.
36+
-rformat, --returnformat [lp|df|dict]
37+
Format of the returned data in memory
38+
(default lp)
39+
-pred, --predicate TEXT Name of the predicate to be exported
40+
(default "predicate")
41+
--help Show this message and exit.
42+
```
43+
44+
??? example "Example: export the `test` ASP dataset"
45+
46+
By default, the exported data will be printed in terminal:
47+
```
48+
geist export clingo --dataset test
49+
```
50+
1751
??? info "geist export duckdb [OPTIONS]"
1852

1953
```

‎docs/cli/load.md‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
*load* command can import data into an existing dataset.
22

3-
There are two subcommands for *load*:
3+
There are three subcommands for *load*:
44
```
55
Usage: geist load [OPTIONS] COMMAND [ARGS]...
66
@@ -10,10 +10,39 @@ Options:
1010
--help Show this message and exit.
1111
1212
Commands:
13+
clingo Import data into an ASP dataset
1314
duckdb Import data into a SQL dataset
1415
rdflib Import data into a RDF dataset
1516
```
1617

18+
??? info "geist load clingo [OPTIONS]"
19+
20+
```
21+
Usage: geist load clingo [OPTIONS]
22+
23+
Import data into an ASP dataset
24+
25+
Options:
26+
-d, --dataset TEXT Name of an ASP dataset to load a file
27+
(default "kb")
28+
-ifile, --inputfile FILENAME Path of the file to be loaded [required]
29+
-iformat, --inputformat [lp|csv|json]
30+
Format of the file to be loaded (default
31+
"lp"). If multiple possibilities are
32+
provided (as a list), only the first one
33+
will be considered.
34+
-pred, --predicate TEXT Name of the predicate to be loaded (default:
35+
"isfirstcol")
36+
-prog, --programname TEXT Name of the program (default: "base")
37+
--help Show this message and exit.
38+
```
39+
40+
??? example "Example: load a file into the `test` ASP dataset"
41+
42+
```
43+
geist load clingo --dataset test --inputfile new_friends.lp --inputformat lp
44+
```
45+
1746
??? info "geist load duckdb [OPTIONS]"
1847

1948
```

‎docs/cli/query.md‎

Lines changed: 55 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
*query* command can perform a query on a dataset.
22

3-
There are two subcommands for *query*:
3+
There are three subcommands for *query*:
44
```
55
Usage: geist query [OPTIONS] COMMAND [ARGS]...
66
@@ -10,10 +10,64 @@ Options:
1010
--help Show this message and exit.
1111
1212
Commands:
13+
clingo Perform an ASP query on a dataset
1314
duckdb Perform a SQL query on a dataset
1415
rdflib Perform a SPARQL query on a dataset
1516
```
1617

18+
??? info "geist query clingo [OPTIONS]"
19+
20+
```
21+
Usage: geist query clingo [OPTIONS]
22+
23+
Perform an ASP query on a dataset
24+
25+
Options:
26+
-d, --dataset TEXT Name of ASP dataset to be queried (default
27+
"kb")
28+
-ifile, --inputfile FILENAME Specify either the path of the file
29+
containing the ASP query to execute or
30+
provide the ASP query itself via stdin
31+
[required]
32+
-oroot, --outputroot TEXT Path of the directory to store the query
33+
results (default: current directory). If the
34+
given path (i.e., --outputfile) is None or a
35+
relative path, it will be ignored.
36+
-ofile, --outputfile TEXT Path of the file to store the query results
37+
(default: None). This file can be reused to
38+
create a dataset by setting
39+
inputformat=json.
40+
-rformat, --returnformat [lp|df|dict]
41+
Format of the returned data in memory
42+
(default lp)
43+
-pred, --predicate TEXT Name of the predicate to be queried
44+
-prog, --programname TEXT Name of the program
45+
--help Show this message and exit.
46+
```
47+
48+
??? example "Example 1: query the `test` ASP dataset from stdin"
49+
50+
```
51+
geist query clingo --dataset test << __END_QUERY__
52+
53+
friends(X, Z) :- friends(X, Y), friends(Y, Z), X < Z.
54+
friends(Y, Z) :- friends(X, Y), friends(X, Z), Y < Z.
55+
56+
__END_QUERY__
57+
```
58+
59+
??? example "Example 2: query the `test` ASP dataset from a query file"
60+
61+
```
62+
geist query clingo --dataset test --inputfile query
63+
```
64+
65+
Here is the query file's content:
66+
```
67+
friends(X, Z) :- friends(X, Y), friends(Y, Z), X < Z.
68+
friends(Y, Z) :- friends(X, Y), friends(X, Z), Y < Z.
69+
```
70+
1771
??? info "geist query duckdb [OPTIONS]"
1872

1973
```

‎docs/geist-templates/tags/tag-create.md‎

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,14 @@ The `create` tag creates a dataset based on the given string. By default, the gi
33
|Name | Description |
44
|---------------|-------------|
55
|`dataset` |Name of RDF dataset to create (by default, `kb`) |
6-
|`datastore` |Data backend. `duckdb` and `rdflib` are available for now. (by default, `rdflib`) |
6+
|`datastore` |Data backend. `duckdb`, `rdflib`, and `clingo` are available. (by default, `rdflib`) |
77
|`inputformat` |Format of the file to be loaded as triples (by default, `json-ld`). It has to be one of {`xml`, `n3`, `turtle`, `nt`, `pretty-xml`, `trix`, `trig`, `nquads`, `json-ld`, `hext`, `csv`} |
88
|`infer` |Inference to perform on update choosing from {`none`, `rdfs`, `owl`, `rdfs_owl`} (by default, `none`). Please check [OWL-RL](https://owl-rl.readthedocs.io/en/latest/owlrl.html) document for detailed information. |
99
|`isfilepath` |A bool value to denote if the given data is a file path or not (by default: `True`, which denotes the given data is a file path) |
1010
|`table` |Table name. Available for `duckdb` data backend only. |
1111
|`colnames` |Column names of triples with the format of `[[subject1, predicate1, object1], [subject2, predicate2, object2], ...]` when the input format is csv (by default, `None`). Available for `rdflib` data backend only. |
12+
|`predicate` |`'isfirstcol'` for using the first column as the predicate name; strings other than `'isfirstcol'` are used as the predicate name directly (by default, `'isfirstcol'`). Available for `clingo` data backend only. |
13+
|`name` |Name of the program (by default, `'base'`). Available for `clingo` data backend only. |
1214

1315
??? example "Example 1: the given string is not a file path"
1416

@@ -19,7 +21,30 @@ The `create` tag creates a dataset based on the given string. By default, the gi
1921
{% endcreate %}
2022
```
2123

22-
??? example "Example 2: the given string is a file path"
24+
??? example "Example 2: create a Clingo dataset (the given string is not a file path)"
25+
26+
```
27+
{% create "test", datastore="clingo", inputformat="lp", isfilepath=False %}
28+
friends(a, b).
29+
friends(a, c).
30+
{% endcreate %}
31+
```
32+
33+
??? example "Example 3: create a Clingo dataset from a file"
34+
35+
Here is the `friends.lp` file:
36+
37+
```file
38+
friends(a, b).
39+
friends(a, c).
40+
```
41+
42+
Code:
43+
```
44+
{% create "test", datastore="clingo", inputformat="lp", isfilepath=True %} friends.lp {% endcreate %}
45+
```
46+
47+
??? example "Example 4: the given string is a file path"
2348

2449
Here is the `test.nt` file:
2550

‎docs/geist-templates/tags/tag-destroy.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ The `destroy` tag deletes a dataset. Here are parameters of the `destroy` tag:
33
| Name | Description |
44
|---------------|----------------------------------------------------------------|
55
|`dataset` | Name of RDF dataset to be removed (default `kb`) |
6-
|`datastore` | Data backend. `duckdb` and `rdflib` are available for now. (by default, `rdflib`) |
6+
|`datastore` | Data backend. `duckdb`, `rdflib`, and `clingo` are available. (by default, `rdflib`) |
77
|`quiet` | Suppress error messages if the provided dataset does not exist |
88

99
??? example "Example: delete the `test` dataset"
@@ -16,7 +16,7 @@ The `destroy` tag deletes a dataset. Here are parameters of the `destroy` tag:
1616
{% destroy "test" %}
1717
```
1818

19-
The `.geistdata/test.pkl` file will be removed after this operation. By default, you will get an error message if the provided dataset (in this case, it is the `test` dataset) does not exist. To suppress this error message, you can add the `quiet` parameter:
19+
The dataset file (e.g., `.geistdata/rdflib/test.pkl`) will be removed after this operation. By default, you will get an error message if the provided dataset (in this case, it is the `test` dataset) does not exist. To suppress this error message, you can add the `quiet` parameter:
2020

2121
```
2222
{% destroy "test", quiet=True %}

‎docs/geist-templates/tags/tag-load.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,22 @@ The `load` tag imports data into a dataset. Here are parameters of the `load` ta
33
| Name | Description |
44
|---------------|----------------------------------------------------------------|
55
|`dataset` | Name of RDF dataset to be removed (default `kb`) |
6-
|`datastore` | Data backend. `duckdb` and `rdflib` are available for now. (by default, `rdflib`) |
6+
|`datastore` | Data backend. `duckdb`, `rdflib`, and `clingo` are available. (by default, `rdflib`) |
77
|`inputformat` | Format of the file to be loaded as triples (default `json-ld`) |
88
|`isfilepath` | A bool value to denote if the given data is a file path or not (default `True`, which denotes the given data is a file path) |
99
|`table` | Table name to be loaded. Available for `duckdb` data backend only. |
1010
|`colnames` | Column names of triples with the format of `[[subject1, predicate1, object1], [subject2, predicate2, object2], ...]` when the input format is csv. Available for `rdflib` data backend only. |
11+
|`predicate` | `'isfirstcol'` for using the first column as the predicate name; strings other than `'isfirstcol'` are used as the predicate name directly (default `'isfirstcol'`). Available for `clingo` data backend only. |
12+
|`programname` | Name of the program (default `'base'`). Available for `clingo` data backend only. |
1113

12-
??? example "Example: load a file into the `test` dataset"
14+
??? example "Example 1: load a file into the `test` RDF dataset"
1315

1416
```
1517
{% load "test", datastore="rdflib" %} test_add.jsonld {% endload %}
1618
```
19+
20+
??? example "Example 2: load a file into the `test` ASP dataset"
21+
22+
```
23+
{% load "test", datastore="clingo", inputformat="lp" %} new_friends.lp {% endload %}
24+
```

0 commit comments

Comments
 (0)