Skip to content

Commit

Permalink
feat(model): Introduce Hello demo model
Browse files Browse the repository at this point in the history
  • Loading branch information
vorburger committed Feb 28, 2024
1 parent debbc2e commit 195defb
Show file tree
Hide file tree
Showing 9 changed files with 307 additions and 1 deletion.
92 changes: 92 additions & 0 deletions docs/models/demo/hello/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
<!--
SPDX-License-Identifier: Apache-2.0
Copyright 2023-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.
-->

# 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):

<!-- TODO Include the YAML, without the LICENSE header -->

```yaml
...
```

Now let's use this:

```bash
./enola --model hello.type.yaml get hello/world
world
```

<!-- TODO Make ExecMD a testing tool, and FAIL if output is not as inlined & excepted -->

## 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):

<!-- TODO Include the Proto, without the LICENSE header -->

```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`.
23 changes: 23 additions & 0 deletions docs/models/demo/hello/greeting.proto
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
// SPDX-License-Identifier: Apache-2.0
//
// Copyright 2023-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.

syntax = "proto3";

package dev.enola.demo.hello;

message Greeting {
string message = 1;
}
22 changes: 22 additions & 0 deletions docs/models/demo/hello/greeting.type.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# SPDX-License-Identifier: Apache-2.0
#
# Copyright 2023-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.

# 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
23 changes: 23 additions & 0 deletions docs/models/demo/hello/hello.type.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# SPDX-License-Identifier: Apache-2.0
#
# Copyright 2023-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.

# 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:
28 changes: 28 additions & 0 deletions docs/models/demo/hello/linked.proto
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
// SPDX-License-Identifier: Apache-2.0
//
// Copyright 2023-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.

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"];
}
26 changes: 26 additions & 0 deletions docs/models/demo/library/favorites.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# SPDX-License-Identifier: Apache-2.0
#
# Copyright 2023-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.

# 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!
48 changes: 48 additions & 0 deletions docs/models/demo/library/library.proto
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
// SPDX-License-Identifier: Apache-2.0
//
// Copyright 2023-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.

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;
}
41 changes: 41 additions & 0 deletions docs/models/demo/library/library.types.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# SPDX-License-Identifier: Apache-2.0
#
# Copyright 2023-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.

# 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:
5 changes: 4 additions & 1 deletion mkdocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,11 @@ copyright: Copyright &copy; 2023 The Enola <https://enola.dev> 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
Expand Down

0 comments on commit 195defb

Please sign in to comment.