Skip to content

Commit

Permalink
clean up doc warnings
Browse files Browse the repository at this point in the history
  • Loading branch information
@tayloraswift
tayloraswift committed Sep 27, 2023
1 parent a045750 commit 0e3bf28
Show file tree
Hide file tree
Showing 3 changed files with 160 additions and 164 deletions.
134 changes: 67 additions & 67 deletions Sources/Grammar/Parsing/Grammar.swift
View file
Original file line number Diff line number Diff line change
@@ -1,26 +1,26 @@
@available(*, deprecated, renamed: "NoDiagnostics")
public
public
typealias _NoDiagnostics = NoDiagnostics
@available(*, deprecated, renamed: "DefaultDiagnostics")
public
public
typealias _DefaultDiagnostics = DefaultDiagnostics

/// A namespace for structured parsing utilities.
@available(*, deprecated)
public
enum Grammar
public
enum Grammar
{
// note: this only works on swift >= 5.7
/// A shortcut for expressing the type constraints on ``ParsingRule.parse(_:)``.
///
/// To use this compile-time abstraction, fill in its generic parameters and
/// declare that it must conform to [`Any`]().
///
///
/// To use this compile-time abstraction, fill in its generic parameters and
/// declare that it must conform to ``Any``.
///
/// For example, the following:
/**
```swift
static
func parse<Diagnostics>(_ input:inout ParsingInput<Diagnostics>)
/**
```swift
static
func parse<Diagnostics>(_ input:inout ParsingInput<Diagnostics>)
throws -> Void?
where Grammar.Parsable<String.Index, UInt8, Diagnostics>:Any
{
Expand All @@ -29,163 +29,163 @@ enum Grammar
```
*/
/// is equivalent to:
/**
```swift
static
func parse<Diagnostics>(_ input:inout ParsingInput<Diagnostics>)
/**
```swift
static
func parse<Diagnostics>(_ input:inout ParsingInput<Diagnostics>)
throws -> Void?
where Diagnostics:ParsingDiagnostics,
where Diagnostics:ParsingDiagnostics,
Diagnostics.Source.Index == String.Index,
Diagnostics.Source.Element == UInt8
{
// ...
}
```
*/
public
typealias Parsable<Location, Terminal, Diagnostics> = Never
where Diagnostics:ParsingDiagnostics,
Diagnostics.Source.Index == Location,
public
typealias Parsable<Location, Terminal, Diagnostics> = Never
where Diagnostics:ParsingDiagnostics,
Diagnostics.Source.Index == Location,
Diagnostics.Source.Element == Terminal

/// A generic context for unicode definitions.
@available(*, deprecated, renamed: "UnicodeEncoding")
public
public
typealias Encoding = UnicodeEncoding

@available(*, deprecated, renamed: "ParsingRule.parse(diagnosing:)")
@inlinable public static
@inlinable public static
func parse<Source, Root>(diagnosing source:Source, as _:Root.Type) throws -> Root.Construction
where Source:Collection, Root:ParsingRule<Source.Element>,
where Source:Collection, Root:ParsingRule<Source.Element>,
Root.Location == Source.Index
{
try Root.parse(diagnosing: source)
}

@available(*, deprecated, renamed: "ParsingRule.parse(_:)")
@inlinable public static
@inlinable public static
func parse<Source, Root>(_ source:Source, as _:Root.Type) throws -> Root.Construction
where Source:Collection, Root:ParsingRule<Source.Element>,
where Source:Collection, Root:ParsingRule<Source.Element>,
Root.Location == Source.Index
{
try Root.parse(source)
}
@available(*, deprecated, renamed: "ParsingRule.parse(_:into:)")
@inlinable public static
@inlinable public static
func parse<Source, Rule, Vector>(_ source:Source, as _:Rule.Type, in _:Vector.Type) throws -> Vector
where Source:Collection,
Rule:ParsingRule<Source.Element>, Rule.Location == Source.Index,
Rule:ParsingRule<Source.Element>, Rule.Location == Source.Index,
Vector:RangeReplaceableCollection<Rule.Construction>
{
try Rule.parse(source, into: Vector.self)
}

@available(*, deprecated, renamed: "LiteralRule")
public
public
typealias TerminalSequence = LiteralRule

@available(*, deprecated, renamed: "TerminalRule")
public
public
typealias TerminalClass = TerminalRule

/// ``Grammar//NoDiagnostics`` was moved to the top-level
/// ``Grammar//NoDiagnostics`` was moved to the top-level
/// namespace of this module.
@available(*, deprecated, renamed: "NoDiagnostics")
public
typealias NoDiagnostics = _NoDiagnostics
public
typealias NoDiagnostics = _NoDiagnostics

/// ``Grammar//DefaultDiagnostics`` was moved to the top-level
/// ``Grammar//DefaultDiagnostics`` was moved to the top-level
/// namespace of this module.
@available(*, deprecated, renamed: "DefaultDiagnostics")
public
public
typealias DefaultDiagnostics = _DefaultDiagnostics

@available(*, deprecated, renamed: "Pattern.End")
public
typealias End<Location, Terminal> = Pattern.End<Location, Terminal>

@available(*, deprecated, renamed: "Pattern.Discard")
public
public
typealias Discard<Rule> = Pattern.Discard<Rule>
where Rule:ParsingRule, Rule.Construction == Void

@available(*, deprecated, renamed: "Pattern.Collect")
public
public
typealias Collect<Rule, Construction> = Pattern.Collect<Rule, Construction>
where Rule:ParsingRule, Rule.Construction == Construction.Element,
Construction:RangeReplaceableCollection

@available(*, deprecated, renamed: "Pattern.Reduce")
public
public
typealias Reduce<Rule, Construction> = Pattern.Reduce<Rule, Construction>
where Rule:ParsingRule, Rule.Construction == Construction.Element,
Construction:RangeReplaceableCollection

@available(*, deprecated, renamed: "Pattern.Join")
public
public
typealias Join<Rule, Separator, Construction> = Pattern.Join<Rule, Separator, Construction>
where Rule:ParsingRule, Separator:ParsingRule,
Rule.Location == Separator.Location,
Rule.Terminal == Separator.Terminal,
Separator.Construction == Void,
Rule.Construction == Construction.Element,
Rule.Location == Separator.Location,
Rule.Terminal == Separator.Terminal,
Separator.Construction == Void,
Rule.Construction == Construction.Element,
Construction:RangeReplaceableCollection

@available(*, deprecated, renamed: "Pattern.Pad")
public
public
typealias Pad<Rule, Padding> = Pattern.Pad<Rule, Padding>
where Rule:ParsingRule, Padding:ParsingRule,
where Rule:ParsingRule, Padding:ParsingRule,
Rule.Location == Padding.Location,
Rule.Terminal == Padding.Terminal,
Rule.Terminal == Padding.Terminal,
Padding.Construction == Void

@available(*, deprecated, renamed: "UnicodeDigit.Natural")
public
typealias NaturalDecimalDigit<Location, Terminal, Construction> =
public
typealias NaturalDecimalDigit<Location, Terminal, Construction> =
UnicodeDigit<Location, Terminal, Construction>.Natural
where Terminal:BinaryInteger, Construction:BinaryInteger
@available(*, deprecated, renamed: "UnicodeDigit.Decimal")
public
typealias DecimalDigit<Location, Terminal, Construction> =
public
typealias DecimalDigit<Location, Terminal, Construction> =
UnicodeDigit<Location, Terminal, Construction>.Decimal
where Terminal:BinaryInteger, Construction:BinaryInteger
@available(*, deprecated, renamed: "UnicodeDigit.Hex")
public
typealias HexDigit<Location, Terminal, Construction> =
public
typealias HexDigit<Location, Terminal, Construction> =
UnicodeDigit<Location, Terminal, Construction>.Hex
where Terminal:BinaryInteger, Construction:BinaryInteger

@available(*, deprecated, renamed: "UnicodeDigit.NaturalScalar")
public
typealias NaturalDecimalDigitScalar<Location, Construction> =
public
typealias NaturalDecimalDigitScalar<Location, Construction> =
UnicodeDigit<Location, Unicode.Scalar, Construction>.NaturalScalar
where Construction:BinaryInteger
@available(*, deprecated, renamed: "UnicodeDigit.DecimalScalar")
public
typealias DecimalDigitScalar<Location, Construction> =
public
typealias DecimalDigitScalar<Location, Construction> =
UnicodeDigit<Location, Unicode.Scalar, Construction>.DecimalScalar
where Construction:BinaryInteger
@available(*, deprecated, renamed: "UnicodeDigit.HexScalar")
public
typealias HexDigitScalar<Location, Construction> =
public
typealias HexDigitScalar<Location, Construction> =
UnicodeDigit<Location, Unicode.Scalar, Construction>.HexScalar
where Construction:BinaryInteger

@available(*, deprecated, renamed: "Pattern.IntegerOverflowError")
public
typealias IntegerOverflowError<T> = Pattern.IntegerOverflowError<T> where T:FixedWidthInteger

@available(*, deprecated, renamed: "Pattern.UnsignedInteger")
public
typealias UnsignedIntegerLiteral<Digit> = Pattern.UnsignedInteger<Digit>
where Digit:DigitRule, Digit.Construction:FixedWidthInteger

@available(*, deprecated, renamed: "Pattern.UnsignedNormalizedInteger")
public
typealias UnsignedNormalizedIntegerLiteral<First, Next> =
typealias UnsignedNormalizedIntegerLiteral<First, Next> =
Pattern.UnsignedNormalizedInteger<First, Next>
where First:ParsingRule, Next:DigitRule, Next.Construction:FixedWidthInteger,
First.Construction == Next.Construction,
First.Location == Next.Location,
where First:ParsingRule, Next:DigitRule, Next.Construction:FixedWidthInteger,
First.Construction == Next.Construction,
First.Location == Next.Location,
First.Terminal == Next.Terminal
}
80 changes: 40 additions & 40 deletions Sources/Grammar/Parsing/ParsingError.swift
View file
Original file line number Diff line number Diff line change
@@ -1,98 +1,98 @@
import TraceableErrors

