From 8b907b5a60d26b66e9360efdac212b8ad49d5e13 Mon Sep 17 00:00:00 2001 From: Jon Ross-Perkins Date: Fri, 13 Mar 2026 17:50:58 -0700 Subject: [PATCH] Support octal literals (#6910) Support octal literals, mainly for migrating Unix file permissions. Reflects leads decision #6821. --- docs/design/README.md | 7 +- .../lexical_conventions/numeric_literals.md | 18 ++- proposals/p6910.md | 107 ++++++++++++++++++ 3 files changed, 123 insertions(+), 9 deletions(-) create mode 100644 proposals/p6910.md diff --git a/docs/design/README.md b/docs/design/README.md index 4110e3fe3399..83858511afa2 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -515,15 +515,16 @@ may be limited to integers of at most 128 bits due to LLVM limitations. #### Integer literals -Integers may be written in decimal, hexadecimal, or binary: +Integers may be written in decimal, hexadecimal, octal, or binary: - `12345` (decimal) - `0x1FE` (hexadecimal) +- `0o755` (octal) - `0b1010` (binary) Underscores (`_`) may be used as digit separators. Numeric literals are -case-sensitive: `0x`, `0b` must be lowercase, whereas hexadecimal digits must be -uppercase. Integer literals never contain a `.`. +case-sensitive: `0x`, `0o`, `0b` must be lowercase, whereas hexadecimal digits +must be uppercase. Integer literals never contain a `.`. Unlike in C++, literals do not have a suffix to indicate their type. Instead, numeric literals have a type derived from their value, and can be diff --git a/docs/design/lexical_conventions/numeric_literals.md b/docs/design/lexical_conventions/numeric_literals.md index 0932de751b67..f708f497c73e 100644 --- a/docs/design/lexical_conventions/numeric_literals.md +++ b/docs/design/lexical_conventions/numeric_literals.md @@ -28,6 +28,7 @@ The following syntaxes are supported: - [Integer literals](#integer-literals) - `12345` (decimal) - `0x1FE` (hexadecimal) + - `0o755` (octal) - `0b1010` (binary) - [Real-number literals](#real-number-literals) - `123.456` (digits on both sides of the `.`) @@ -55,15 +56,16 @@ base. The available base specifiers and corresponding bases are: | Base specifier | Base | Digits | | -------------- | ---- | ------------------------ | | `b` | 2 | `0` and `1` | +| `o` | 8 | `0` ... `7` | | `x` | 16 | `0` ... `9`, `A` ... `F` | -The above table is case-sensitive. For example, `0b1` and `0x1A` are valid, and -`0B1`, `0X1A`, and `0x1a` are invalid. +The above table is case-sensitive. For example, `0b1`, `0o7`, and `0x1A` are +valid, and `0B1`, `0O7`, `0X1A`, and `0x1a` are invalid. A zero at the start of a literal can never be followed by another digit: either the literal is `0`, the `0` begins a base specifier, or the next character is a -decimal point (see below). No support is provided for octal literals, and any C -or C++ octal literal (other than `0`) is invalid in Carbon. +decimal point (see below). The `0o` prefix is used for octal literals; a C-style +`0755` octal is invalid in Carbon. ### Real-number literals @@ -111,8 +113,9 @@ example: - Decimal integers: `1_23_456_7890` - Hexadecimal integers: `0x7_F_FF_FFFF` -- Real-number literals: `2_147.48_3648e12_345` or `0x1_00CA.FE_F00Dp+2_4` +- Octal literals: `0o7_55` - Binary literals: `0b1_000_101_11` +- Real-number literals: `2_147.48_3648e12_345` or `0x1_00CA.FE_F00Dp+2_4` ## Divergence from other languages @@ -129,7 +132,7 @@ provides benefits directly in line with the goal that Carbon code should be That said, it still provides sufficient variations to address important use cases for the goal of not leaving room for a lower level language: -- Hexadecimal and binary integer literals. +- Hexadecimal, octal, and binary integer literals. - Scientific notation floating point literals. - Hexadecimal (scientific) floating point literals. @@ -145,6 +148,7 @@ cases for the goal of not leaving room for a lower level language: - [3-digit decimal groupings](/proposals/p1983.md#3-digit-decimal-groupings) - [2-digit or 4-digit hexadecimal digit groupings](/proposals/p1983.md#2-digit-or-4-digit-hexadecimal-digit-groupings) - [Disallow digit separators in fractions](/proposals/p1983.md#disallow-digit-separators-in-fractions) +- [No octal literals](/proposals/p6910.md#no-octal-literals) ## References @@ -154,3 +158,5 @@ cases for the goal of not leaving room for a lower level language: [#866: Allow ties in floating literals](https://github.com/carbon-language/carbon-lang/pull/866) - Proposal [#1983: Weaken digit separator placement rules](https://github.com/carbon-language/carbon-lang/pull/1983) +- Proposal + [#6910: Support octal literals](https://github.com/carbon-language/carbon-lang/pull/6910) diff --git a/proposals/p6910.md b/proposals/p6910.md new file mode 100644 index 000000000000..9b2245ae2333 --- /dev/null +++ b/proposals/p6910.md @@ -0,0 +1,107 @@ +# Support octal literals + + + +[Pull request](https://github.com/carbon-language/carbon-lang/pull/6910) + + + +## Table of contents + +- [Abstract](#abstract) +- [Problem](#problem) +- [Background](#background) +- [Proposal](#proposal) +- [Future work](#future-work) + - [File permissions API](#file-permissions-api) +- [Rationale](#rationale) +- [Alternatives considered](#alternatives-considered) + - [No octal literals](#no-octal-literals) + + + +## Abstract + +Support octal literals, mainly for migrating Unix file permissions. Reflects +leads decision +[#6821](https://github.com/carbon-language/carbon-lang/issues/6821). + +## Problem + +Carbon currently does not support octal numeric literals, because they're very +rare, as previously decided in proposal +[#143: Numeric literals](https://github.com/carbon-language/carbon-lang/pull/143). +However, as part of interoperability with POSIX file system calls such as +[`umask`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/umask.html), +we want an easy way to express octal file permissions. + +## Background + +Leads discussed support of octal literals in issue +[#6821: Support octal literals](https://github.com/carbon-language/carbon-lang/issues/6821). + +Unix file permissions written in octal are familiar to both programmers and +non-programmers who have experience administering Unix-like machines. For +example: + +- `chmod OCTAL-MODE FILE...` +- [POSIX `mode_t` values](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html), + including the argument to + [`umask`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/umask.html). + +However, they are are not likely to be readable to those unfamiliar with them, +nor are they very common in code. We also expect these to be the primary use of +octal numeric literals in Carbon. + +Given these issues, proposal #143 +[rejected octal literals](/proposals/p0143.md#octal-literals). Now, we're +testing interoperability of POSIX file system calls, and we are considering +octal literals as a potential solution. + +Proposal #143 [discussed the Carbon-style `0o` versus C++-style `0` prefix for +octal literals. The same logic still applies, so we will not address it here. + +## Proposal + +Introduce support for octal literals using the `0o` prefix (for example, +`0o755`), followed by one or more octal digits (`0-7`). This provides a very +simple lexical space for octal numbers, mapping clearly from C++ and building +consistently off the existing `0x...` syntax for hexadecimal and `0b...` syntax +for binary. + +## Future work + +### File permissions API + +We may still provide a file permissions API in Carbon, for example as part of a +`Core` file system API. This proposal takes no stance on what that API should +look like. The only decision being made right now is that supporting octal +literals is worthwhile for interoperability and migration. + +## Rationale + +This proposal effectively advances Carbon's goals by focusing on: + +- [Interoperability with and migration from existing C++ code](/docs/project/goals.md#interoperability-with-and-migration-from-existing-c-code): + Providing a direct counterpart for C++ octal literals simplifies the + migration of Unix file system code without needing to wait for a better file + permission API. +- [Code that is easy to read, understand, and write](/docs/project/goals.md#code-that-is-easy-to-read-understand-and-write): + The explicit `0o` prefix avoids the frequent confusion caused by C++'s + leading `0` syntax, while maintaining consistency with hex and binary + prefixes. +- [Software and language evolution](/docs/project/goals.md#software-and-language-evolution): + The `0o` octal literal syntax is consistent with other literals. We don't + expect it to hinder future language features. + +## Alternatives considered + +### No octal literals + +Proposal #143 rejected octal literals. The main argument was that they are +rarely used. However, the cost of octal literal syntax is low, and the benefit +for C++ interoperability and migration is enough that we should add them.