Prepare readme for 0.1

README.md

@@ -1,73 +1,151 @@
-⚠️ This repo is work-in-progress! Before v0.1.0 all APIs are considered unstable and might be subject to change. ⚠️
+[![Read the Docs](https://img.shields.io/readthedocs/rdf4cpp)](https://rdf4cpp.readthedocs.io/en/latest/)
+[![Conan](https://img.shields.io/badge/conan-package-blue)](https://conan.dice-research.org/ui/packages/conan:%2F%2Frdf4cpp) 
+[![GitHub Release](https://img.shields.io/github/v/release/rdf4cpp/rdf4cpp)](https://github.com/rdf4cpp/rdf4cpp/releases)
+![GitHub License](https://img.shields.io/github/license/rdf4cpp/rdf4cpp)
+
 
 # rdf4cpp
 
-rdf4cpp aims to be a stable, modern RDF library for C++, implementing the following standards:
-- [W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes](https://www.w3.org/TR/xmlschema11-2/)
-- [XPath and XQuery Functions and Operators 3.1 ](https://www.w3.org/TR/xpath-functions-31/)
-- [OWL Real and Rational](https://www.w3.org/TR/owl2-syntax/#Datatype_Maps)
+_rdf4cpp_ is a modern C++23 library providing basic RDF support.
+
+The focus is **correctness**, **performance** and **ease-of-use** for **basic building blocks** like:
+
+- parsing, validating and writing RDF data ([N-Triples](https://www.w3.org/TR/n-triples/), [Turtle](https://www.w3.org/TR/turtle/), [N-Quads](https://www.w3.org/TR/n-quads/), [TriG](https://www.w3.org/TR/trig/))
+- Complete and extensible literal datatypes (validation, functions, operations, subtype and promotion casting, mapping to C++ types, error handling, ...) 
+- Managing RDF nodes efficiently
+- Blank node scoping (e.g., for RDF datasets)
+
+_rdf4cpp_ is **not** a **SPARQL engine** or **reasoning engine**, although it provides very basic support for triple/quad
+pattern matching on RDF graphs/datasets. _rdf4cpp_ rather provides the necessary primitives to implement such engines.
+
+We implement the following W3C standards:
 
-Current documentation: https://rdf4cpp.readthedocs.io/en/latest/
+- [RDF 1.1 Concepts and Abstract Syntax](https://www.w3.org/TR/rdf11-concepts/)
+- [XML XSD 1.1 Part 2: Datatypes](https://www.w3.org/TR/xmlschema11-2/) (RDF related parts)
+- [OWL Real and Rational](https://www.w3.org/TR/owl2-syntax/#Datatype_Maps)
+- [XPath and XQuery Functions and Operators 3.1](https://www.w3.org/TR/xpath-functions-31/) (SPARQL related parts)
+
+## Example
+
+```c++
+#include <iostream>
+#include <rdf4cpp.hpp>
+
+int main() {
+    using namespace ::rdf4cpp;
+    using namespace ::rdf4cpp::shorthands;
+    using namespace ::rdf4cpp::namespaces;
+    using namespace ::rdf4cpp::datatypes;
+
+    /// 1) basic dataset, graph and RDF node usage
+    // using namespaces
+    FOAF foaf{};                               // common, predefined namespace
+    Namespace const ex{"http://example.com/"}; // self-declared namespace
+
+    Dataset dataset;
+    // populate a named graph in the dataset
+    auto &graph = dataset.graph(IRI{"http://ex.com/MyGraph"});                                                  // IRI constructor
+    graph.add({"http://example.com/Bob"_iri, "http://example.com/knows"_iri, "http://example.com/Alice"_iri});  // IRI shorthand
+    graph.add({ex + "Alice", foaf + "knows", ex + "Bob"});                                                      // using namespaces
+    graph.add({ex + "Bob", foaf + "name", "Bob"_xsd_string}); // Literal datatype shorthand
+
+    // serialize the dataset as N-Quads
+    std::cout << "Dataset as N-Quads: \n"
+              << dataset << std::endl;
+
+    // 2) Using datatypes and arithmetics
+    // typed Literal instantiation
+    auto const d = Literal::make_typed_from_value<xsd::Double>(2.3); // factory function
+    auto const ui = 42_xsd_uint;         // Literal datatype shorthand
+    auto const dec = "42.1"_xsd_decimal; // infinite precision decimals
+
+    // basic arithmetics with automatic result type deduction
+    auto const r1 = d * dec;            // double * decimal → double
+    auto const r2 = (ui + dec).round(); // round(integer + decimal) → decimal
+
+    std::cout << "Using XSD datatypes, functions and operators: \n"
+              << std::format("{} * {} = {}\n", d, dec, r1)
+              << std::format("ceil({} + {}) = {}", ui, dec, r2) << std::endl;
+
+    return 0;
+}
+```
 
-## Usage 
-check out the [examples](./examples) directory. 
+## Using _rdf4cpp_
 
-### As Conan Package
+_rdf4cpp_ is consumed via Conan 2 but it is not available via [Conan Center](https://conan.io/center).
+Instead, it can be found on the artifactory of the [DICE Research Group](https://dice-research.org/).
 
-Until its first stable release, rdf4cpp will not be available via Conan Center. Instead, it is available via the artifactory of the [DICE Research Group](https://dice-research.org/). 
+You need the package manager [conan](https://conan.io/downloads.html) installed and set up. You can add the DICE
+artifactory with:
 
-You need the [package manager Conan](https://conan.io/downloads.html) installed and set up. You can add the DICE artifactory with:
 ```shell
 conan remote add dice-group https://conan.dice-research.org/artifactory/api/conan/tentris
 ```
 
-To use rdf4cpp, add it to your `conanfile.txt`:
+To use _rdf4cpp_, add it to your `conanfile.txt`:
+
 ```
 [requires]
-rdf4cpp/0.0.58
+rdf4cpp/0.1.0
 ```
 
-Note:
+For getting started how to use rdf4cpp, check out the [examples](./examples) directory and refer to our documentation.
 
-If you want to include rdf4cpp without using conan, make sure you also include its dependencies exposed via the rdf4cpp API.
 
-## Build
 
-### Requirements
+## Developing _rdf4cpp_
 
-Currently, rdf4cpp builds only on linux with a C++20 compatible compiler. 
-CI builds and tests rdf4cpp with gcc-{13}, clang-{17,18,19} with libstdc++-13 on ubuntu 22.04. 
-
-### Dependencies
-It is recommended to include build dependencies via conan. Set up Conan as follows on Ubuntu 22.04+:
-```shell
-sudo apt install python3-pip
-pip3 install --user conan
-conan user
-conan profile new --detect default
-conan profile update settings.compiler.libcxx=libstdc++11 default
-conan remote add dice-group https://conan.dice-research.org/artifactory/api/conan/tentris
-```
+### Compile
 
+_rdf4cpp_ uses CMake and Conan 2. To build it, run:
 
-### Compile
-rdf4cpp uses CMake and conan 2. To build it, run: 
 ```shell
 wget https://github.com/conan-io/cmake-conan/raw/develop2/conan_provider.cmake -O conan_provider.cmake # download conan provider
 cmake -B build_dir -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=conan_provider.cmake # configure and generate
 cmake --build build_dir # compile
 ```
 
 To install it to your system, run afterward:
+
 ```shell
 cd build_dir
 sudo make install
 ```
 
 ### Additional CMake config options:
 
-`-DBUILD_EXAMPLES=ON/OFF [default: OFF]`: Build the examples.
+- `-DBUILD_EXAMPLES=ON/OFF [default: OFF]`: Build the examples.
+- `-DBUILD_TESTING=ON/OFF [default: OFF]`: Build the tests.
+- `-DBUILD_SHARED_LIBS=ON/OFF [default: OFF]`: Build a shared library instead of a static one.
+
+
+## Supported Platforms
+
+- **Linux distributions (x86_64, AArch64)** (e.g. Ubuntu 22.04+, Fedora 42+, etc.) with:
+    - GCC 13+ (libstdc++ 13+; used with both GCC and Clang)
+    - Clang 17+ (except Clang 18 does not work on AArch64)
+    - glibc 2.35+ or musl 1.2.4+
+- **macOS (ARM64)**: macOS Sonoma (14)+ with GCC 13 (via Homebrew)
+
+## Stability
+
+### API Stability
+
+From version 0.1 onwards (before 1.0.0), all high-level public API that the average user is expected to interact with is
+considered stable.
+This includes basically everything, except what is in the `rdf4cpp::storage` and `rdf4cpp::datatypes::registry`
+namespaces.
+Should we ever break anything in these high-level interfaces, we will bump the minor version (for example, from 0.1.0 to
+0.2.0).
+
+### ABI Stability
+
+ABI stability is not guaranteed.
 
-`-DBUILD_TESTING=ON/OFF [default: OFF]`: Build  the tests.
+### POBR Stability
 
-`-DBUILD_SHARED_LIBS=ON/OFF [default: OFF]`: Build a shared library instead of a static one.
+The POBR (Persisted Object Binary Representation) version tracks on-disk format stability (e.g., with allocators
+like [Metall](https://github.com/LLNL/metall)).
+This includes everything in `rdf4cpp::storage::identifiers` but nothing else.
+The current POBR version can be retrieved via `rdf4cpp::pobr_version`.