Support octal literals (#6910)

Support octal literals, mainly for migrating Unix file permissions.
Reflects leads decision #6821.

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

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)

proposals/p6910.md

@@ -0,0 +1,107 @@
+# Support octal literals
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+[Pull request](https://github.com/carbon-language/carbon-lang/pull/6910)
+
+<!-- toc -->
+
+## 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)
+
+<!-- tocstop -->
+
+## 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.