@swiftbrowser/swift 0.1.0 → 0.3.0

package/Sources/FoundationBridge/Markdown.swift

@@ -0,0 +1,527 @@
+// `AttributedString(markdown:options:baseURL:)`, which swift-foundation has
+// only on Apple platforms. It parses Markdown's inline syntax, as CommonMark
+// and GitHub define it, into the attributes Apple's parser sets:
+//
+// - `inlinePresentationIntent`: emphasis (`*a*`, `_a_`), strong emphasis
+//   (`**a**`, `__a__`), code spans (`` `a` ``), strikethrough (`~a~`, `~~a~~`)
+//   and hard line breaks;
+// - `link`, from `[text](url "title")` and `<scheme:…>` autolinks;
+// - `imageURL`, from `![alt](url)`, on the alt text (EmojiText marks its
+//   custom emoji this way).
+//
+// Backslash escapes and HTML entities are decoded. Block syntax is not
+// interpreted. With `.full`, blank lines separate paragraphs, and the
+// paragraphs are concatenated, as Apple's parser does when it sets no block
+// attributes. `.inlineOnly` turns line breaks into spaces;
+// `.inlineOnlyPreservingWhitespace` keeps the text's whitespace as it is.
+// Parsing never fails, so the initializer never throws.
+
+import Foundation
+
+/// How a run of text is presented inline: Markdown's emphasis, code and the like.
+public struct InlinePresentationIntent: OptionSet, Hashable, Codable, Sendable {
+    public let rawValue: UInt
+    public init(rawValue: UInt) { self.rawValue = rawValue }
+
+    public static let emphasized = InlinePresentationIntent(rawValue: 1 << 0)
+    public static let stronglyEmphasized = InlinePresentationIntent(rawValue: 1 << 1)
+    public static let code = InlinePresentationIntent(rawValue: 1 << 2)
+    public static let strikethrough = InlinePresentationIntent(rawValue: 1 << 5)
+    public static let softBreak = InlinePresentationIntent(rawValue: 1 << 6)
+    public static let lineBreak = InlinePresentationIntent(rawValue: 1 << 7)
+    public static let inlineHTML = InlinePresentationIntent(rawValue: 1 << 8)
+    public static let blockHTML = InlinePresentationIntent(rawValue: 1 << 9)
+}
+
+extension AttributeScopes.FoundationAttributes {
+    /// Markdown's inline presentation (`run.inlinePresentationIntent`).
+    public enum InlinePresentationIntentAttribute: CodableAttributedStringKey {
+        public typealias Value = InlinePresentationIntent
+        public static let name = "NSInlinePresentationIntent"
+    }
+
+    /// For `attributedString.inlinePresentationIntent`: like the scope's own
+    /// attributes, the key path names the key and its value is never read.
+    public var inlinePresentationIntent: InlinePresentationIntentAttribute { fatalError("an attribute key path is never read") }
+}
+
+extension AttributedString {
+    public struct MarkdownParsingOptions: Hashable, Sendable {
+        public enum InterpretedSyntax: Hashable, Sendable {
+            case full
+            case inlineOnly
+            case inlineOnlyPreservingWhitespace
+        }
+
+        public enum FailurePolicy: Hashable, Sendable {
+            case throwError
+            case returnPartiallyParsedIfPossible
+        }
+
+        public var allowsExtendedAttributes: Bool
+        public var interpretedSyntax: InterpretedSyntax
+        public var failurePolicy: FailurePolicy
+        public var languageCode: String?
+        public var appliesSourcePositionAttributes: Bool
+
+        public init(allowsExtendedAttributes: Bool = false, interpretedSyntax: InterpretedSyntax = .full,
+                    failurePolicy: FailurePolicy = .throwError, languageCode: String? = nil,
+                    appliesSourcePositionAttributes: Bool = false) {
+            self.allowsExtendedAttributes = allowsExtendedAttributes
+            self.interpretedSyntax = interpretedSyntax
+            self.failurePolicy = failurePolicy
+            self.languageCode = languageCode
+            self.appliesSourcePositionAttributes = appliesSourcePositionAttributes
+        }
+    }
+
+    public init(markdown: String, options: MarkdownParsingOptions = .init(), baseURL: URL? = nil) throws {
+        self.init()
+        for segment in _MarkdownInline.segments(of: markdown, syntax: options.interpretedSyntax) {
+            var piece = AttributedString(segment.text)
+            if !segment.intent.isEmpty { piece[AttributeScopes.FoundationAttributes.InlinePresentationIntentAttribute.self] = segment.intent }
+            if let link = segment.link { piece.link = Self._url(link, relativeTo: baseURL) }
+            if let image = segment.image { piece.imageURL = Self._url(image, relativeTo: baseURL) }
+            self.append(piece)
+        }
+    }
+
+    public init(markdown: Data, options: MarkdownParsingOptions = .init(), baseURL: URL? = nil) throws {
+        try self.init(markdown: String(decoding: markdown, as: UTF8.self), options: options, baseURL: baseURL)
+    }
+
+    static func _url(_ string: String, relativeTo base: URL?) -> URL? {
+        if let url = URL(string: string, relativeTo: base) { return url }
+        let encoded = string.addingPercentEncoding(withAllowedCharacters: .urlFragmentAllowed.union(.urlPathAllowed).union(CharacterSet(charactersIn: "?#:/")))
+        return encoded.flatMap { URL(string: $0, relativeTo: base) }
+    }
+}
+
+/// Markdown's inline syntax, parsed into runs of text with their presentation.
+enum _MarkdownInline {
+    struct Segment: Equatable {
+        var text: String
+        var intent: InlinePresentationIntent = []
+        var link: String?
+        var image: String?
+    }
+
+    indirect enum Node: Equatable {
+        case text(String)
+        case code(String)
+        case lineBreak
+        case styled(InlinePresentationIntent, [Node])
+        case link(String, [Node])
+        case image(String, [Node])
+    }
+
+    static func segments(of markdown: String, syntax: AttributedString.MarkdownParsingOptions.InterpretedSyntax) -> [Segment] {
+        var source = markdown.replacingOccurrences(of: "\r\n", with: "\n")
+        switch syntax {
+        case .inlineOnlyPreservingWhitespace:
+            return merge(flatten(parse(source, keepWhitespace: true)))
+        case .inlineOnly:
+            return merge(flatten(parse(source, keepWhitespace: false)))
+        case .full:
+            // Paragraphs: runs of lines between blank lines, concatenated.
+            if source.hasSuffix("\n") { source.removeLast() }
+            var paragraphs: [String] = []
+            var current: [Substring] = []
+            for line in source.split(separator: "\n", omittingEmptySubsequences: false) {
+                if line.allSatisfy({ $0 == " " || $0 == "\t" }) {
+                    if !current.isEmpty { paragraphs.append(current.joined(separator: "\n")) }
+                    current = []
+                } else {
+                    current.append(line)
+                }
+            }
+            if !current.isEmpty { paragraphs.append(current.joined(separator: "\n")) }
+            return merge(paragraphs.flatMap { flatten(parse($0, keepWhitespace: false)) })
+        }
+    }
+
+    // MARK: Flattening
+
+    static func flatten(_ nodes: [Node], intent: InlinePresentationIntent = [], link: String? = nil, image: String? = nil) -> [Segment] {
+        nodes.flatMap { node -> [Segment] in
+            switch node {
+            case .text(let text): [Segment(text: text, intent: intent, link: link, image: image)]
+            case .code(let text): [Segment(text: text, intent: intent.union(.code), link: link, image: image)]
+            case .lineBreak: [Segment(text: "\n", intent: intent.union(.lineBreak), link: link, image: image)]
+            case .styled(let style, let children): flatten(children, intent: intent.union(style), link: link, image: image)
+            case .link(let url, let children): flatten(children, intent: intent, link: url, image: image)
+            case .image(let url, let children): flatten(children, intent: intent, link: link, image: url)
+            }
+        }
+    }
+
+    /// Joins neighbors with the same attributes, and drops empty ones.
+    static func merge(_ segments: [Segment]) -> [Segment] {
+        var out: [Segment] = []
+        for segment in segments where !segment.text.isEmpty {
+            if var last = out.last, last.intent == segment.intent, last.link == segment.link, last.image == segment.image {
+                last.text += segment.text
+                out[out.count - 1] = last
+            } else {
+                out.append(segment)
+            }
+        }
+        return out
+    }
+
+    // MARK: Parsing
+
+    /// A piece of the inline content while it is parsed: finished nodes, and
+    /// the delimiters that may yet open or close emphasis or a link.
+    enum Piece {
+        case node(Node)
+        case delimiter(Delimiter)
+    }
+
+    struct Delimiter {
+        var char: Character
+        var count: Int
+        var originalCount: Int
+        var canOpen: Bool
+        var canClose: Bool
+        /// `[` or `![`: a link or image opener.
+        var isBracket: Bool { char == "[" || char == "!" }
+        var active = true
+
+        var literal: String { char == "!" ? "![" : String(repeating: char, count: count) }
+    }
+
+    static let punctuation = Set("!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~")
+
+    static func isPunctuation(_ c: Character?) -> Bool {
+        guard let c else { return false }
+        return punctuation.contains(c) || c.unicodeScalars.allSatisfy { CharacterSet.punctuationCharacters.contains($0) || CharacterSet.symbols.contains($0) }
+    }
+
+    static func isWhitespace(_ c: Character?) -> Bool {
+        guard let c else { return true }
+        return c.isWhitespace
+    }
+
+    static func parse(_ source: String, keepWhitespace: Bool) -> [Node] {
+        let chars = Array(source)
+        var pieces: [Piece] = []
+        var text = ""
+        var i = 0
+
+        func flushText() {
+            if !text.isEmpty { pieces.append(.node(.text(text))); text = "" }
+        }
+
+        while i < chars.count {
+            let c = chars[i]
+            switch c {
+            case "\\":
+                if i + 1 < chars.count, chars[i + 1] == "\n" {
+                    flushText()
+                    pieces.append(.node(.lineBreak))
+                    i += 2
+                } else if i + 1 < chars.count, punctuation.contains(chars[i + 1]) {
+                    text.append(chars[i + 1])
+                    i += 2
+                } else {
+                    text.append(c)
+                    i += 1
+                }
+            case "`":
+                var run = 0
+                while i + run < chars.count, chars[i + run] == "`" { run += 1 }
+                if let end = closingBackticks(chars, from: i + run, count: run) {
+                    flushText()
+                    var code = String(chars[(i + run)..<end]).replacingOccurrences(of: "\n", with: " ")
+                    if code.count >= 2, code.first == " ", code.last == " ", !code.allSatisfy({ $0 == " " }) {
+                        code = String(code.dropFirst().dropLast())
+                    }
+                    pieces.append(.node(.code(code)))
+                    i = end + run
+                } else {
+                    text += String(repeating: "`", count: run)
+                    i += run
+                }
+            case "*", "_", "~":
+                var run = 0
+                while i + run < chars.count, chars[i + run] == c { run += 1 }
+                let before: Character? = i > 0 ? chars[i - 1] : nil
+                let after: Character? = i + run < chars.count ? chars[i + run] : nil
+                let leftFlanking = !isWhitespace(after) && (!isPunctuation(after) || isWhitespace(before) || isPunctuation(before))
+                let rightFlanking = !isWhitespace(before) && (!isPunctuation(before) || isWhitespace(after) || isPunctuation(after))
+                var canOpen = leftFlanking
+                var canClose = rightFlanking
+                if c == "_" {
+                    canOpen = leftFlanking && (!rightFlanking || isPunctuation(before))
+                    canClose = rightFlanking && (!leftFlanking || isPunctuation(after))
+                }
+                if c == "~" && run > 2 {
+                    text += String(repeating: "~", count: run)
+                } else {
+                    flushText()
+                    pieces.append(.delimiter(Delimiter(char: c, count: run, originalCount: run, canOpen: canOpen, canClose: canClose)))
+                }
+                i += run
+            case "!" where i + 1 < chars.count && chars[i + 1] == "[":
+                flushText()
+                pieces.append(.delimiter(Delimiter(char: "!", count: 1, originalCount: 1, canOpen: true, canClose: false)))
+                i += 2
+            case "[":
+                flushText()
+                pieces.append(.delimiter(Delimiter(char: "[", count: 1, originalCount: 1, canOpen: true, canClose: false)))
+                i += 1
+            case "]":
+                flushText()
+                if let next = closeBracket(&pieces, chars, after: i + 1) {
+                    i = next
+                } else {
+                    text.append("]")
+                    i += 1
+                }
+            case "<":
+                if let (url, end) = autolink(chars, from: i) {
+                    flushText()
+                    pieces.append(.node(.link(url, [.text(url.hasPrefix("mailto:") && !String(chars[(i + 1)..<end]).hasPrefix("mailto:") ? String(url.dropFirst(7)) : String(chars[(i + 1)..<end]))])))
+                    i = end + 1
+                } else {
+                    text.append(c)
+                    i += 1
+                }
+            case "&":
+                if let (decoded, end) = entity(chars, from: i) {
+                    text += decoded
+                    i = end
+                } else {
+                    text.append(c)
+                    i += 1
+                }
+            case "\n":
+                // Two or more spaces before a line break make a hard break.
+                if text.hasSuffix("  ") {
+                    while text.hasSuffix(" ") { text.removeLast() }
+                    flushText()
+                    pieces.append(.node(.lineBreak))
+                } else if keepWhitespace {
+                    text.append("\n")
+                } else {
+                    while text.hasSuffix(" ") { text.removeLast() }
+                    text.append(" ")
+                }
+                i += 1
+                if !keepWhitespace { while i < chars.count, chars[i] == " " { i += 1 } }
+            default:
+                text.append(c)
+                i += 1
+            }
+        }
+        flushText()
+        processEmphasis(&pieces, from: 0)
+        return nodes(of: pieces)
+    }
+
+    /// The pieces as nodes, with delimiters that matched nothing as text.
+    static func nodes(of pieces: some Collection<Piece>) -> [Node] {
+        var out: [Node] = []
+        for piece in pieces {
+            let node: Node
+            switch piece {
+            case .node(let n): node = n
+            case .delimiter(let d): node = .text(d.literal)
+            }
+            if case .text(let new) = node, case .text(let old)? = out.last {
+                out[out.count - 1] = .text(old + new)
+            } else {
+                out.append(node)
+            }
+        }
+        return out
+    }
+
+    static func closingBackticks(_ chars: [Character], from start: Int, count: Int) -> Int? {
+        var j = start
+        while j < chars.count {
+            if chars[j] == "`" {
+                var run = 0
+                while j + run < chars.count, chars[j + run] == "`" { run += 1 }
+                if run == count { return j }
+                j += run
+            } else {
+                j += 1
+            }
+        }
+        return nil
+    }
+
+    /// `]` after a `[` or `![` opener: when `(destination "title")` follows,
+    /// the pieces since the opener become a link or image.
+    static func closeBracket(_ pieces: inout [Piece], _ chars: [Character], after start: Int) -> Int? {
+        guard let openerIndex = pieces.lastIndex(where: { if case .delimiter(let d) = $0 { return d.isBracket }; return false }),
+              case .delimiter(let opener) = pieces[openerIndex] else { return nil }
+        guard opener.active, let (destination, end) = inlineDestination(chars, from: start) else {
+            // Not a link: the opener is literal text.
+            pieces[openerIndex] = .node(.text(opener.literal))
+            return nil
+        }
+        processEmphasis(&pieces, from: openerIndex + 1)
+        let children = nodes(of: pieces[(openerIndex + 1)...])
+        pieces.removeSubrange(openerIndex...)
+        if opener.char == "!" {
+            pieces.append(.node(.image(destination, children)))
+        } else {
+            pieces.append(.node(.link(destination, children)))
+            // No links inside links: earlier openers can no longer make one.
+            for index in pieces.indices {
+                if case .delimiter(var d) = pieces[index], d.char == "[" {
+                    d.active = false
+                    pieces[index] = .delimiter(d)
+                }
+            }
+        }
+        return end
+    }
+
+    /// `(destination "title")` at `start`: the destination and the index after `)`.
+    static func inlineDestination(_ chars: [Character], from start: Int) -> (String, Int)? {
+        guard start < chars.count, chars[start] == "(" else { return nil }
+        var j = start + 1
+        func skipSpaces() { while j < chars.count, chars[j] == " " || chars[j] == "\n" || chars[j] == "\t" { j += 1 } }
+        skipSpaces()
+        var destination = ""
+        if j < chars.count, chars[j] == "<" {
+            j += 1
+            while j < chars.count, chars[j] != ">" {
+                if chars[j] == "\n" || chars[j] == "<" { return nil }
+                if chars[j] == "\\", j + 1 < chars.count, punctuation.contains(chars[j + 1]) { j += 1 }
+                destination.append(chars[j])
+                j += 1
+            }
+            guard j < chars.count else { return nil }
+            j += 1
+        } else {
+            var depth = 0
+            while j < chars.count {
+                let c = chars[j]
+                if c == " " || c == "\n" || c == "\t" { break }
+                if c == "(" { depth += 1 }
+                if c == ")" {
+                    if depth == 0 { break }
+                    depth -= 1
+                }
+                if c == "\\", j + 1 < chars.count, punctuation.contains(chars[j + 1]) {
+                    j += 1
+                }
+                destination.append(chars[j])
+                j += 1
+            }
+        }
+        skipSpaces()
+        if j < chars.count, chars[j] == "\"" || chars[j] == "'" || chars[j] == "(" {
+            let close: Character = chars[j] == "(" ? ")" : chars[j]
+            j += 1
+            while j < chars.count, chars[j] != close { j += 1 }
+            guard j < chars.count else { return nil }
+            j += 1
+            skipSpaces()
+        }
+        guard j < chars.count, chars[j] == ")" else { return nil }
+        return (destination, j + 1)
+    }
+
+    /// `<scheme:…>` or `<user@host>`: the URL and the index of `>`.
+    static func autolink(_ chars: [Character], from start: Int) -> (String, Int)? {
+        var j = start + 1
+        var body = ""
+        while j < chars.count, chars[j] != ">" {
+            if chars[j] == " " || chars[j] == "<" || chars[j] == "\n" { return nil }
+            body.append(chars[j])
+            j += 1
+        }
+        guard j < chars.count else { return nil }
+        if let colon = body.firstIndex(of: ":") {
+            let scheme = body[..<colon]
+            guard (2...32).contains(scheme.count), scheme.first!.isLetter,
+                  scheme.allSatisfy({ $0.isLetter || $0.isNumber || $0 == "+" || $0 == "." || $0 == "-" }) else { return nil }
+            return (body, j)
+        }
+        if body.contains("@"), !body.hasPrefix("@"), !body.hasSuffix("@") { return ("mailto:" + body, j) }
+        return nil
+    }
+
+    static let namedEntities: [String: String] = [
+        "amp": "&", "lt": "<", "gt": ">", "quot": "\"", "apos": "'", "nbsp": "\u{00A0}",
+        "hellip": "…", "mdash": "—", "ndash": "–", "lsquo": "‘", "rsquo": "’", "ldquo": "“", "rdquo": "”",
+        "copy": "©", "reg": "®", "trade": "™", "middot": "·", "bull": "•", "laquo": "«", "raquo": "»",
+    ]
+
+    /// `&name;`, `&#123;` or `&#x1F600;` at `start`: the decoded text and the index after `;`.
+    static func entity(_ chars: [Character], from start: Int) -> (String, Int)? {
+        guard let semicolon = chars[start...].prefix(34).firstIndex(of: ";"), semicolon > start + 1 else { return nil }
+        let body = String(chars[(start + 1)..<semicolon])
+        if body.hasPrefix("#x") || body.hasPrefix("#X") {
+            guard let code = UInt32(body.dropFirst(2), radix: 16), let scalar = Unicode.Scalar(code), code != 0 else { return nil }
+            return (String(Character(scalar)), semicolon + 1)
+        }
+        if body.hasPrefix("#") {
+            guard let code = UInt32(body.dropFirst()), let scalar = Unicode.Scalar(code), code != 0 else { return nil }
+            return (String(Character(scalar)), semicolon + 1)
+        }
+        guard let decoded = namedEntities[body] else { return nil }
+        return (decoded, semicolon + 1)
+    }
+
+    /// CommonMark's emphasis algorithm over the pieces from `bottom` on: each
+    /// closer, left to right, matches the nearest opener of its kind, and
+    /// what lies between becomes emphasized (or struck through).
+    static func processEmphasis(_ pieces: inout [Piece], from bottom: Int) {
+        var closerIndex = bottom
+        while closerIndex < pieces.count {
+            guard case .delimiter(var closer) = pieces[closerIndex], !closer.isBracket, closer.canClose else {
+                closerIndex += 1
+                continue
+            }
+            var openerIndex: Int?
+            var j = closerIndex - 1
+            while j >= bottom {
+                if case .delimiter(let opener) = pieces[j], opener.char == closer.char, opener.canOpen {
+                    let matches: Bool
+                    if closer.char == "~" {
+                        matches = opener.count == closer.count
+                    } else if (opener.canClose || closer.canOpen),
+                              (opener.originalCount + closer.originalCount) % 3 == 0,
+                              !(opener.originalCount % 3 == 0 && closer.originalCount % 3 == 0) {
+                        matches = false
+                    } else {
+                        matches = true
+                    }
+                    if matches { openerIndex = j; break }
+                }
+                j -= 1
+            }
+            guard let openerIndex, case .delimiter(var opener) = pieces[openerIndex] else {
+                closerIndex += 1
+                continue
+            }
+            let used: Int
+            let style: InlinePresentationIntent
+            if closer.char == "~" {
+                used = closer.count
+                style = .strikethrough
+            } else {
+                used = opener.count >= 2 && closer.count >= 2 ? 2 : 1
+                style = used == 2 ? .stronglyEmphasized : .emphasized
+            }
+            let inner = nodes(of: pieces[(openerIndex + 1)..<closerIndex])
+            opener.count -= used
+            closer.count -= used
+            var replacement: [Piece] = []
+            if opener.count > 0 { replacement.append(.delimiter(opener)) }
+            replacement.append(.node(.styled(style, inner)))
+            let styledIndex = openerIndex + replacement.count - 1
+            if closer.count > 0 { replacement.append(.delimiter(closer)) }
+            pieces.replaceSubrange(openerIndex...closerIndex, with: replacement)
+            // A closer with some left over is next again; otherwise the piece after the run.
+            closerIndex = styledIndex + 1
+        }
+    }
+}

