You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: OVERVIEW.md
+67-26Lines changed: 67 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ In this way, Bauble is a format very useful for specifying information processed
5
5
6
6
Once a context has been created, that context can then be used for parsing various Bauble source files and extracting the newly parsed data back as typed values that can be used to update the state of the program.
7
7
8
-
# BaubleContext
8
+
# `BaubleContext`
9
9
10
10
[`BaubleContext`] is used to register various Bauble source files to parse information from, as well as maintaining a type registry where every known type to Bauble is provided.
11
11
Through [`BaubleContext`], various separate Bauble source files are able to reference each other's objects.
@@ -52,34 +52,63 @@ Whether the conversion is successful depends on the implementation of the [`Baub
52
52
In order to support all Bauble values being parsed and represented as a single type in Rust, using type erasure is a possibility, however it has to be manually implemented.
53
53
For example, a single `ErasedBauble` type which can represent any type that implements `Bauble`, but has to be explicitly downcast to the concrete type sometime later at runtime (when the type is known).
54
54
55
-
##Bauble overview
55
+
# Bauble overview
56
56
57
-
# Includes (use)
57
+
##Includes (use)
58
58
59
59
All Bauble source files support the usage of `use`.
60
60
Similar to Rust, it may include any item defined from a separate Bauble module, as long as both modules (the module being used, and the module using) exist within the same [`BaubleContext`].
61
61
Alternatively to `use`, like in Rust, the fully qualified path may be written out instead.
62
62
`use` may be used to include both objects and Bauble registered types/traits.
63
63
64
-
# Object
64
+
##Object
65
65
66
66
All bauble source files consists of a set of objets.
67
67
A single Bauble object is a tree of Bauble values and a type.
68
68
A Bauble object can be thought of as a single asset, being tied to a unique path.
69
69
Objects are the format of its contents Bauble provides after it has parsed all of its files, and ultimately what is used to convery the parsed Bauble contents.
70
70
71
-
#Values
71
+
### Object terminology
72
72
73
-
A value in Bauble is typed, and contains an enum representing the kind of the value (whether it is a number, a string, an array or a map for example).
73
+
There are three kinds of Bauble objects. Top level, local, and inline. These can be seen
74
+
represented in the [`ObjectPath`] enum.
75
+
76
+
A top level (or Top for short) object is the main kind of object. A single source file has a single
77
+
top level object which appears at the start of the file with the `0` identifier used as its name
78
+
(NOTE: completely empty files are also allowed). These objects have the same path as their
79
+
containing file. Top objects can be freely referenced by objects in other files. They can also be
80
+
referenced in the current file both by their full path and by the special `0` identifier.
81
+
82
+
Local objects are the remaining named objects in a file that appear after the top object. They can
83
+
only be referenced by other objects in the same file and only via their name rather than a full
84
+
path.
85
+
86
+
An inline object is a reference value within a Bauble object which is not written as a reference in
87
+
the source (see [References](#references)). Instead they appear as an "inlined" object directly
88
+
defined together with the object. Functionally, inline objects work similar to a regular reference
89
+
with the difference being they are defined locally to the object where they are used and are not
90
+
named separately referencable objects themselves. They act as a convenience for the alternative of
91
+
defining and referencing a separate object. The paths of these objects are generated based on the
92
+
parent object when loading a Bauble file.
93
+
94
+
In addition to referencing other Bauble objects, external assets can be referenced. These are
95
+
assets that aren't bauble files. For example, an audio or image asset. They can be exposed to be
96
+
referenced by bauble values via `BaubleContext::register_asset`. When an object references an
97
+
external asset it uses `ObjectPath::Top` wrapping the path provided to `register_asset `. When
98
+
something can be either a Bauble object or an external asset, we use the term "asset".
99
+
100
+
## Values
101
+
102
+
A value in Bauble is typed, and contains an enum representing the kind of the value (whether it is a number, a string, an array or a map for example).
74
103
Values are not that usually interacted with by the end user, as generally Bauble is implemented through the derive macro which means the user does not need to handle parsing from a raw Bauble value themselves.
75
104
76
-
# Types
105
+
##Types
77
106
78
107
Types are registered to the [`BaubleContext`] through the builder, and every type requires the [`Bauble`] trait to be implemented on top of it.
79
108
The [`Bauble`] trait determines how the type gets registered into the [`BaubleContext`], how it is parsed from Bauble source, and what path the type has.
80
109
In Bauble every object is associated with a type, the type may be explicitly written with the value or implied by context, similar to type inference rules in Rust.
81
110
82
-
# Traits
111
+
##Traits
83
112
84
113
Traits may be registered to Bauble in the form of `dyn Trait` types.
85
114
If a trait has been registered, `dyn Trait` can then be used within registered Bauble types. In order for Bauble to parse a value of type `dyn Trait` with a value of a type that implements `Trait` called `T`, both `Trait` the `T` must be registered, and Bauble must know `T` implements `Trait`.
@@ -88,30 +117,42 @@ Bauble is unable to use reflection and figure out if a type implements a trait b
88
117
In order to register Bauble traits, you can use the method [`get_or_register_trait`](types::TypeRegistry::get_or_register_trait), then in order to mark a type as implementing that trait in Bauble,
89
118
use [`add_trait_dependency`](types::TypeRegistry::add_trait_dependency)
90
119
91
-
# Modules
120
+
## Modules
121
+
122
+
Every registered source file in Bauble is a module, similar to Rust. Every module contains various objects. The notion of sub-modules are not really present in Bauble.
123
+
124
+
## Paths
92
125
93
-
Every registered source file in Bauble is a module, similar to Rust. Every module contains various assets. The notion of sub-modules are not really present in Bauble.
126
+
Every asset, module, reference and registered type/trait in Bauble has a corresponding unique path.
127
+
In Bauble this is known as [`path::TypePath`], and is the association to that particular element in
128
+
the [`BaubleContext`].
129
+
A path consists of various elements. Similar to Rust, most elements are seperated by `::`, so
130
+
`a::b` means element `b` which is a child of element `a`.
131
+
An element here can be a module, type, object, or external asset.
94
132
95
-
# Paths
133
+
References to Objects use [`object_path::ObjectPath`] which is an enum that augments
134
+
[`path::TypePath`] with information about the kind of object. Note, local and inline objects are
135
+
not known to the `BaubleContext` so referring to top objects in the `BaubleContext` just uses
136
+
`TypePath`.
96
137
97
-
Every asset, module, reference and registered type/trait in Bauble has a corresponding unique path. In Bauble this is known as [`path::TypePath`], and is the association to that particular element in the [`BaubleContext`].
98
-
A path consists of various elements. Similar to Rust, most elements are seperated by `::`, so `a::b` means element `b` which is a child of element `a`.
99
-
An element here can be a module, type or object.
100
-
There are things known as sub-objects which may be appended to the path of a regular object, which are effectively children of the current object.
101
-
A sub-object's path is denoted by `<path to parent>&$ty@$idx` where `$ty` is the index of the type of the sub-object and `$idx` is the index of the sub-object to the parent (the first sub-oject being 0, the second 1, the third 2, etc).
138
+
There are objects known as inline objects which are effectively children of the current object.
139
+
Their paths are constructed by appending to the name of a regular object to create a new object
140
+
path with a different name that shares the same path prefix.
141
+
An inline object's path is denoted by `<path to parent>&$ty@$num` where `$ty` ID of the type of the
142
+
inline object and `$num` is an aribtrary number that distinguishes different inline objects with
143
+
the same parent (usually starting at 0).
102
144
103
-
# References
145
+
##References
104
146
105
-
A reference is a Bauble object which may not be present in the current module.
106
-
A Bauble object's value may use a reference to avoid code duplication in the local file (referencing a previous object to use its values), or to reference the value of a Bauble object from a different file (module).
147
+
A reference is a value that points to another Bauble object or a registered external asset.
148
+
A Bauble object's value may use a reference to avoid code duplication in the local file
149
+
(referencing a previous object to use its values), or to reference the value of a Bauble object
150
+
from a different file (module).
107
151
References are specified using a bauble `Path`.
108
152
109
-
Bauble does expose the builtin type for references, [`Ref`], which can be used for convenience to represent references from Bauble in Rust.
110
-
It is not required to use this type to represent references, custom types which are capable of parsing reference values are equal to the builtin [`Ref`] type, it is just a convenience.
153
+
Bauble does expose the builtin type for references, [`Ref`], which can be used for convenience to
154
+
represent references from Bauble in Rust.
155
+
It is not required to use this type to represent references, custom types which are capable of
156
+
parsing reference values are equal to the builtin [`Ref`] type, it is just a convenience.
111
157
112
-
# Sub-objects
113
158
114
-
A single Bauble object may contain sub-objects.
115
-
A sub-object is a reference value within a Bauble object which is not written as a reference, and rather as an "inlined" object directly defined together with the object.
116
-
Functionally sub-objects work similar to a regular reference with the difference being they are defined locally to the object where they are used and are not
0 commit comments