Commit Graph
60 Commits
Author SHA1 Message Date
Chandler Carruth 2047e08635 Update examples throughout the design for p7016 (#7200)
Also updates a few spots with some subtle aspects changed in
`lambdas.md` and `namespace_cleanliness.md`.

Assisted-by: Antigravity with Gemini
2026-05-13 18:42:55 +00:00
2d5e5e9692 Expression form basics (#5545)
This proposal introduces the concept of a _form_, which is a
generalization of
"type" that encompasses all of the information about an expression
that's
visible to the type system, including type and expression category.
Forms can be
composed into _tuple forms_ and _struct forms_, which lets us track the
categories of individual tuple and struct literal elements.

The proposal PR also adds `ref` bindings to the pattern matching
documentation,
but that is not part of the proposal itself; it's just bringing the
documentation
up to date with proposal
[#5434](https://github.com/carbon-language/carbon-lang/pull/5434).

---------

Co-authored-by: josh11b <15258583+josh11b@users.noreply.github.com>
Co-authored-by: Chandler Carruth <chandlerc@gmail.com>
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
Co-authored-by: Carbon Infra Bot <carbon-external-infra@google.com>
2026-02-10 17:44:50 +00:00
Geoff Romerandjosh11b e940cb72b6 Parse ref as operator (#6539)
This is the first step of implementing the guidance in #6342.

---------

Co-authored-by: josh11b <15258583+josh11b@users.noreply.github.com>
2025-12-30 19:18:34 +00:00
gleb 4370acd1bb Snippets update (#6204)
~~Added explanatory comment about math package usage~~
Changed Main() entry point to Run() as per design and toolchain

This small update of front page code snippets will add
explanatory comment to highlight that provided Carbon code
is  hypothetical and meant to show the look and feel of the language.

Also it delivers change of Main() to Run() to
highlight correct entry point for Carbon lang.
2025-10-17 13:09:46 +00:00
Calvin bd4d5805dd Replace addr with ref in design docs (#6141)
Updates the documentation under `docs/design/` to use `ref` instead of
`addr` after their removal in #5434. Care was taken to manually clean up
edge cases and, in a couple cases, surrounding text (see
3d72c49bb75c0f40ca7e8114b6a1369b941e1697). After this change, there are
no matches for `addr(?!ess)` in `docs/design/`.

Closes #6032
2025-10-06 18:44:24 +00:00
Geoff RomerandRichard Smith c713279a3d Keep design documents current (#5606)
Require language design proposals to either update the design documents
to
reflect the proposed changes, or add "TODO" comments to mark where those
changes
will be needed, with links back to the proposal. This is intended to
ensure that
the design documentation accurately informs readers about the current
language
design, without excessively burdening the proposal process.

---------

Co-authored-by: Richard Smith <richard@metafoo.co.uk>
2025-10-01 20:12:05 +00:00
Hitesh JoshiandHitesh Joshi 0166d8837c Update Documentation to use new expression terminology (#5890)
# Changes

## Terminology Updates
This PR updates documentation to align with the expression phase
terminology changes introduced in
[#2964](https://github.com/carbon-language/carbon-lang/pull/2964):

* **"symbolic value" → "symbolic constant"**: Updated all remaining
instances using find-and-replace

## Scope of Changes
* Focused on documentation that predates the July 2023 terminology
change
* Used git blame history to identify instances likely using the old
"constant" definition
* Manually reviewed each "constant" usage to distinguish between:
- New definition (unchanged): the broader category including symbolic
constants

Closes
[#5599](https://github.com/carbon-language/carbon-lang/issues/5599)

---------

Co-authored-by: Hitesh Joshi <hitesh@mitsu.care>
2025-09-30 20:15:55 +00:00
ac98870e67 ref parameters, arguments, returns and val returns (#5434)
- A parameter binding can be marked `ref` instead of `var` or the
default. It will bind to reference argument expressions in the caller
and produces a reference expression in the callee.
- Unlike pointers, a `ref` binding can't be rebound to a different
object.
- This replaces `addr`, and is not restricted to the `self` parameter.
- A `ref` binding, like a value binding, can't be used in fields of
classes or structs.
- When calling functions, arguments to non-`self` `ref` parameters are
also marked with `ref`.
- The return of a function can optionally be marked `ref`, `val`, or
`var`. These control the category of the call expression invoking the
function, and how the return expression is returned.
- These may be mixed for functions returning tuple or struct forms.
-   The address of a `ref` binding is `nocapture` and `noalias`.
- We mark parameters of a function that may be referenced by the return
value with `bound`.

---------

Co-authored-by: Josh L <josh11b@users.noreply.github.com>
Co-authored-by: Geoff Romer <gromer@google.com>
Co-authored-by: Chandler Carruth <chandlerc@gmail.com>
2025-08-01 17:43:41 +00:00
Richard Smith 11d5ee5f3e Add partial to the precedence diagram. (#5749)
Following the decision in #5010.
2025-06-30 22:44:54 +00:00
Jon Ross-Perkins 6966b1879d A few more mermaid newline fixes (#5752)
Akin to #5751, found in two other files.
2025-06-30 22:43:03 +00:00
Jon Ross-Perkins 72c3f8a6b5 Fix repeated newlines in expression mermaid (#5751)
A newline adds a br. The br tag is redundant, unless you really want two
newlines. Might stem from a mistake in #1089

We have a couple spots using br to keep text on a single line; changing
those for consistency.

Before:

![Screenshot 2025-06-30 at 1 01
51 PM](https://github.com/user-attachments/assets/29c16b0f-1180-4e91-a2f8-3889db4dd311)

After:

![Screenshot 2025-06-30 at 1 01
18 PM](https://github.com/user-attachments/assets/1b69356e-92b7-4db5-8e0d-9e838035a9f5)
2025-06-30 20:10:16 +00:00
Richard Smith bc952b1a4b Document numeric type literals in lexical conventions. (#4842)
Also improve the precision of some other nearby documentation.
2025-01-24 01:57:42 +00:00
c5b5d36e8b Change operator precedence (#4075)
Update the operator precedence to achieve a few goals:

-   Form operators into groups which behave similarly
- Make the group of operators ("top-level operators") that capture
everything to the right, like `if`...`then`...`else`, behave similarly
to the left, so that rearranging expressions won't change how they
group.
- Add the `where` operator, used to specify constraints on facet types,
to the precedence chart, to define how it interacts with other
operators.
- Make the operator precedence diagram prettier, so that it eventually
can be made into a poster that Carbon programmers can hang on their
walls.

---------

Co-authored-by: Josh L <josh11b@users.noreply.github.com>
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
2024-08-10 00:15:37 +00:00
4132c6a65f Merge the suffix ops into a single box in the operator precedence mermaid diagram (#4067)
The current approach was done to work-around a limitation that we can
only have a single link per box, but is unscalable. Instead have a
single link to a new sections of the document that describes the box,
and has multiple links.

---------

Co-authored-by: Josh L <josh11b@users.noreply.github.com>
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
2024-06-20 21:17:25 +00:00
74d7d49bcf Include function call and subscripting/indexing in the operator list and precedence chart (#4052)
Co-authored-by: Josh L <josh11b@users.noreply.github.com>
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
2024-06-17 22:19:02 +00:00
Richard Smith 6bbbd4ec1f More consistent package syntax (#3927)
Change the syntax for `package` declarations from:

```carbon
[package Foo] [library "bar"] api;
[package Foo] [library "bar"] impl;
```

to

```carbon
[package Foo] [library "bar"];
impl [package Foo] [library "bar"];
```
2024-05-16 00:55:37 +00:00
Richard Smith cb849cf165 Integrate description of tuple indexing into member access better. (#3679)
Improve the exposition of the design changes from #3646 to integrate
better into the overall description of member access design.

This fixes the incorrect description of the rules for `->` by instead
relying on the general rule that `->` is rewritten to use `*` and `.`
before any other processing is done, and generally makes
*integer-literal* names be less of a special case.
2024-02-03 08:40:03 +00:00
Richard Smith a1655b6858 Tuples and tuple indexing (#3646)
Add support for extracting elements of a tuple by their numerical index.

Also formally add the well-established basic syntactic and semantic
rules for
tuples, for which we have had leads issues but no proposal, into the
design.
2024-01-31 23:42:11 +00:00
josh11bandChandler Carruth 58c106010c Updates to design docs to reflect accepted proposals (#3254)
Includes proposals:
- #990
- #2188
- #2138
- #2200
- #2360
- #2760
- #2964
- #3162

Also tries to use more precise language when talking about:
- implementations, to avoid confusing `impl` declaration and definitions
with the `impls` operator used in `where` clauses, an issue brought up
in #2495 and #2483;
- "binding patterns", like `x: i32`, and "bindings" like `x`.

---------

Co-authored-by: Chandler Carruth <chandlerc@gmail.com>
2023-09-23 15:53:07 +00:00
josh11bandRichard Smith a8ca499450 Updates to generics design details, part 1 (#3231)
First step in updating `docs/design/generics/details.md`. It
incorporates changes from proposals: #989 #2138 #2173 #2200 #2360 #2964
#3162 , but there are still more changes from those proposals to be
made.

It also switches away from suggesting static-dispatch witness tables,
and creates an appendix to describe that decision.

---------

Co-authored-by: Richard Smith <richard@metafoo.co.uk>
2023-09-19 19:06:47 +00:00
josh11b dc394b6d95 Clarify some points in Member Access design (#3177)
Follow-on to #3160. Incorporates decision about template specialization
from #2200.
2023-09-06 22:23:52 +00:00
josh11bandRichard Smith d5d6945f85 Update member_access.md to reflect accepted proposals (#3160)
Most changes are due to proposal #2360, but this also includes changes
to reflect: #1136, #2138, #2006, #2550, and #2964.

---------

Co-authored-by: Richard Smith <richard@metafoo.co.uk>
2023-08-31 00:17:00 +00:00
josh11b 9600030a05 Reduce ambiguity in terminology (#3162)
Change terminology away from terms that are ambiguous:

- Reserve "generic type" for types with (compile-time) parameters, like
`Vector` in `Vector(T:! type)`. Don't use that term to refer to `T`, as
it would with
[#2360](https://github.com/carbon-language/carbon-lang/blob/trunk/proposals/p2360.md#terminology).
- Use the term "compile-time" instead of "constant" to mean "template or
symbolic." Expand the term "constant" to include values, such as from
`let` bindings.
2023-08-30 17:13:40 +00:00
Richard Smith 7b22173cba Add precedence rules for assignment operators to the precedence diagram. (#3083)
Also indicate what can appear within parentheses.

This is intended to be a clarification, not a design change. Note that
while we previously described the operand of `++` or `--` as being
simply an expression, the operand can never be anything other than the
kinds of expression the diagram now shows due to the expression category
rules added in #2006.

Fixes #3079.
2023-08-10 22:35:51 +00:00
Chandler Carruth 6d3a4b84cb Mark unary operators as repeating. (#3074)
Currently, they are marked as left-associative which isn't completely
obvious for unary operators and wouldn't match the fact that we have
both prefix and postfix unary operators we intend to allow to repeat
without parentheses: `***x` and `T***`.

This fixes the graph by making the left-associative marker only for
binary operators, and using a separate marker for repeating unary
operators: a diamond.

It also adds a note that Carbon currently only has left-associativity
because the right-associative operators like assignment are statements
in Carbon.

This isn't intended ta be a change of anything in Carbon's design, just
an improvement to the documentation.
2023-08-08 17:57:25 +00:00
0d1e6bd84d Values, variables, pointers, and references (#2006)
Introduce a concrete design for how Carbon values, objects, storage,
variables,
and pointers will work. This includes fleshing out the design for:

- The expression categories used in Carbon to represent values and
objects,
how they interact, and terminology that anchors on their expression
nature.
-   An expression category model for readonly, abstract values that can
    efficiently support function inputs.
- A customization system for value expression representations,
especially as
    seen on function boundaries in the calling convention.
- An expression category model for references instead of a type system
model.
-   How patterns match different expression categories.
-   How initialization works in conjunction with function returns.
- Specific pointer syntax, semantics, and library customization
mechanisms.
- A `const` type qualifier for use when the value expression category
system
    is too abstracted from the underlying objects in storage.

---------

Co-authored-by: Geoff Romer <gromer@google.com>
Co-authored-by: josh11b <josh11b@users.noreply.github.com>
Co-authored-by: Adrien Leravat <Pixep@users.noreply.github.com>
Co-authored-by: Jon Ross-Perkins <jperkins@google.com>
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
2023-08-08 07:27:44 +00:00
587ab64d1b Update Generics terminology document (#3048)
This reflects changes from a number of approved proposals:
- #920 : concrete statements about orphan and overlap in Carbon
- #2138 : "generic" -> "checked generic", "template" -> "template
generic"
- #2188 : binding patterns are forbidden in type position
- #2360 : "type", "facet type", "facet". Note: I am not using the term
"generic type" from #2360 since that meaning conflicts with the
generally accepted meaning of "generic type" of a type with a
compile-time parameter.
- #2760 / #2770 : internal/external impl -> extending impl
- #2964 : "symbolic constant" and "template constant"

---------

Co-authored-by: Geoff Romer <gromer@google.com>
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
2023-08-02 23:22:15 +00:00
josh11b 2ae8117d62 Update design docs with syntax changes from #2760 (#2866)
This includes:

- Syntax changes from this chart:

| Before                          | After                                   |
| ------------------------------- | --------------------------------------- |
| `class D extends B { ... }`     | `class D { extend base: B; ... }`       |
| `external impl C as Sub;`       | `impl C as Sub;`                        |
| `class C { impl as Sortable; }` | `class C { extend impl as Sortable; }`  |
| `adapter A for C { ... }`       | `class A { adapt C; ... }`              |
| `adapter A extends C { ... }`   | `class A { extend adapt C; ... }`       |
| `interface I { impl as J; }`    | `interface I { require Self impls J; }` |
| `interface I { extends J; }`    | `interface I { extend J; }`             |

- Dropping the syntax for conditionally implemented internal interfaces.

This does not include:

- terminology changes from #2760 ("internal" and "external")
- changes to code, such as explorer, toolchain, language grammars, or other tooling
2023-06-16 14:22:29 -07:00
642fcd3b77 Replace keyword is with impls (#2483)
Use the keyword `impls` instead of `is` when writing a `where` constraint that a type variable needs to implement an interface or named constraint.

What was previously (provisionally) written:
```
fn Sort[T:! Container where .ElementType is Ordered](x: T*);
```
will now be written:
```
fn Sort[T:! Container where .ElementType impls Ordered](x: T*);
```

---------

Co-authored-by: Geoff Romer <gromer@google.com>
Co-authored-by: Chandler Carruth <chandlerc@gmail.com>
2023-03-22 21:45:32 -07:00
Aadarsh Raj 76b274b136 fixing word for greater and greater than equal symbol from comparison_operators doc (#2662)
### Greater symbol issue in doc file of comparison_operators

In doc, symbol of greater or greater than equal is write but word is miswritten  
so i just fix the word which is miswritten.
2023-03-09 08:26:46 -08:00
Avi Aaron 0a70614235 replace me with self 2nd try (#2631)
this is a second try after PR 2629,
I restarted from scratch since most changes were undone.
2023-02-23 21:54:45 -08:00
a89aba2698 Assignment statements (#2511)
Assignment is permitted only as a complete statement, not as a subexpression.
Assignment and compound assignment syntax follow C++ in all other respects.
Pre-increment is provided. Post-increment is not. Uses of all of these operators
are translated into calls to interface members.

Co-authored-by: Jon Ross-Perkins <jperkins@google.com>
Co-authored-by: Chandler Carruth <chandlerc@gmail.com>
2023-01-27 19:03:47 -08:00
Richard Smith 4daaa4866f Rename Type -> type, per #2360. (#2507)
Also make minor updates to the skeletal design in
docs/design/name_lookup.md following #2113, as there are no longer any prelude names that are made available to unqualified name lookup by default.

Add `type` to the keyword list in
docs/design/lexical_conventions/words.md, following #2360.
2023-01-04 14:22:30 -08:00
Jon Ross-Perkins c5f4e65fdd Add parentheses to remove ambiguity for %. (#2478) 2022-12-20 17:51:05 -08:00
josh11b 8e29547911 Move numeric_literals.md design doc into expressions/literals.md and update (#2459)
Follow-on to change #2410 which created the `expressions/literals.md` home for literal expressions. Incorporates the decision in #2113 to address a TODO.
2022-12-13 16:31:02 -08:00
Geoff Romer 0bf4d11ced Design documentation for indexing (#2388)
Update the design documentation to reflect #2274.

The contents are largely copy-pasted from p2274.md with minor edits, but the "Open questions" section is new.
2022-12-10 01:25:04 -08:00
dd2f7d732c Design updates for #2015 numeric type literal syntax (#2410)
Edit numeric literal design for the literal type proposal and add reference where #2015 was mentioned.

Closes #2159 

Co-authored-by: Richard Smith <richard@metafoo.co.uk>
Co-authored-by: josh11b <josh11b@users.noreply.github.com>
2022-12-09 11:01:21 -08:00
josh11b 9c8fd6864e Implement rename me -> self (#2444)
Implements change proposed in #1382

Replaces #1624
2022-12-06 20:17:00 -08:00
Richard Smith dca7214c25 Update design to use current impl syntax. (#2309) 2022-10-24 14:16:41 -07:00
josh11b 14206da00a Primitive types (#1975)
A few changes:
- Merge content from the `primitive_types.md` design doc into the overall design `README.md` since there was so much overlap and no need for two copies.
- Consistently spell integer types `Carbon.Int(N)` and `Carbon.UInt(N)`, including the `Carbon.` prefix and avoiding `Unsigned(N)`.
- Consistently use a comprehensive set of floating-point types.
- Incorporates #2015 into the design docs.
2022-09-08 18:13:09 -07:00
Ryan Russell aa4ce80907 docs(design): improve readability (#1431)
Readability improvements focused on `docs/design/.md`

Signed-off-by: Ryan Russell <git@ryanrussell.org>
2022-07-19 17:45:45 -04:00
josh11b eed666f0d4 Fix interface extends syntax (#1383) 2022-07-12 10:14:32 -07:00
Richard Smith d2b33a712f Fix missing backtick (#1235) 2022-05-06 20:56:16 -07:00
Richard SmithandChandler Carruth c4fecf720f Bitwise operators (#1191)
Add bitwise and bit-shift operators `&`, `|`, `^`, `<<`, `>>`. Replace C++ `~` with unary prefix `^`.

Co-authored-by: Chandler Carruth <chandlerc@gmail.com>
2022-05-06 14:26:55 -07:00
Richard SmithandChandler Carruth 4a8ca9cd0f Rework operator interfaces (#1178)
Add concrete design for interfaces for comparison.

Rename interfaces for arithmetic following current thinking in #1058.

Update rules for mixed-type comparisons for data classes following #710.

Co-authored-by: Chandler Carruth <chandlerc@gmail.com>
2022-05-03 15:37:45 -07:00
770279e02d Arithmetic expressions (#1083)
Add support for arithmetic operators:

- Unary `+`.
- Binary `+`, `-`, `*`, `/`, `%`.

Specify their behavior for integer and floating-point types. Signed integer overflow is a programming error, handled in various ways. Unsigned integer overflow is specified as wrapping around, intended for hashing / crypto / PRNG use cases.

Co-authored-by: jonmeow <46229924+jonmeow@users.noreply.github.com>
Co-authored-by: Chandler Carruth <chandlerc@gmail.com>
Co-authored-by: josh11b <josh11b@users.noreply.github.com>
2022-03-24 17:51:17 -07:00
Richard Smith 9384077abd Direct/indirect member access -> simple/compound member access. (#1119)
Plus some minor fixups to improve the readability and precision of the
summary in README.md.
2022-03-10 13:36:12 -08:00
josh11b 81c5eef3b8 Fix copy-paste error (#1123) 2022-03-08 10:15:24 -08:00
Richard Smithandjosh11b 18b423dc5f Member access expressions (#989)
Support for member access expressions with syntax `container.member`, covering cases such as:

* `object.field`
* `object.method(args)`
* `package.namespace.class.member`
* `object.(interface.member)`
* `object.(class.member)`

... and so on. Includes the rule for template name lookup as decided in #949.

Co-authored-by: josh11b <josh11b@users.noreply.github.com>
2022-03-02 13:01:01 -08:00
Jon MeowandRichard Smith fae7f0d007 Refining the precedence chart with if, struct literals, and links. (#1089)
This is intended to be a more iterative edit to the chart:

- Adding `if` and struct literals, since it came up in arithmetic.
- Adding links to address a comment of mine about wanting references
- Rephrasing slightly to reduce the implication that it's only for operators (particularly since I don't think we want to call `if` an operator)
- Shifting operators below because similar 

Co-authored-by: Richard Smith <richard@metafoo.co.uk>
2022-02-24 18:00:55 -08:00