/// An error type that indicates the furthest-successful parse, and provides a
/// An error type that indicates the furthest-successful parse, and provides a
/// stack trace detailing how the parser got there.
///
/// None of the structured parsers defined in ``/swift-grammar`` throw this error
///
/// None of the structured parsers defined in swift-grammar throw this error
/// directly. Instead, the ``DefaultDiagnostics`` engine computes it
/// based on the diagnostic engine’s internal state when encountering
/// based on the diagnostic engine’s internal state when encountering
/// invalid input.
///
///
/// Custom ``ParsingRule`` implementations should not throw this error either.
@frozen public
struct ParsingError<Index>:TraceableError, CustomStringConvertible
@frozen public
struct ParsingError<Index>:TraceableError, CustomStringConvertible
{
/// The underlying parsing error.
public
public
let underlying:Error
/// The index of the first invalid terminal in the input, or the ``Collection/.endIndex``
/// of the input.
///
/// If the parser attempted to apply multiple rules via backtracking, this
/// The index of the first invalid terminal in the input, or the ``Collection endIndex``
/// of the input.
///
/// If the parser attempted to apply multiple rules via backtracking, this
/// index comes from the longest successful parse.
public
public
let index:Index
public
public
let trace:[Frame]
@inlinable public

@inlinable public
init(at index:Index, because error:Error, trace:[Frame])
{
self.underlying = error
self.index = index
self.index = index
self.trace = trace
}

public
var notes:[String]
public
var notes:[String]
{
trace.map
trace.map
{
if $0.construction is Void.Type
{
return "while matching pattern '\($0.rule)'"
}
else
else
{
return "while parsing value of type '\($0.construction)' by rule '\($0.rule)'"
}
}
}
static
func annotate<Background>(_ range:Range<Index>, background:Background,
renderer render:(Background.SubSequence) -> String,
newline predicate:(Background.Element) -> Bool)
-> String

static
func annotate<Background>(_ range:Range<Index>, background:Background,
renderer render:(Background.SubSequence) -> String,
newline predicate:(Background.Element) -> Bool)
-> String
where Background:BidirectionalCollection, Background.Index == Index
{
// `..<` means this will print the previous line if the problematic
// `..<` means this will print the previous line if the problematic
// index references the newline itself
let beginning:String,
let beginning:String,
middle:String
if let start:Index = background[..<range.lowerBound].lastIndex (where: predicate)
{
// can only remove newline if there is actually a preceeding newline
// can only remove newline if there is actually a preceeding newline
beginning = render(background[start..<range.lowerBound].dropFirst())
}
else
else
{
beginning = render(background[..<range.lowerBound])
}
}
let line:String
let end:Index = background[range.lowerBound...].firstIndex(where: predicate) ??
let end:Index = background[range.lowerBound...].firstIndex(where: predicate) ??
background.endIndex
if range.upperBound < end
if range.upperBound < end
{
middle = render(background[range])
line = beginning + middle + render(background[range.upperBound..<end])
}
else
else
{
middle = render(background[range.lowerBound..<end])
line = beginning + middle
line = beginning + middle
}
return
return
"""
\(line)
\(String.init(repeating: " ", count: beginning.count))\
^\(String.init(repeating: "~", count: middle.count).dropLast())
"""
}
public
func annotate<Background>(source background:Background,
public
func annotate<Background>(source background:Background,
renderer:(Background.SubSequence) -> String,
newline:(Background.Element) -> Bool) -> String
newline:(Background.Element) -> Bool) -> String
where Background:BidirectionalCollection, Background.Index == Index
{
var annotation:String = self.underlying.headline()
Expand Down
Loading

0 comments on commit 0e3bf28

Please sign in to comment.