-
Notifications
You must be signed in to change notification settings - Fork 1.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
An incomplete, early, and in-progress overview of the language design. #22
Conversation
This is basically a snapshot of an in-progress document, moved to markdown and prepared for sharing with the wider community. It isn't finished. It isn't even necessarily up to date with the latest thinking on any particular area. But I think it will make more sense to land it as essentially a collective WIP and let people iterate on any given section as those details get sorted out. Even in its current form, I think it still provides a starting point and gives people the feel of what this will look like. There are a number of document links lost in this conversion. I've carefully left a `TODO` in the document at each point to come back and add the appropriate link back to the document once the rest of the existing material is somewhere visible. These were all fairly easy to preserve as they primarily were links out to an entire document.
I think this is in a state where folks can start reading it and discussing. A couple of points on discussion here though... The big one: on any specific topic, please try to keep discussion fairly light and high-level. I'll try to add some rough notes about major high-level concerns, but it is easy to become swamped in those. This is not intended to propose any particular set of details as the path forward, only to collect a high level picture (even if stale & inaccurate from time to time). The right place to dig into details, or really push on any specific direction is through a detailed proposal in that area. I am especially interested if there are major improvements people would like to see in the overall organization. So far, I've not loved any of the organization, but this one seems at least "OK" for now. But if there are concrete suggestions for ways to structure that would be better, I'd love to hear ideas and discuss them. Also interested in better ways to phrase and word the top-level introduction to best convey the nature and purpose of the document -- serving as an overview and index across the design space, not pushing any one area forward with "this is how it should be". |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't want to get into an extended debate here, but I thought making an attempt to make the document a bit more accurate would be beneficial. I think it would be reasonable to just delete sections that we know are inaccurate until later if you want to get this in quickly.
> **Note**: this implies that other names within your own package but not | ||
> declared within the file must be found via the package name. It isn't clear if | ||
> this is the desirable end state. We need to consider alternatives where names | ||
> from the same module or any module in the same package are made immediately |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When you say "module" here do you mean the "library" you defined above?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, good catch.
Carbon also disallows the use of shadowed unqualified names, but not the | ||
_declaration_ of shadowing names in different named scopes. Because all |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I did not follow this -- perhaps an example would make it clearer?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done.
that adding names to the standard library or importing a new package (both of | ||
which bring new names into the current package's scope) doesn't force renaming |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This bit about adding names to a package that is imported adds names to the package's scope doesn't sound consistent with what you said before, nor consistent with how I expect/want things to work.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Tried to make this more clear in the example, but let me know if it still isn't clear.
That said, I'm not really trying to endorse this. I'm happy removing a bunch of this if you want -- I mostly think it is interesting to consider the underlying ideas of restricting shadowing by limiting unqualified name lookup and falling back to qualified name lookup.
- Bitwise: `2 & 3`, `2 | 4`, `3 ^ 1`, `1 << 3`, `8 >> 1`, `~7` | ||
- Relational: `2 == 2`, `3 != 4`, `5 < 6`, `7 > 6`, `8 <= 8`, `8 >= 8` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- Bitwise: `2 & 3`, `2 | 4`, `3 ^ 1`, `1 << 3`, `8 >> 1`, `~7` | |
- Relational: `2 == 2`, `3 != 4`, `5 < 6`, `7 > 6`, `8 <= 8`, `8 >= 8` | |
- Bitwise: `2 & 3`, `2 | 4`, `3 ^ 1`, `1 << 3`, `8 >> 1`, `~7` | |
- Relational: `2 == 2`, `3 != 4`, `5 < 6`, `7 > 6`, `8 <= 8`, `8 >= 8` |
I've noticed this is an issue with our docs-to-markdown exporter.
should cast or convert the argument to control the deduction. The explicit type | ||
is passed after a runtime parameter. While this makes that type unavailable to | ||
the declaration of the runtime parameter, it still is a true type and available | ||
to use as a type even within the remaining parts of the template function | ||
declaration. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I suspect these last sentences are talking about something that is no longer relevant.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I just think I was using really bad words. Anyways, rewritten to be I think somewhat more clear.
> **Note**: there is an important open question about how to distinguish between | ||
> a non-type parameter of a template function which is a normal runtime | ||
> parameter and one which must trigger instantiation and become available in the | ||
> function as a compile time constant. Currently, the most appealing technique | ||
> is an annotation of the parameter itself, but we still don't have a very | ||
> appealing suggestion for how to spell this annotation without making the | ||
> declaration excessively verbose. An alternative would be to give up on the | ||
> single-parameter sequence and require the template parameters to be separate | ||
> so the above becomes `template fn Convert[Type: T](Type: U)(T: source) -> U` | ||
> and the call becomes `Convert(Float)(i)`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also out of date.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Deleted.
> **TODO:** Update all of this to match the generics proposal when we have a | ||
> draft published, and link to it. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would be much more comfortable omitting these sections until they can be rewritten than including them as-is.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We discussed this offline a bit... I agree that the sections don't currently make much sense, just representing very dated and not coherent idle speculation... However, I also feel like there is some minimal value here to help people begin thinking outside of the C++ constrnucts of templates and inheritance, and to provide some common syntax primitives around interfaces that can be useful in examples and other discussions.
I'm currently rewritting the entire section to both be much more minimal while still giving some flavor of the directions we're exploring here. I'll update again when I have new text here for a fresh look and then let's see if we can arrive at something that still provides this "flavor" level value without ending up misleading.
be the only non-whitespace on the line. Carbon also supports a nestable block | ||
comment syntax: | ||
|
||
``` | ||
/* | ||
... | ||
/* | ||
... | ||
*/ | ||
... | ||
*/ | ||
``` | ||
|
||
While these use the block comment syntax of C and C++, they allow nesting much | ||
like with Swift. The opening (`/*`) and closing (`*/`) are required to be the | ||
first and last (respectively) thing on the line. Both of these comment styles |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd just delete this bit about /* ... */ for now. Including it and then having notes about them maybe not actually being included is too much detail for an overview document like this, which has a lot to cover, and any place we can shorten will be beneficial.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sure, tried to shorten up a bit.
a local variable named `p` which is then returned. | ||
|
||
### Pattern matching as function overload resolution | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add TODO
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done.
Co-authored-by: Jon Meow <46229924+jonmeow@users.noreply.github.com> Co-authored-by: josh11b <josh11b@users.noreply.github.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
First off, thanks for the thorough review. =D
I think I got through all of the comments left and responded. I'll make a second pass to double check and mark all the ones that seem definitive as "resolved" tomorrow.
Appreciate not going too far down the debate path here. I think there are really two areas with substantial issues:
- Tuples (especially w.r.t. function calls)
- Generics (and templates, etc)
For 2, I've got a pretty clear idea of what might both be a more useful and much more up-to-date and accurate summary for generics. I've deleted most of the egregious text and left some TODOs, I plan to fill that in before landing though, I just didn't want to wait on finishing that text to send out the rest of my updates. The template sections I was able to pretty quickly update to something plausible (or at least, they may be plausible once I address my TODOs to give the introduction section that ties them together).
For 1, I've responded inline and tried to re-focus the text in the document on the more useful (and I think less interesting / difficult / uncertain (to me) aspects. It still isn't perfect, and I've tried to make sure there are at least very explicit notes about the uncertainty here. Unsure if this is really enough in the way of disclaimer to avoid confusion, but at least for me it seems pretty close. Happy to iterate here until we find something that strikes a reasonable balance though.
be the only non-whitespace on the line. Carbon also supports a nestable block | ||
comment syntax: | ||
|
||
``` | ||
/* | ||
... | ||
/* | ||
... | ||
*/ | ||
... | ||
*/ | ||
``` | ||
|
||
While these use the block comment syntax of C and C++, they allow nesting much | ||
like with Swift. The opening (`/*`) and closing (`*/`) are required to be the | ||
first and last (respectively) thing on the line. Both of these comment styles |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sure, tried to shorten up a bit.
We'll get into more detail about what these mean and how they all work as we go | ||
along. | ||
|
||
### Basic names and scopes |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good call, added a section and restructured a bit so it fits.
> **Note**: this implies that other names within your own package but not | ||
> declared within the file must be found via the package name. It isn't clear if | ||
> this is the desirable end state. We need to consider alternatives where names | ||
> from the same module or any module in the same package are made immediately |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, good catch.
and run-time parameters. | ||
|
||
``` | ||
template fn Convert[Type: T](T: source, Type: U) -> U { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done and entire section rewritten. Similar to above, this references as-yet-unwritten high level ideas that are common such as implicit parameters. Will add that as I get the generics bit fleshed out and then need to make sure this lines up coherently. But it is at least much less actively wrong/misleading.
should cast or convert the argument to control the deduction. The explicit type | ||
is passed after a runtime parameter. While this makes that type unavailable to | ||
the declaration of the runtime parameter, it still is a true type and available | ||
to use as a type even within the remaining parts of the template function | ||
declaration. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I just think I was using really bad words. Anyways, rewritten to be I think somewhat more clear.
> **Note**: there is an important open question about how to distinguish between | ||
> a non-type parameter of a template function which is a normal runtime | ||
> parameter and one which must trigger instantiation and become available in the | ||
> function as a compile time constant. Currently, the most appealing technique | ||
> is an annotation of the parameter itself, but we still don't have a very | ||
> appealing suggestion for how to spell this annotation without making the | ||
> declaration excessively verbose. An alternative would be to give up on the | ||
> single-parameter sequence and require the template parameters to be separate | ||
> so the above becomes `template fn Convert[Type: T](Type: U)(T: source) -> U` | ||
> and the call becomes `Convert(Float)(i)`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Deleted.
#### Specialization | ||
|
||
An important feature of templates in C++ is the ability to customize how they | ||
end up specialized for specific types. Carbon also supports this for templates: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yes, lemme just say that too....
#### Specialization | ||
|
||
An important feature of templates in C++ is the ability to customize how they | ||
end up specialized for specific types. Carbon also supports this for templates: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also tried to clarify that by leveraging pattern matching there is potentially more going on here. The only hting I want to really be concrete about though is that this gives us a potential integrated way to get extremely comparable facilities to what C++ provides so we know we're covering that space.
import Shadow library OtherLib; | ||
|
||
// We can reference the imported library: | ||
alias ??? OtherLibType = Shadow.SomeType; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
alias ??? OtherLibType = Shadow.SomeType; | |
alias ??? OtherLibType = OtherLib.Shadow.SomeType; |
I'm a bit confused here, isn't "Shadow" here unqualified, and thus an error? Shouldn't this require OtherLib.Shadow.SomeType?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this whole example (and possibly idea?) is just broken, and so I'm deleting all of it. We shouldn't figure out how this does work here, that should be in the naming proposal. I'll think more about what we really want around shadowing and try again in that doc! =D
with parentheses to have clear and distinct syntax and match both the common | ||
case (multiple parameters) and common convention in programming languages around | ||
function notation. `Int*` `Int*?` `Int[]` | ||
Generally, functions pattern match a single tuple value of the arguments (with |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Broad comment -- I was digging and the dev style guide strongly discourages use of parentheticals, you might want to go through removing uses.
https://developers.google.com/style/parentheses
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a good point, I'm going through and trying to clean up my use of them. It's a long standing habit, so apologies when I inevitable regress, but definitely keep calling it out.
I think there are some uses that (as the guide says) are OK when judiciously used... but long parentheticals like this seem clearly better written differently. =]
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Replying to the new comments from Jon as I work on these and some other updates.
import Shadow library OtherLib; | ||
|
||
// We can reference the imported library: | ||
alias ??? OtherLibType = Shadow.SomeType; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this whole example (and possibly idea?) is just broken, and so I'm deleting all of it. We shouldn't figure out how this does work here, that should be in the naming proposal. I'll think more about what we really want around shadowing and try again in that doc! =D
with parentheses to have clear and distinct syntax and match both the common | ||
case (multiple parameters) and common convention in programming languages around | ||
function notation. `Int*` `Int*?` `Int[]` | ||
Generally, functions pattern match a single tuple value of the arguments (with |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a good point, I'm going through and trying to clean up my use of them. It's a long standing habit, so apologies when I inevitable regress, but definitely keep calling it out.
I think there are some uses that (as the guide says) are OK when judiciously used... but long parentheticals like this seem clearly better written differently. =]
|
||
Our current proposed naming convention, which we at least are attempting to | ||
follow within Carbon documentation in order to keep code samples as consistent | ||
as possible: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
as possible: | |
as possible, is: |
|
||
- `UpperCamelCase` for names of compile-time resolved constants, such that they | ||
can participate in the type system and type checking of the program. | ||
- `lower_snake_case` for names of run-time resolved values. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is it worth mentioning here that we intend to use lower_snake_case
for keywords too?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, and highlight (ba-dum) that syntax highlighting helps those stand out on their own, and why. I'll make a suggestion on Jon's new structure.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actually, this seems better handled in the lexical conventions. This section is about the naming conventions within identifiers, and I feel like bringing up keywords is likely to just be confusing.
> **Note**: this implies that other names within your own package but not | ||
> declared within the file must be found via the package name. It isn't clear if | ||
> this is the desirable end state. We need to consider alternatives where names | ||
> from the same library or any library in the same package are made immediately | ||
> visible within the package scope for unqualified name lookup. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When deciding what to do here, we should think about whether we want to support compilation at a finer granularity than package-at-a-time. We have evidence that the Rust crate-at-a-time compilation model results in compilation performance problems.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agreed. Not sure there is anything we can say this early though?
Because all unqualified name lookup is locally controlled, shadowing isn't | ||
needed for robustness and is a long and painful source of bugs over time. | ||
Disallowing it provides simple, predictable rules for name lookup. However, it | ||
is important that adding names to the standard library or importing a new | ||
package (both of which bring new names into the current package's scope) doesn't | ||
force renaming interfaces that may have many users. To accomplish this, we allow | ||
code to declare shadowing names, but references to that name must be qualified. | ||
For package-scope names, this can be done with an explicit use of the current | ||
package name: `PackageName.ShadowingName`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is adding a new name to the prelude a breaking change? (Would you need to update all existing code to stop using that name as an unqualified identifier first, before upgrading?) Perhaps we could give names from the prelude the same treatment that #17 suggests for keywords: if you declare them anywhere in a file, you don't get to use them with their built-in meaning in that file.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm OK with adding a new name being a breaking change exactly as much as I'm OK with adding keywords being a breaking change. =] And I'm also happy finding similar mechanisms to allow people to handle the fallout in sustainable ways, as long as neither one stops progress of adding keywords when justified. =D Anyways, probably best to handle it in #17 rather than here.
``` | ||
std::int64_t Sum(std::int64_t a, std::int64_t b); | ||
|
||
// Or with the new trailing return type syntax: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
// Or with the new trailing return type syntax: | |
// Or with trailing return type syntax: |
(It's not all that new any more.)
package MyProgram library Entry; | ||
|
||
fn Run() -> Bool { | ||
Print("Hello World!"); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This isn't the right place for this comment, but: I view Carbon as being a language for writing code at scale, where you probably don't want to use Print
and would instead want some domain-specific output mechanism; therefore, I don't think it should be visible by default in Carbon source files -- I think people should be required to think at least a little bit before using it. That said, I think
-
We should be able to support the kinds of small utilities where
Print
is useful. Putting a bunch of such functionality into some standard library "tool utilities" package seems like a good idea. -
Being able to print out a debugging string is certainly useful, and it might be reasonable to make functionality for that be available by default.
> **TODO:** Need a comprehensive design document to underpin these, and then | ||
> link to it here. | ||
|
||
These types are fundamental to the language as they aren't comprised of other |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These types are fundamental to the language as they aren't comprised of other | |
These types are fundamental to the language as they aren't formed from other |
> should be defined in Carbon code rather than special. Clearly they can't be | ||
> directly implemented w/o help, but it might still be useful to force the | ||
> programmer-observed interface to reside in code. However, this can cause |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not certain that we can't implement many of these types directly without help. For example, I could imagine allowing a direct implementation of Type
for a given value, that allows Carbon code to specify layout properties of a type. There are circularity problems to deal with (eg, what is the return type of Type.Size
?) but perhaps we could cut that cycle somewhere that's invisible to Carbon programs.
that is not available as part of the type system would be named `n`, even if it | ||
happened to be immutable or only take on a single value. Functions and most | ||
types will be in `UpperCamelCase`, but a type where only run-time type | ||
information queries are available would end up as `lower_snake_case`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How does this apply to generic arguments to a function, which are compile-time constants at the call site but not within the function body? This explanation makes it sound like they should be lowercase, since you can't use them in compile-time-only contexts, but most of the examples I've seen use uppercase.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't really follow, I think the generic examples are using the types as compile-time constants...
fn GenericF[SomeInterface:$ GenericT](GenericT: value) -> Void
Here, GenericT
is used in a compile time context -- it is part of the parameter declaration?
> explicit types or other questions in this space). That was a very limited PhD | ||
> student's study of Java programmers that seemed to indicate improved latency | ||
> for recalling the type of a given variable name with types on the left (as in | ||
> C++). However, those results are _far_ from conclusive. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If you're looking for data points on how people respond to this syntax: this tripped me up in your presentation when I tried to read example Carbon code for the first time, and it continues to trip me up over a month later. Literally every other language I know of that uses this syntax does it in the other order.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yep, this is a point that I think folks are very much thinking about. Happy to talk more in depth about this at some point if you want, but probably this doc isn't the best place.
@jonmeow has what I think is a really nice (but different) structured approach in #83 that I much prefer, and so I'm closing this PR out in favor of his for now. I've tried to respond to some of the questions here. I think most of the immediate adjustments suggested have been reflected in #83, but if anyone sees one that got missed, I'll try to keep following this thread just-in-case. |
#83) Co-authored by: chandlerc - Based on [PR 22](#83) - [Idea topic](https://forums.carbon-lang.dev/t/proposal-for-an-incomplete-rough-high-level-overview-ready-for-early-feedback/52) - [RFC](https://forums.carbon-lang.dev/t/rfc-an-incomplete-early-and-in-progress-overview-of-the-language-design/73) - [Decision announcement](https://forums.carbon-lang.dev/t/accepted-an-incomplete-early-and-in-progress-overview-of-the-language-design/110) This proposal should be considered a starting point of the language design. It's not intended to be final; language details may change. This is intended to offer a reasonable starting point for: - Example code. - Conceptualizing Carbon at a high level. - Reasonable, but not necessarily final, approaches to features in README.md. - If any idea is obviously bad, we can clean it up here. This proposal is not intended to achieve: - A whole language design. - This is way too much work for a single proposal; this is a skeletal framework only. - As we work on feature-specific designs, we may decide to use other approaches. That's fine: we only need somewhere to start. - The summaries in README.md may be expected to change over time. - Feature-specific files aren't intended to be well-written or comprehensive. They are a quick jot of prior thoughts. - We want to avoid getting stuck on language details that we should consider more carefully regardless. If you're passionate about a feature, please feel free to start a new proposal for it. - Each and every aspect of the suggested overview should be subject to careful examination and justification before it becomes a settled plan of record. Chandler started this with #22. I've taken it over with the following changes: - More of a directory hierarchy. - Trying to thin out the main file (now README.md) to lighter summaries of features. - Details/rationale/alternatives should be in feature-specific files. - Draft files are linked as references where added. For an example of how we may proceed with feature-specific designs, see #80. In this structure: - docs/design/README.md mentions interoperability, with a light overview. - The light overview is not yet in #80. - docs/design/interoperability/README.md goes into more depth on interoperability, covering key points of the approach. - Individual files in docs/design/interoperability/* go into more depth on interoperability. Simple designs may not have a subdirectory. All current feature-specific designs do not -- they may be moved later.
This is basically a snapshot of an in-progress document, moved to
markdown and prepared for sharing with the wider community. It isn't
finished. It isn't even ready for full review yet. Some specific changes
that I'm planning to make:
structure is somewhat outdated and I have better ideas about how to
organize these things.
thinking. While to an extent this is inevitable, I'd like to clean at
least a few of them up.
However, as is I think it still provides a starting point and gives
people the feel of what this will look like.
There are a number of document links lost in this conversion. I've
carefully left a
TODO
in the document at each point to come back andadd the appropriate link back to the document once the rest of the
existing material is somewhere visible.
Fixes #18.