blob: b6a9b693fa9f2933b4be400fc0651a1fa57a2ee0 [file]
/-
Copyright (c) 2025 Lean FRO, LLC. All rights reserved.
Released under Apache 2.0 license as described in the file LICENSE.
Authors: Joseph Rotella
-/
module
prelude
public import Lean.Message
public import Lean.EnvExtension
public import Lean.DocString.Links
public section
namespace Lean
/--
Metadata for an error explanation.
* `summary` gives a short description of the error
* `sinceVersion` indicates the version of Lean in which an error with this error name was introduced
* `severity` is the severity of the diagnostic
* `removedVersion` indicates the version of Lean in which this error name was retired, if applicable
-/
structure ErrorExplanation.Metadata where
summary : String
sinceVersion : String
severity : MessageSeverity := .error
removedVersion? : Option String := none
deriving FromJson, ToJson
/--
An explanation of a named error message.
Error explanations are rendered in the manual; a link to the resulting manual page is displayed at
the bottom of corresponding error messages thrown using `throwNamedError` or `throwNamedErrorAt`.
-/
structure ErrorExplanation where
doc : String
metadata : ErrorExplanation.Metadata
declLoc? : Option DeclarationLocation
namespace ErrorExplanation
/--
Returns the error explanation summary prepended with its severity. For use in completions and
hovers.
-/
def summaryWithSeverity (explan : ErrorExplanation) : String :=
s!"({explan.metadata.severity}) {explan.metadata.summary}"
/--
The kind of a code block in an error explanation example. `broken` blocks raise the diagnostic being
explained; `fixed` blocks must compile successfully.
-/
inductive CodeInfo.Kind
| broken | fixed
deriving Repr, Inhabited, BEq
instance : ToString CodeInfo.Kind where
toString
| .broken => "broken"
| .fixed => "fixed"
def CodeInfo.Kind.ofString : String → Option CodeInfo.Kind
| "broken" => some .broken
| "fixed" => some .fixed
| _ => none
/-- Metadata about a code block in an error explanation, parsed from the block's info string. -/
structure CodeInfo where
lang : String
kind? : Option CodeInfo.Kind
title? : Option String
deriving Repr
open Std.Internal Parsec Parsec.String in
/-- Parse metadata for an error explanation code block from its info string. -/
def CodeInfo.parse (s : String) : Except String CodeInfo :=
infoString.run s |>.mapError (fun e => s!"Invalid code block info string `{s}`: {e}")
where
/-- Parses the contents of a string literal up to, but excluding, the closing quotation mark. -/
stringContents : Parser String := attempt do
let escaped := pchar '\\' *> pchar '"'
let cs ← many (notFollowedBy (pchar '"') *> (escaped <|> any))
return String.mk cs.toList
/--
Parses all input up to the next whitespace. If `nonempty` is `true`, fails if there is no input
prior to the next whitespace.
-/
upToWs (nonempty : Bool) : Parser String := fun it =>
let it' := it.find fun c => c.isWhitespace
if nonempty && it'.pos == it.pos then
.error it' (.other "Expected a nonempty string")
else
.success it' (it.extract it')
/-- Parses a named attribute, and returns its name and value. -/
namedAttr : Parser (String × String) := attempt do
let name ← skipChar '(' *> ws *> (upToWs true)
let contents ← ws *> skipString ":=" *> ws *> skipChar '"' *> stringContents
discard <| skipChar '"' *> ws *> skipChar ')'
return (name, contents)
/--
Parses an "attribute" in an info string, either a space-delineated identifier or a named
attribute of the form `(name := "value")`.
-/
attr : Parser (String ⊕ String × String) :=
.inr <$> namedAttr <|> .inl <$> (upToWs true)
infoString : Parser CodeInfo := do
let lang ← upToWs false
let attrs ← many (attempt <| ws *> attr)
let mut kind? := Option.none
let mut title? := Option.none
for attr in attrs do
match attr with
| .inl atomicAttr =>
match atomicAttr with
| "broken" | "fixed" =>
match kind? with
| none => kind? := Kind.ofString atomicAttr
| some kind =>
fail s!"Redundant kind specifications: previously `{kind}`; now `{atomicAttr}`"
| _ => fail s!"Invalid attribute `{atomicAttr}`"
| .inr (name, val) =>
if name == "title" then
if title?.isNone then
title? := some val
else
fail "Redundant title specifications"
else
fail s!"Invalid named attribute `{name}`; expected `title`"
return { lang, title?, kind? }
open Std.Internal Parsec
/--
An iterator storing nonempty lines in an error explanation together with their original line
numbers.
-/
private structure ValidationState where
lines : Array (String × Nat)
idx : Nat := 0
deriving Repr, Inhabited
/-- Creates an iterator for validation from the raw contents of an error explanation. -/
private def ValidationState.ofSource (input : String) : ValidationState where
lines := input.splitOn "\n"
|>.zipIdx
|>.filter (!·.1.trim.isEmpty)
|>.toArray
-- Workaround to account for the fact that `Input` expects "EOF" to be a valid position
private def ValidationState.get (s : ValidationState) :=
if _ : s.idx < s.lines.size then
s.lines[s.idx].1
else
""
private def ValidationState.getLineNumber (s : ValidationState) :=
if _ : s.lines.size = 0 then
0
else
s.lines[min s.idx (s.lines.size - 1)].2
private instance : Input ValidationState String Nat where
pos := ValidationState.idx
next := fun s => { s with idx := min (s.idx + 1) s.lines.size }
curr := ValidationState.get
hasNext := fun s => s.idx < s.lines.size
next' := fun s _ => { s with idx := s.idx + 1 }
curr' := fun s _ => s.get
private abbrev ValidationM := Parsec ValidationState
private def ValidationM.run (p : ValidationM α) (input : String) : Except (Nat × String) α :=
match p (.ofSource input) with
| .success _ res => Except.ok res
| .error s err => Except.error (s.getLineNumber, toString err)
/--
Matches `p` as many times as possible, followed by EOF. If `p` cannot be matched prior to the end
of the input, rethrows the corresponding error.
-/
private partial def manyThenEOF (p : ValidationM α) : ValidationM Unit := fun s =>
match eof s with
| .success .. => .success s ()
| .error .. =>
match p s with
| .success s' _ => manyThenEOF p s'
| .error s' err => .error s' err
/-- Repeatedly parses the next input as long as it satisfies `p`, and discards the result. -/
private partial def manyD (p : ValidationM α) : ValidationM Unit :=
Parsec.tryCatch p (fun _ => manyD p) (fun _ => pure ())
/-- Parses one or more inputs as long as they satisfy `p`, and discards the result. -/
private def many1D (p : ValidationM α) : ValidationM Unit :=
p *> manyD p
/-- Repeatedly parses the next input as long as it fails to satisfy `p`, and discards the result. -/
private def manyNotD (p : ValidationM α) : ValidationM Unit :=
manyD (notFollowedBy p *> skip)
/-- Parses an error explanation: a general description followed by an examples section. -/
private def parseExplanation : ValidationM Unit := do
manyNotD examplesHeader
eof <|> (examplesHeader *> manyThenEOF singleExample)
where
/-- The top-level `# Examples` header -/
examplesHeader := attempt do
let line ← any
if (matchHeader 1 "Examples" line).isSome then
return
else
fail s!"Expected level-1 'Examples' header, but found `{line}`"
-- We needn't `attempt` examples because they never appear in a location where backtracking is
-- possible, and persisting the line index allows better error message placement
singleExample := do
let header ← exampleHeader
labelingExampleErrors header do
codeBlock "lean" (some .broken)
many1D (codeBlock "output")
many1D do
let leanBlock ← codeBlock "lean" (some .fixed)
let outputBlocks ← many (codeBlock "output")
return (leanBlock, outputBlocks)
manyNotD exampleEndingHeader
/-- A level-2 header for a single example. -/
exampleHeader := attempt do
let line ← any
if let some header := matchHeader 2 none line then
return header
else
fail s!"Expected level-2 header for an example section, but found `{line}`"
/-- A header capable of ending an example. -/
exampleEndingHeader := attempt do
let line ← any
if (matchHeader 1 none line).isSome || (matchHeader 2 none line).isSome then
return
else
fail s!"Expected a level-1 or level-2 header, but found `{line}`"
codeBlock (lang : String) (kind? : Option ErrorExplanation.CodeInfo.Kind := none) := attempt do
let (numTicks, infoString) ← fence
<|> fail s!"Expected a(n){kind?.map (s!" {·}") |>.getD ""} `{lang}` code block"
manyD (notFollowedBy (fence numTicks) *> any)
let (_, closing) ← fence numTicks
<|> fail s!"Missing closing code fence for block with header '{infoString}'"
-- Validate code block:
unless closing.trim.isEmpty do
fail s!"Expected a closing code fence, but found the nonempty info string `{closing}`"
let info ← match ErrorExplanation.CodeInfo.parse infoString with
| .ok i => pure i
| .error s =>
fail s
let langMatches := info.lang == lang
let kindMatches := (kind?.map (some · == info.kind?)).getD true
unless langMatches && kindMatches do
let (expKind, actKind) := match kind? with
| some kind =>
let actualKindStr := (info.kind?.map (s!" {·}")).getD " unspecified-kind"
(s!" {kind}", actualKindStr)
| none => ("", "")
fail s!"Expected a(n){expKind} `{lang}` code block, but found a(n){actKind} `{info.lang}` one"
fence (ticksToClose : Option Nat := none) := attempt do
let line ← any
if line.startsWith "```" then
let numTicks := line.takeWhile (· == '`') |>.length
match ticksToClose with
| none => return (numTicks, line.drop numTicks)
| some n =>
if numTicks == n then
return (numTicks, line.drop numTicks)
else
fail s!"Expected a closing code fence with {n} ticks, but found:\n{line}"
else
-- Don't put `line` in backticks here because it might be a partial code fence
fail s!"Expected a code fence, but found:\n{line}"
/-- Prepends an error raised by `x` to indicate that it arose in example `header`. -/
labelingExampleErrors {α} (header : String) (x : ValidationM α) : ValidationM α := fun s =>
match x s with
| res@(.success ..) => res
| .error s' msg => .error s' (.other s!"Example '{header}' is malformed: {msg}")
/--
If `line` is a level-`level` header and, if `title?` is non-`none`, its title is `title?`,
then returns the contents of the header at `line` (i.e., stripping the leading `#`). Returns
`none` if `line` is not a header of the appropriate form.
-/
matchHeader (level : Nat) (title? : Option String) (line : String) : Option String := do
let octsEndPos := line.nextWhile (· == '#') 0
guard (octsEndPos.byteIdx == level)
guard (line.get octsEndPos == ' ')
let titleStartPos := line.next octsEndPos
let title := Substring.mk line titleStartPos line.endPos |>.toString
let titleMatches : Bool := match title? with
| some expectedTitle => title == expectedTitle
| none => true
guard titleMatches
some title
/--
Validates that the given error explanation has the expected structure. If an error is found, it is
represented as a pair `(lineNumber, errorMessage)` where `lineNumber` gives the 0-based offset from
the first line of `doc` at which the error occurs.
-/
def processDoc (doc : String) : Except (Nat × String) Unit :=
parseExplanation.run doc
end ErrorExplanation
/-- An environment extension that stores error explanations. -/
builtin_initialize errorExplanationExt : SimplePersistentEnvExtension (Name × ErrorExplanation) (NameMap ErrorExplanation) ←
registerSimplePersistentEnvExtension {
addEntryFn := fun s (n, v) => s.insert n v
addImportedFn := fun ess =>
ess.foldl (init := ∅) fun acc es =>
es.foldl (init := acc) fun acc (n, v) =>
acc.insert n v
}
/-- Returns an error explanation for the given name if one exists, rewriting manual links. -/
def getErrorExplanation? [Monad m] [MonadEnv m] [MonadLiftT BaseIO m] (name : Name) : m (Option ErrorExplanation) := do
let explan? := errorExplanationExt.getState (← getEnv) |>.find? name
explan?.mapM fun explan =>
return { explan with doc := (← rewriteManualLinks explan.doc) }
/--
Returns an error explanation for the given name if one exists *without* rewriting manual links.
In general, use `Lean.getErrorExplanation?` instead if the body of the explanation will be used.
-/
def getErrorExplanationRaw? (env : Environment) (name : Name) : Option ErrorExplanation := do
errorExplanationExt.getState env |>.find? name
/-- Returns `true` if there exists an error explanation named `name`. -/
def hasErrorExplanation [Monad m] [MonadEnv m] [MonadLiftT BaseIO m] (name : Name) : m Bool :=
return errorExplanationExt.getState (← getEnv) |>.contains name
/--
Returns all error explanations with their names as an unsorted array, *without* rewriting manual
links.
In general, use `Lean.getErrorExplanations` or `Lean.getErrorExplanationsSorted` instead of this
function if the bodies of the fetched explanations will be used.
-/
def getErrorExplanationsRaw (env : Environment) : Array (Name × ErrorExplanation) :=
errorExplanationExt.getState env |>.toArray
/-- Returns all error explanations with their names, rewriting manual links. -/
def getErrorExplanations [Monad m] [MonadEnv m] [MonadLiftT BaseIO m] : m (Array (Name × ErrorExplanation)) := do
let entries := errorExplanationExt.getState (← getEnv) |>.toArray
entries
|>.mapM fun (n, e) => return (n, { e with doc := (← rewriteManualLinks e.doc) })
/--
Returns all error explanations with their names as a sorted array, rewriting manual links.
-/
def getErrorExplanationsSorted [Monad m] [MonadEnv m] [MonadLiftT BaseIO m] : m (Array (Name × ErrorExplanation)) := do
return (← getErrorExplanations).qsort fun e e' => e.1.toString < e'.1.toString
end Lean