enola-dev · vorburger · May 13, 2024
diff --git a/docs/concepts/what.md b/docs/concepts/what.md
@@ -0,0 +1,39 @@
+<!--
+    SPDX-License-Identifier: Apache-2.0
+
+    Copyright 2024 The Enola <https://enola.dev> Authors
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+
+# Things & Resources
+
+Enola's main concepts are _Things_ and _Resources._
+
+## Things
+
+Let's talk about things.
+
+In Enola, everything is a _Thing!_ Things have _Properties_ which are identified by _Predicates_ and a _Datatype._
+
+Things have an _[Identity](which.md)._ which lets us _link_ all Things. (At least most of them do; but there can also be "inner Things", which are "anonymous").
+
+[Implementations Details](../dev/implementation.md) has more internal technical details about these things.
+
+## Resources
+
+_Resources_ are what Enola calls things which are just 010011s - without properties like Things. Resources are identified by an URL.
+
+An HTML page on a web server, or a JPEG photo image in a local file on your computer are both examples of a _Resource._
+
+Some resources can be viewed as (converted to) Things.
diff --git a/docs/concepts/which.md b/docs/concepts/which.md
@@ -0,0 +1,108 @@
+<!--
+    SPDX-License-Identifier: Apache-2.0
+
+    Copyright 2024 The Enola <https://enola.dev> Authors
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+
+# Identifiers
+
+<!-- TODO build.bash: cp -r docs/ .be/docs/ && ./enola semmd --in=.be/docs/**.md --out=.be/docs/
+     (BTW The semmd sub-command is just a shortcut for exactly the same as: ./enola rosetta --in=.be/docs/**.md?mediaType=text/x-semmantic-markdown --out=.be/docs/?mediaType=text/markdown?kind=CommonMark)
+
+  TODO
+     * models/youtube.ttl
+
+     * models/enola.dev/emoji.ttl:
+
+     * models/enola.dev/term.ttl
+
+     * models/enola.dev/wikipedia.ttl
+  -->
+
+Humans [name :snowman: things](https://youtube.com/TODO) <!-- youtube:3 Männer im Schnee, "Der Mensch muss heissen", Kazimir) -->.
+Because they are :brain: so smart, they usually know _what_ things they're talking about with these _names_ (often from _"context")._
+
+Computers on the other hand are pretty stupid, and it helps them to have crystal clear unique names of what's what; so Enola uses the following.
+
+## URL
+
+An _"Uniform Resource Locator"_ ([[URL]]) is well-known e.g. as the [[Text]] which you can type into your [[web browsers]]'s address bar. Your browser "fetches" (gets) the [[enola:Resource]] which that URL _"points to"_ - and displays its content to you. Examples of this are:
+
+* <https://google.com> the homepage of the Google Web Search Engine
+* <https://google.com?q=Enola.dev> the web page showing the results of a Google search for "Enola.dev"
+* <https://www.w3.org/assets/logos/w3c/w3c-no-bars.svg> the logo of the W3C
+
+<!-- TODO Callout with Note: or NOTE: or a different syntax? -->
+
+NOTE: URL are actually a lot less great than one may think at first for really uniquely naming things. For example, <https://google.com> and <https://google.com/> (note the trailing `/` slash) are "the same thing" in practice (that homepage) - as is <https://www.google.com/> (note the `www` prefix), or in some other cases something like `https://www.google.com/index.html`.
+
+URLs have _"schemas"_ - that's the string like `https` - anything before the `:` colon, really. The `https` e.g. means "get it via [[enola:net/HTTP]], and `mailto:` e.g. means "this is an [[enola:email/address]] that you can send an [[Email]] to".
+
+<!-- TODO Move Enola CLI usage examples to a separate linked next page, with same headings? -->
+
+Enola supports URLs, of different schemes; here is how to see which:
+
+```bash
+$ ./enola info schemes
+http: HyperText Transfer Protocol; see https://enola.dev/net/http (also https:)
+file: ...
+...
+```
+
+Enola can "fetch" the content that an URL points to, like this:
+
+```bash
+$ ./enola get http://vorburger.ch/hi
+hello, world
+```
+
+Getting an URL can raise various errors:
+
+```bash
+$ ./enola get http://bad.tld/hi
+Error: Could not resolve bad.tld
+```
+
+BTW, fun fact: The _#fragment_ (e.g. in `https://server/path#fragment`) of a URL is not relevant for fetching an URL (only e.g. for scrolling to header in displaying); notice how it doesn't change anything here:
+
+```bash
+$ ./enola get http://vorburger.ch/hi#there
+hello, world
+```
+
+## IRI
+
+An _"Internationalized Resource Identifier"_ ([[IRI]) is something fairly different than an [[URL]].
+
+This can, but don't necceessarily really have to,
+which can be a bit confusing, at first.
+
+Sometimes can be fetched - but this is not a hard requirement of _Linked Data,_ and so sometimes you cannot.
+
+## URI
+
+An [[URI] ...
+
+## Identity
+
+TBD
+
+### ISBN
+
+TBD
+
+### Other
+
+TBD
diff --git a/java/dev/enola/datatype/ProviderX.java b/java/dev/enola/datatype/ProviderX.java
@@ -0,0 +1,39 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Copyright 2024 The Enola <https://enola.dev> Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package dev.enola.datatype;
+
+import dev.enola.data.Provider;
+
+import org.jspecify.annotations.Nullable;
+
+interface ProviderX extends Provider<String, Object> { // NOT ProviderFromIRI<V>
+
+    @Nullable Object get(String name, String datatypeIRI);
+
+    @Nullable <X> X get(String name, Datatype<X> datatype);
+
+    @Nullable <X> X get(String name, Class<X> clazz);
+
+    /**
+     * Because this has no explicit context, it may make an assumption about what you could have
+     * meant, e.g. for something URI like an implementation may assume IRI of Thing instead of URL
+     * of Resource ; it's thus generally better to use the other methods.
+     */
+    @Override
+    @Nullable Object get(String name);
+}
diff --git a/java/dev/enola/thing/resource/ResourceToThingsConverter.java b/java/dev/enola/thing/resource/ResourceToThingsConverter.java
@@ -0,0 +1,29 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Copyright 2024 The Enola <https://enola.dev> Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package dev.enola.thing.resource;
+
+import dev.enola.common.io.resource.Resource;
+import dev.enola.thing.Thing;
+
+import java.util.stream.Stream;
+
+interface ResourceToThingsConverter { // TODO Converter<Resource, Stream<Thing>>
+    // TODO Retrofit the thing the CLI does to --load RDF into this
+
+    Stream<Thing> convert(Resource resource);
+}
diff --git a/mkdocs.yaml b/mkdocs.yaml
@@ -52,6 +52,8 @@ nav:
       - Info: use/info/index.md
   - Models: models/index.md
   - Concepts:
+      - What? Things!: concept/what.md
+      - Which? Identifiers!: concept/which.md
       - Core: concepts/core.md
       - Architecture Diagrams: concepts/core-arch.md
       - Singularity: concepts/singularity.md

diff --git a/models/enola.dev/emoji.ttl b/models/enola.dev/emoji.ttl
@@ -0,0 +1,5 @@
+# TODO https://enola.dev/Emoji is a Datatype with has a RegExp that matches " :.*[a-z ]:"
+
+# TODO https://enola.dev/Emoji/{emoji} is a schema:Identifier subclass, where {emoji} is either ":?crystal ball:?" or 🔮
+
+# TODO https://enola.dev/emoji is the (existing) property, which has range (?) #/Emoji.
diff --git a/models/enola.dev/varia.ttl b/models/enola.dev/varia.ttl
@@ -0,0 +1,56 @@
+@prefix schema: <https://schema.org/>.
+@prefix enola:  <https://enola.dev/>.
+
+enola:Resource a rdfs:Class;
+  enola:identifiedBy schema:URL;
+  schema:description "Resource is the Thing describing what's available at an URL. This is different from a [[rdf:Resource]]).";
+  enola:java/type "dev.enola.thing.ResourceThing".
+
+enola:net/Protocol a rdfs:Class;
+  enola:wikibase TBD; # Infer enola:wikipedia?
+
+enola:net/http a enola:net/Protocol;
+  enola:term "HTTP";
+  schema:name "HyperText Transfer Protocol";
+  enola:rfc "TBD";
+  enola:net/client <enola:webbrowser>, <https://curl.se>, <enola:enola>;
+  enola:wikibase TBD.
+
+enola:net/webbrowser a schema:Software;
+  enola:term "Browser", "Web Browser";
+  schema:name "Web Browser";
+  enola:net/protocol enola:HTTP.
+
+enola:firefox a schema:Software;
+  schema:kindof enola:browser.
+
+enola:chrome a schema:Software;
+  schema:kindof enola:browser.
+
+# TODO Double check that this matches how schema:URL is modeled
+enola:IRI a schema:Class;
+  rdfs:subClassOf schema:Identity;
+  enola:identityOf schema:Thing.
+
+# TODO enola:URI, similar to enola:IRI
+
+# TODO Move the following elsewhere?
+
+enola:identityOf a rdfs:Property;
+  enola:inverseOf enola:identifiedBy.
+
+enola:ThingTemplate a rdfs:Class;
+  schema:description "Template of a Thing. When 'instantiated' (from variables), this 'infers' a (new) Thing.".
+
+enola:Matcher a rdfs:Class;
+
+enola:Term a rdfs:Datatype
+  rdf:subClassOf schema:identity;
+  enola:matcher [
+    enola:regExp "\[\[(<WORDS> .+\)]\]";
+  ], [
+    enola:regExp "\[\[(<NAMESPACE>[a-zA-Z0-9]+:(<NAME>[a-zA-Z0-9]+)\]\]";
+  ].
+
+enola:term a rdf:Property;
+  rdf:range enola:Term.
diff --git a/models/example.org/greetingN.ttl b/models/example.org/greetingN.ttl
@@ -4,5 +4,5 @@
 
 :greeting a rdfs:Class;
   enola:iriTemplate "https://example.org/greet/{NUMBER}";