package/Sources/FoundationBridge/MeasurementFormat.swift

@@ -0,0 +1,95 @@
+// `Measurement.formatted()` and `Measurement.FormatStyle`, which corelibs
+// Foundation lacks: the value as `Double.formatted()` writes it, then the
+// unit's symbol ("57°F", "5 km"). A temperature in the general or weather
+// usage is converted to the locale's unit first (Fahrenheit in the United
+// States and the few regions that use it, Celsius elsewhere), as Apple's
+// does; other units are written in their own. Units are written as symbols
+// at every width.
+
+import Foundation
+
+extension Measurement {
+    public struct FormatStyle: Foundation.FormatStyle, Hashable, Sendable {
+        public struct UnitWidth: Codable, Hashable, Sendable {
+            let name: String
+            public static var wide: UnitWidth { UnitWidth(name: "wide") }
+            public static var abbreviated: UnitWidth { UnitWidth(name: "abbreviated") }
+            public static var narrow: UnitWidth { UnitWidth(name: "narrow") }
+        }
+
+        public var width: UnitWidth
+        public var locale: Locale
+        /// Whether a temperature is converted to the locale's unit.
+        var convertsTemperature: Bool
+
+        public init(width: UnitWidth = .abbreviated, locale: Locale = .autoupdatingCurrent) {
+            self.width = width
+            self.locale = locale
+            convertsTemperature = true
+        }
+
+        public func locale(_ locale: Locale) -> Self {
+            var copy = self
+            copy.locale = locale
+            return copy
+        }
+
+        public func format(_ measurement: Measurement<UnitType>) -> String {
+            var value = measurement.value
+            var symbol = measurement.unit.symbol
+            if convertsTemperature, let temperature = measurement as? Measurement<UnitTemperature> {
+                let unit: UnitTemperature = Self.usesFahrenheit(locale) ? .fahrenheit : .celsius
+                let converted = temperature.converted(to: unit)
+                value = converted.value
+                symbol = unit.symbol
+            }
+            let number = value.formatted()
+            // Temperatures and angles hug their number, as in "21°C".
+            let hugs = symbol.hasPrefix("°") || symbol == "%" || symbol == "′" || symbol == "″"
+            return hugs ? number + symbol : number + " " + symbol
+        }
+
+        static func usesFahrenheit(_ locale: Locale) -> Bool {
+            ["US", "LR", "MM", "BS", "BZ", "KY", "PW", "FM", "MH"].contains(locale.region?.identifier ?? "US")
+        }
+    }
+
+    /// The measurement in the locale's style (see the top of the file).
+    public func formatted() -> String {
+        FormatStyle().format(self)
+    }
+
+    public func formatted<S: Foundation.FormatStyle>(_ style: S) -> S.FormatOutput where S.FormatInput == Measurement<UnitType> {
+        style.format(self)
+    }
+}
+
+extension Measurement.FormatStyle where UnitType == UnitTemperature {
+    /// How a temperature is used: in the general and weather usages it is
+    /// converted to the locale's unit; `asProvided` keeps its own.
+    public struct Usage: Codable, Hashable, Sendable {
+        let converts: Bool
+        public static var general: Usage { Usage(converts: true) }
+        public static var weather: Usage { Usage(converts: true) }
+        public static var person: Usage { Usage(converts: true) }
+        public static var asProvided: Usage { Usage(converts: false) }
+    }
+
+    public init(width: UnitWidth = .abbreviated, locale: Locale = .autoupdatingCurrent, usage: Usage) {
+        self.init(width: width, locale: locale)
+        convertsTemperature = usage.converts
+    }
+}
+
+extension Foundation.FormatStyle {
+    public static func measurement<UnitType: Dimension>(width: Measurement<UnitType>.FormatStyle.UnitWidth = .abbreviated) -> Self
+    where Self == Measurement<UnitType>.FormatStyle {
+        Measurement<UnitType>.FormatStyle(width: width)
+    }
+
+    public static func measurement(width: Measurement<UnitTemperature>.FormatStyle.UnitWidth = .abbreviated,
+                                   usage: Measurement<UnitTemperature>.FormatStyle.Usage) -> Self
+    where Self == Measurement<UnitTemperature>.FormatStyle {
+        Measurement<UnitTemperature>.FormatStyle(width: width, usage: usage)
+    }
+}