From 388261f9c1a64e870deb19ac5a842e4d9a978ba8 Mon Sep 17 00:00:00 2001 From: Michael Vorburger Date: Fri, 16 Feb 2024 15:00:53 +0100 Subject: [PATCH] feat(model): Introduce Hello demo model --- docs/models/demo/hello/README.md | 92 +++++++++++++++++++++ docs/models/demo/hello/greeting.proto | 23 ++++++ docs/models/demo/hello/greeting.type.yaml | 22 +++++ docs/models/demo/hello/hello.type.yaml | 23 ++++++ docs/models/demo/hello/linked.proto | 28 +++++++ docs/models/demo/library/favorites.yaml | 26 ++++++ docs/models/demo/library/library.proto | 48 +++++++++++ docs/models/demo/library/library.types.yaml | 41 +++++++++ mkdocs.yaml | 5 +- 9 files changed, 307 insertions(+), 1 deletion(-) create mode 100644 docs/models/demo/hello/README.md create mode 100644 docs/models/demo/hello/greeting.proto create mode 100644 docs/models/demo/hello/greeting.type.yaml create mode 100644 docs/models/demo/hello/hello.type.yaml create mode 100644 docs/models/demo/hello/linked.proto create mode 100644 docs/models/demo/library/favorites.yaml create mode 100644 docs/models/demo/library/library.proto create mode 100644 docs/models/demo/library/library.types.yaml diff --git a/docs/models/demo/hello/README.md b/docs/models/demo/hello/README.md new file mode 100644 index 000000000..472598aad --- /dev/null +++ b/docs/models/demo/hello/README.md @@ -0,0 +1,92 @@ + + +# Hello + +Please first [install Enola](../../../use/), if you haven't already. + +Then let's do a [`hello, world`](https://en.wikipedia.org/wiki/%22Hello,_World!%22_program)! + +## Type + +Greetings are a kind of _Type._ Let's define one, in [`hello.type.yaml`](hello.type.yaml): + + + +```yaml +... +``` + +Now let's use this: + +```bash +./enola --model hello.type.yaml get hello/world +world +``` + + + +## Schema + +Our first `enola.dev/demo/hello` _"type"_ was just a `string`. That was a great start - but now let's define our first _data structure._ We'll use [Protocol Buffers](https://protobuf.dev) (for now, [later others](../../../concepts/core.md#schemas)) to define a _"schema",_ in [`greeting.proto`](greeting.proto): + + + +```proto +... +``` + +and use this by changing that `schema: string:` from above to `proto: dev.enola.demo.hello.Greeting` as in [`greeting.type.yaml`](greeting.type.yaml), and then: + +```bash +./enola --model greeting.type.yaml get hello/world +message: world +``` + +The output is no longer just text, but now structured information - the `message` is `world`. This is YAML format. Enola also supports [other _formats_](../../../concepts/core.md#formats), e.g. as JSON: + +```bash +./enola --model greeting.type.yaml get --format=json hello/world +{ message: world } +``` + +## Template + +TODO Initially not for link but just set `message` to "hello, {{{ greeting }}}" prefix (change `uri: hello/{greeting}`) + +## Link + +TODO [`linked.proto`](linked.proto), with an `enola:` URI template, and here introduce the Web UI!!! + +https://docs.enola.dev/use/connector/#uri-templates + +## Connector + +https://docs.enola.dev/use/connector/#file-system-repository + +## Reflection + +```bash +./enola --model greeting.type.yaml get enola/type/greeting +name: enola.dev/demo/hello +uri: hello/{message} +schema: + proto: dev.enola.demo.hello.Greeting +``` + +Open in the Web interface, and note link to `Greeting`. diff --git a/docs/models/demo/hello/greeting.proto b/docs/models/demo/hello/greeting.proto new file mode 100644 index 000000000..58bf7198b --- /dev/null +++ b/docs/models/demo/hello/greeting.proto @@ -0,0 +1,23 @@ +// SPDX-License-Identifier: Apache-2.0 +// +// Copyright 2023-2024 The Enola 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. + +syntax = "proto3"; + +package dev.enola.demo.hello; + +message Greeting { + string message = 1; +} diff --git a/docs/models/demo/hello/greeting.type.yaml b/docs/models/demo/hello/greeting.type.yaml new file mode 100644 index 000000000..218515a70 --- /dev/null +++ b/docs/models/demo/hello/greeting.type.yaml @@ -0,0 +1,22 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# Copyright 2023-2024 The Enola 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. + +# TODO Publish schema & Remove yaml-language-server +# yaml-language-server: $schema=../../enola/schemas/Type.schema.json + +name: enola.dev/demo/hello +uri: hello/{message} +proto: greeting.proto#dev.enola.demo.hello.Greeting diff --git a/docs/models/demo/hello/hello.type.yaml b/docs/models/demo/hello/hello.type.yaml new file mode 100644 index 000000000..2f78964ee --- /dev/null +++ b/docs/models/demo/hello/hello.type.yaml @@ -0,0 +1,23 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# Copyright 2023-2024 The Enola 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. + +# TODO Publish schema & Remove yaml-language-server +# yaml-language-server: $schema=../../enola/schemas/Type.schema.json + +name: enola.dev/demo/hello +uri: hello/{message} +# TODO Do we *really* need this? +# string: diff --git a/docs/models/demo/hello/linked.proto b/docs/models/demo/hello/linked.proto new file mode 100644 index 000000000..000a7a514 --- /dev/null +++ b/docs/models/demo/hello/linked.proto @@ -0,0 +1,28 @@ +// SPDX-License-Identifier: Apache-2.0 +// +// Copyright 2023-2024 The Enola 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. + +syntax = "proto3"; + +package dev.enola.demo.hello; + +import "core/lib/src/main/java/dev/enola/core/enola_ext.proto"; + +message Greeting { + string message = 1; + string google = 2 + [(dev.enola.url) = "https://www.google.com/search?q={{ message }}"]; + string link = 3 [(dev.enola.type) = "dev.enola.demo.hello"]; +} diff --git a/docs/models/demo/library/favorites.yaml b/docs/models/demo/library/favorites.yaml new file mode 100644 index 000000000..c7951bf4a --- /dev/null +++ b/docs/models/demo/library/favorites.yaml @@ -0,0 +1,26 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# Copyright 2023-2024 The Enola 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. + +# TODO JSON Schema, generated from library.proto! + +isbn: 0434961604 +title: The Little Prince +rating: RATING_TOP_TIP + +--- +isbn: 0-13-140731-7 +rating: RATING_LIKE_IT +# title will be fetched by Connector! diff --git a/docs/models/demo/library/library.proto b/docs/models/demo/library/library.proto new file mode 100644 index 000000000..3c3d6b690 --- /dev/null +++ b/docs/models/demo/library/library.proto @@ -0,0 +1,48 @@ +// SPDX-License-Identifier: Apache-2.0 +// +// Copyright 2023-2024 The Enola 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. + +syntax = "proto3"; + +package dev.enola.demo.library; + +import "core/lib/src/main/java/dev/enola/core/enola_ext.proto"; + +message Book { + string isbn = 1; + // TODO Write a Connector using some REST API which fetches a Book's Title, + // given its ISBN. + string title = 2; + int32 pages = 3; +} + +message Favorite { + string isbn = 1 [(dev.enola.type) = "enola.dev/demo/library/book"]; + + Rating rating = 2; + + enum Rating { + RATING_UNSPECIFIED = 0; + RATING_OH_WELL = 1; + RATING_WHY_NOT = 2; + RATING_ITS_OKY = 3; + RATING_LIKE_IT = 4; + RATING_TOP_TIP = 5; + } +} + +message Favorites { + repeated Favorite favorites = 1; +} diff --git a/docs/models/demo/library/library.types.yaml b/docs/models/demo/library/library.types.yaml new file mode 100644 index 000000000..ee60da890 --- /dev/null +++ b/docs/models/demo/library/library.types.yaml @@ -0,0 +1,41 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# Copyright 2023-2024 The Enola 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. + +# yaml-language-server: $schema=../../enola/schemas/Types.schema.json + +# TODO Demo how to alternative declare this in library.proto, with extensions. + +types: + - name: enola.dev/demo/library/book + proto: library.proto#dev.enola.demo.library.Book + emoji: 📖 + properties: + openlibrary: + link: https://openlibrary.org/search?isbn={path.isbn} + labels: + en: Open Library + google: + link: https://www.google.com/search?tbm=bks&q=isbn:{path.isbn} + labels: + en: Google Book Search + fr: Recherche de Livres sur Google + urn: + # https://en.m.wikipedia.org/wiki/Uniform_Resource_Name + link: urn:isbn:{isbn} + + - name: enola.dev/demo/library/favorites + proto: dev.enola.demo.library.Favorites + emoji: ⭐ diff --git a/mkdocs.yaml b/mkdocs.yaml index ba3297943..44de5e48c 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -26,8 +26,11 @@ copyright: Copyright © 2023 The Enola Authors nav: - News (Blog): blog/index.md - Introduction: index.md + - Installation: use/index.md + - Models: + - Demo: + - Hello: models/demo/hello/README.md - Users: - - Overview: use/index.md - Help: use/help/index.md - Example Model: use/library/index.md - DocGen: use/docgen/index.md