-  :yo               "http://example.org/hi/{NUMBER}"^^enola:IRITemplate;
-  enola:example     <https://example.org/greet/42>.
+  enola:example     <https://example.org/greet/42>;
+  :yo               "http://example.org/hi/{NUMBER}"^^enola:IRITemplate.
diff --git a/models/schema.org/emojis.ttl b/models/schema.org/emojis.ttl
@@ -1,10 +1,21 @@
 @prefix schema: <https://schema.org/>.
 @prefix enola:  <https://enola.dev/>.
 
+# TODO Rename this now from emojis.ttl to schema.org.ttl
+
+# TODO schema: enola:import "https://raw.githubusercontent.com/schemaorg/schemaorg/main/data/schema.ttl "
+# Note Bene: We're using "quotes" not <link> because it's an URL import needs to fetch, not an IRI link to a Thing!
+
 schema:name enola:emoji "🏷️".
 schema:description enola:emoji "📜".
 schema:image enola:emoji "🖼️".
 schema:url enola:emoji "🔗".
 schema:identifier enola:emoji "🆔".
 schema:email enola:emoji "📨".
 schema:sameAs enola:emoji "🪞".
+
+schema:Text enola:term "Text".
+
+schema:URL
+  enola:term "URL";
+  enola:identityOf enola:Resource.
diff --git a/models/youtube.ttl b/models/youtube.ttl
@@ -0,0 +1,46 @@
+@prefix rdfs:   <http://www.w3.org/2000/01/rdf-schema#>.
+@prefix schema: <https://schema.org/>.
+@prefix enola:  <https://enola.dev/>.
+
+<htps://youtube.com> a <schema:Website>
+  <schema:sameAs> "https://youtube.com/".
+
+enola:youtube/VideoID a rdf:Datatype;
+  rdfs:subClassOf schema:Identity; # TODO TBC
+  enola:regExp "f9[A-Z0-9]+)".
+
+enola:youtube/videoID a rdfs:Property;
+  rdfs:range enola:youtube/VideoID;
+
+enola:youtube/Video a schema:CreativeWork; # Which (ultimately, indirectly) still IS-A rdfs:Class; is it, right??
+  enola:identifiedBy enola:youtube/VideoID;
+  enola:matcher [ # a enola:Matcher;
+    enola:iriTemplate    "htps://youtube.com/watch?v={YTVID}";
+    enola:example        <htps://youtube.com/watch?v=TODO>; # TODO Pick one of my old videos...
+  ], [
+    enola:iriRegExp      "youtube:(<YTVID>f9[A-Z0-9]+)";
+    enola:example        "youtube:f9m7...gY";
+  ];
+  enola:thingTemplate  [ # a enola:ThingTemplate;
+    schema:id(entifier?) "enola:youtube/video/{YTVID}";
+    enola:youtube/videoID "{YTVID}"^^<enola:youtube/VideoID>;
+
+    # TODO Settle if "enola:youtube/video/{YTVID}" is a valid IRI?!
+    # Is the Exception an Enola limitation? An RDF4j Namespace one? An IRI one? An RDF one?
+    # ? <https://enola.dev/youtube/video/{YTVID} a enola:youtube/Video;
+    # ? enola:youtube/video/{YTVID} a enola:youtube/Video;
+    schema:url "htps://youtube.com/watch?v={YTVID}";
+
+    # TODO What Things does Schema.org Validator and Google Search Rich Results show for a YT Video HTML URL?
+    enola:connector <https://enola.dev/connector/htmlThing>
+  ].
+
+enola:youtube/Search a rdfs:Class;
+  enola:matcher [
+    enola:iriRegExp      "youtube:(<SEARCH>[A-Za-z 0-9]+)";
+    enola:example        "youtube:Linked Data";
+  ];
+  enola:thingTemplate  [ # a enola:ThingTemplate;
+    schema:id(entifier?) "enola:youtube/search/{SEARCH}";
+    schema:url "htps://youtube.com/search?q={SEARCH}"; # TODO TBC
+  ].
diff --git a/test/greeting.md b/test/greeting.md
@@ -4,5 +4,5 @@
 
 * [`rdf:type`](https://docs.enola.dev/models/www.w3.org/1999/02/22-rdf-syntax-ns/type/): [`rdfs:Class`](https://docs.enola.dev/models/www.w3.org/2000/01/rdf-schema/Class/)
 * [`enola:iriTemplate`](https://docs.enola.dev/models/enola.dev/iriTemplate/): https://example.org/greet/{NUMBER}
-* [`ex:yo`](https://example.org/yo): http://example.org/hi/{NUMBER} _[`enola:IRITemplate`](https://docs.enola.dev/models/enola.dev/IRITemplate/)_
 * [`enola:example`](https://docs.enola.dev/models/enola.dev/example/): [`ex:greet/42`](greet/_NUMBER.md?NUMBER=42)
+* [`ex:yo`](https://example.org/yo): http://example.org/hi/{NUMBER} _[`enola:IRITemplate`](https://docs.enola.dev/models/enola.dev/IRITemplate/)_