From 9b51dcfe1b64bafa0c38f18a6ab2f103789007ee Mon Sep 17 00:00:00 2001 From: Karolina Bogacka Date: Wed, 9 Apr 2025 18:25:31 +0200 Subject: [PATCH 1/9] nice readme --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index 56b552a..52997e2 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,18 @@ To convert from Jelly to RDF run: $ ./jelly-cli rdf from-jelly input.jelly > output.ttl ``` +To inspect a Jelly file and get basic statistics describing its contents, run + +```shell +$ ./jelly-cli rdf inspect input.jelly +``` + +To validate a Jelly file, run + +```shell +$ ./jelly-cli rdf validate input.jelly +``` + Use the `--help` option to learn more about all the available settings: ```shell @@ -35,6 +47,8 @@ $ ./jelly-cli rdf from-jelly --help $ ./jelly-cli rdf inspect --help ``` +For more information, go to the official [jelly-cli documentation](https://jelly-rdf.github.io/dev/use-cases/jelly-cli). + Alternatively, you can use the JAR build, which runs on any platform, as long as you have Java (min. version 17). Go to the **[releases page](https://github.com/Jelly-RDF/cli/releases)** and download the `jelly-cli.jar` file. Then, run it like so: ```shell From 5121f23a06d6ac704a290f07b986a208df2c6a0f Mon Sep 17 00:00:00 2001 From: Karolina Bogacka Date: Wed, 9 Apr 2025 21:47:23 +0200 Subject: [PATCH 2/9] Add more examples to readme --- README.md | 43 ++++++++++++++++++- .../jelly/cli/command/rdf/RdfInspect.scala | 2 +- 2 files changed, 42 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 52997e2..dfb8328 100644 --- a/README.md +++ b/README.md @@ -15,30 +15,62 @@ $ chmod +x jelly-cli $ ./jelly-cli --help ``` +## Usage + +### Convert RDF to Jelly + To convert an RDF file (e.g., Turtle) to Jelly, simply run: ```shell $ ./jelly-cli rdf to-jelly input.ttl > output.jelly ``` +### Convert Jelly to RDF + To convert from Jelly to RDF run: ```shell -$ ./jelly-cli rdf from-jelly input.jelly > output.ttl +$ ./jelly-cli rdf from-jelly input.jelly > output.nq ``` -To inspect a Jelly file and get basic statistics describing its contents, run +By default, `jelly-cli` will translate files to NQuads. +But you can also specify the output format with `--out-format`, for example: + +```shell +$ ./jelly-cli rdf from-jelly input.jelly --out-format=ttl > output.ttl +``` + +You can specify most well-known formats supported by Apache Jena, but also a custom Jelly-Text format. +Jelly-Text is a human-readable format that is not meant for machine consumption. It is useful for debugging and inspecting Jelly files. + +### Inspect Jelly files + +To inspect a Jelly file and get basic information describing its contents, such as stream options or number of triples in the file, run ```shell $ ./jelly-cli rdf inspect input.jelly ``` +You can also compute triple and quad counts separately for each frame with the `--per-frame` option: + +```shell +$ ./jelly-cli rdf inspect input.jelly --per-frame +``` + +In both cases, you will get the output as a valid YAML. + +### Validate Jelly files + To validate a Jelly file, run ```shell $ ./jelly-cli rdf validate input.jelly ``` +You can also check whether the Jelly file has been encoded using specific stream options or is equivalent to another RDF file. + +### General tips + Use the `--help` option to learn more about all the available settings: ```shell @@ -47,6 +79,13 @@ $ ./jelly-cli rdf from-jelly --help $ ./jelly-cli rdf inspect --help ``` +And use the `--debug` option to get more information about any exceptions you encounter. +You can set it for any of the commands described above, for example: + +```shell +$ ./jelly-cli rdf to-jelly --debug +``` + For more information, go to the official [jelly-cli documentation](https://jelly-rdf.github.io/dev/use-cases/jelly-cli). Alternatively, you can use the JAR build, which runs on any platform, as long as you have Java (min. version 17). Go to the **[releases page](https://github.com/Jelly-RDF/cli/releases)** and download the `jelly-cli.jar` file. Then, run it like so: diff --git a/src/main/scala/eu/neverblink/jelly/cli/command/rdf/RdfInspect.scala b/src/main/scala/eu/neverblink/jelly/cli/command/rdf/RdfInspect.scala index 04e2609..638243b 100644 --- a/src/main/scala/eu/neverblink/jelly/cli/command/rdf/RdfInspect.scala +++ b/src/main/scala/eu/neverblink/jelly/cli/command/rdf/RdfInspect.scala @@ -31,7 +31,7 @@ case class RdfInspectOptions( "Whether to print the statistics per frame (default: false). " + "If true, the statistics are computed and printed separately for each frame in the stream.", ) - @ExtraName("per-frame") perFrame: Boolean = false, + perFrame: Boolean = false, ) extends HasJellyCommandOptions object RdfInspect extends JellyCommand[RdfInspectOptions]: From 8c1c32f2c84580ab3df595011aa06151606f6487 Mon Sep 17 00:00:00 2001 From: Karolina Bogacka Date: Wed, 9 Apr 2025 21:47:42 +0200 Subject: [PATCH 3/9] Add more examples to readme --- build.sbt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build.sbt b/build.sbt index 4c2fb19..c777222 100644 --- a/build.sbt +++ b/build.sbt @@ -6,7 +6,7 @@ resolvers += "Sonatype OSS Snapshots" at "https://s01.oss.sonatype.org/content/repositories/snapshots" lazy val jenaV = "5.3.0" -lazy val jellyV = "2.10.0" +lazy val jellyV = "2.10.1" addCommandAlias("fixAll", "scalafixAll; scalafmtAll") From 2a4a31423e432936e2cbbf6d4196d2eb40b4bec7 Mon Sep 17 00:00:00 2001 From: Karolina-Bogacka Date: Wed, 9 Apr 2025 22:02:59 +0200 Subject: [PATCH 4/9] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Piotr Sowiński --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index dfb8328..b356621 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ $ ./jelly-cli rdf from-jelly input.jelly --out-format=ttl > output.ttl ``` You can specify most well-known formats supported by Apache Jena, but also a custom Jelly-Text format. -Jelly-Text is a human-readable format that is not meant for machine consumption. It is useful for debugging and inspecting Jelly files. +Jelly-Text is a human-readable translation of Jelly binary. It's not meant for machine consumption. It is useful for debugging and inspecting Jelly files. ### Inspect Jelly files From 7ebf153c559168d0e1eff0235c4d7b7da7aa9c32 Mon Sep 17 00:00:00 2001 From: Karolina-Bogacka Date: Wed, 9 Apr 2025 22:03:10 +0200 Subject: [PATCH 5/9] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Piotr Sowiński --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b356621..842d991 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ To inspect a Jelly file and get basic information describing its contents, such $ ./jelly-cli rdf inspect input.jelly ``` -You can also compute triple and quad counts separately for each frame with the `--per-frame` option: +You can also compute the statistics separately for each stream frame with the `--per-frame` option: ```shell $ ./jelly-cli rdf inspect input.jelly --per-frame From 9474ae3a9255a10c80a4077f9c144d2b101a7fc1 Mon Sep 17 00:00:00 2001 From: Karolina-Bogacka Date: Wed, 9 Apr 2025 22:05:14 +0200 Subject: [PATCH 6/9] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Piotr Sowiński --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 842d991..f860976 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ To validate a Jelly file, run $ ./jelly-cli rdf validate input.jelly ``` -You can also check whether the Jelly file has been encoded using specific stream options or is equivalent to another RDF file. +You can also check whether the Jelly file has been encoded using specific stream options or is equivalent to another RDF file, with the use of additional options to this command. ### General tips @@ -77,6 +77,7 @@ Use the `--help` option to learn more about all the available settings: $ ./jelly-cli rdf to-jelly --help $ ./jelly-cli rdf from-jelly --help $ ./jelly-cli rdf inspect --help +$ ./jelly-cli rdf validate --help ``` And use the `--debug` option to get more information about any exceptions you encounter. From 6a59eb7a1fa36ff700a1b98f84eb1175f0336e55 Mon Sep 17 00:00:00 2001 From: Karolina Bogacka Date: Wed, 9 Apr 2025 22:18:27 +0200 Subject: [PATCH 7/9] Add more tweaks --- README.md | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index f860976..34a7a31 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@ # jelly-cli -***Warning: This project is in early development and is not yet ready for production use.*** - -CLI utility for working with Jelly data. +Fast and convenient CLI utility for working with Jelly data. ## Quick start @@ -80,16 +78,11 @@ $ ./jelly-cli rdf inspect --help $ ./jelly-cli rdf validate --help ``` -And use the `--debug` option to get more information about any exceptions you encounter. -You can set it for any of the commands described above, for example: - -```shell -$ ./jelly-cli rdf to-jelly --debug -``` +And use the `--debug` option to get more information about any exceptions you encounter. -For more information, go to the official [jelly-cli documentation](https://jelly-rdf.github.io/dev/use-cases/jelly-cli). +## Alternative installation -Alternatively, you can use the JAR build, which runs on any platform, as long as you have Java (min. version 17). Go to the **[releases page](https://github.com/Jelly-RDF/cli/releases)** and download the `jelly-cli.jar` file. Then, run it like so: +If for some reason the binaries wouldn't work for you, you can use the JAR build. The build runs on any platform, as long as you have Java (min. version 17). Go to the **[releases page](https://github.com/Jelly-RDF/cli/releases)** and download the `jelly-cli.jar` file. Then, run it like so: ```shell java -jar jelly-cli.jar --help From 7f5ddc0d1232bc41d6ab728ea3cb6ad8c2ec9d0c Mon Sep 17 00:00:00 2001 From: Karolina Bogacka Date: Wed, 9 Apr 2025 22:21:15 +0200 Subject: [PATCH 8/9] Add link to jelly --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 34a7a31..24e3a9f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # jelly-cli -Fast and convenient CLI utility for working with Jelly data. +Fast and convenient CLI utility for working with the [Jelly](https://jelly-rdf.github.io/dev/) protocol for RDF streaming. ## Quick start From 482ac281c7ab8c57e4949e8a9269f4ab727b4b7c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotr=20Sowi=C5=84ski?= Date: Wed, 9 Apr 2025 22:24:54 +0200 Subject: [PATCH 9/9] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 24e3a9f..42fabde 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # jelly-cli -Fast and convenient CLI utility for working with the [Jelly](https://jelly-rdf.github.io/dev/) protocol for RDF streaming. +Fast and convenient CLI utility for working with the [Jelly](https://jelly-rdf.github.io/dev/) knowledge graph streaming protocol. ## Quick start