1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
/*
* Copyright 2022 Weavers @ Eternal Loom. All rights reserved.
* Use of this software is governed by the license that can be
* found in LICENSE file in the source repository.
*/
//! _Metals_ is a meta programming language for building composable systems.
//!
//! It is a library that provides the meta programming language environment
//! for domain modeling and schema management to compose complex systems from
//! simpler components.
//!
//! ## About Domains and Modeling in Computation
//!
//! A domain is a field or an area under investigation. In a computational
//! context, we are interested in developing computational models of domains
//! in the real world and use these models to build solutions to the problems
//! at hand.
//!
//! _Modeling or model development_ is the first step in any project. They are
//! essential to communication among stakeholders and used throughout the
//! development process. They may be formal or informal, documented or not,
//! explicit or implicit.
//!
//! The power of models essentially decides the type of problems we can
//! address and the quality of our solutions.
//!
//! ## Key Ideas
//!
//! The domain modeling capabilities and the required meta programming support
//! within _metals_ are based on the following key ideas.
//! - __Simple models, complex domains:__ _Models based on simple rules can
//! exhibit complex behavior._
//! Ability to model domains of arbitrary complexity does not necessarily mean
//! that the models have to be unreasonably complex as well. We strive to
//! promote simple models throughout.
//!
//! - __Compositional models:__ _Complex models are compositionally built from
//! simpler ones._
//! It is our fundamental belief that the compositionality of our mental models
//! underlie the extraordinary human cognitive capabilities.
//!
//! - __Context Aware Computing:__ _Next to compositionality, context awareness
//! or mode dependent computation is the most important aspect of the
//! computational models supported by _metals_._
//! This is especially important in the context of distributed, heterogeneous
//! computing environments. The models are not used by a single system or
//! environment as we traditionally assume when we build computational models.
//!
//! - __Combinatorial generalization:__ _the ability to learn increasingly
//! complex concepts by synthesizing simple ideas, enabling both rapid learning
//! and adaptation of knowledge_
//!
//! ### Our goals
//!
//! The modeling capabilities provided by _metals_ shall meet the following
//! goals.
//!
//! - __Enable Communication:__ _The models should serve as the communication
//! medium between different teams, especially with domain experts._
//! We shall not expect any programming expertize from the domain experts or other
//! teams outside of the development or engineering teams, nor shall we want
//! the developers to leave their tools of choice and familiarity to
//! build communication models.
//!
//! - __Modeling Data and Behaviors:__ _The models should be able to represent
//! both data and their associated behaviors._ The compositionality and
//! combinatorial generalization shall apply to both data and behaviors.
//!
//! - __Executable models:__ _The models should be executable._
//! It should be possible to convert the models developed through collaborative
//! modeling process to executable artifacts with minimal effort.
//!
//! - __Make Illegal States Unrepresentable:__ _The models should be able to
//! capture the domain constraints explicitly and make all illegal states
//! unrepresentable._
//! The models should fully and faithfully represent the domain constraints so
//! that they can serve as a single source of truth about accuracy our
//! requirements and the subsequent implementation.
//!
//! - __Uniform Structured representations:__ _The modeling language shall
//! support structured representations that can be used across heterogeneous
//! environments._
//! The models should be able to provide uniform view of the domain across
//! many boundaries that exists in the development and runtime environments
//! such as programming languages, frameworks, platforms, networks, etc.
//!
//! - __Lazy Evaluation and Transparency:__ _A state represented in the
//! model shall be evaluated lazily in a location transparent way._
//! When one models a domain, the domain objects represent data that eventually
//! resolve to appropriate values, not necessarily eagerly computed. For example,
//! when one refers to a _User_ in the model, it could be an object that is
//! returned by a network call or a database query. The models should be able
//! hide such details. The transparency also means that the model builders are
//! not burdened by idiosyncrasies such as different query semantics,
//! implementation details and access protocols of the underlying systems or
//! environment.
//!
//! - __Distributed and Independently Evolving Models:__ _Building a uniform
//! model for a given application does not necessarily mean a single
//! global model._
//! Global models are complex to build and a nightmare to maintain. Our goal
//! is to support smaller, distributed models that can evolve independently.
//! An application (or solution) context will be able import the relevant models
//! and create a unified view of the domain as it pertains to that
//! application.
//!
//! ## Organization
//!
//! The _metals_ library is organized into the following set of packages or
//! libraries (crates).
//!
//! - [`metals`]: This library (current crate) brings the overall functionality
//! together.
//! - [`metals-poly`]: Poly library provides the interface and interface type
//! abstractions that form the foundations of the meta programming.
//!
//! ## Metals book
//!
//! The [metals book][`metals-book`] contains introduction to modeling,
//! guides for modeling with [`metals`] and deeper dive into technical and
//! mathematical background.
//!
//! Please note that this is still work in progress.
//!
//! [`metals`]: https://docs.rs/metals/
//! [`metals-book`]: https://metals.compos.dev
//! [`metals-poly`]: https://docs.rs/metals-poly/