Add documentation, and @inlinable / @usableFromInline.

Author: kareman

Sources/Patterns/Decoder.swift

@@ -6,27 +6,36 @@
 //
 
 extension Parser where Input == String {
+	/// Decodes all matches found in `string` into an array of `T`.
+	@inlinable
 	public func decode<T>(_ type: [T].Type, from string: String) throws -> [T] where T: Decodable {
 		try matches(in: string).map { try $0.decode(type.Element.self, from: string) }
 	}
 
+	/// Decodes the first match found in `string` into a value of type `type`.
+	@inlinable
 	public func decodeFirst<T>(_ type: T.Type, from string: String) throws -> T? where T: Decodable {
 		try match(in: string, at: string.startIndex).map { try $0.decode(type.self, from: string) }
 	}
 }
 
 extension Parser.Match where Input == String {
+	/// Decodes this match found in `string` into a value of type `type`.
+	@inlinable
 	public func decode<T>(_ type: T.Type, from string: String) throws -> T where T: Decodable {
-		return try type.init(from: MatchDecoder(match: self, string: string))
+		try type.init(from: MatchDecoder(match: self, string: string))
 	}
 
 	public struct MatchDecoder: Decoder {
+		@usableFromInline
 		let match: Parser.Match
+		@usableFromInline
 		let string: String
 
 		public let codingPath: [CodingKey]
 		public var userInfo: [CodingUserInfoKey: Any] { [:] }
 
+		@inlinable
 		init(match: Parser.Match, string: String, codingPath: [CodingKey] = []) {
 			let namePrefix = codingPath.first.map { $0.stringValue }
 			let captures = namePrefix.map { namePrefix in
@@ -40,52 +49,77 @@ extension Parser.Match where Input == String {
 			self.codingPath = codingPath
 		}
 
+		@inlinable
 		public func container<Key>(keyedBy _: Key.Type) throws -> KeyedDecodingContainer<Key> where Key: CodingKey {
-			return KeyedDecodingContainer(KDC(codingPath: codingPath, matchDecoder: self))
+			KeyedDecodingContainer(KDC(codingPath: codingPath, matchDecoder: self))
 		}
 
+		@inlinable
 		public func unkeyedContainer() throws -> UnkeyedDecodingContainer {
 			UDC(codingPath: codingPath, values: match.captures.map { $0.range }, string: string)
 		}
 
+		@inlinable
 		public func singleValueContainer() throws -> SingleValueDecodingContainer {
 			guard match.captures.count < 2 else {
+				let property = codingPath.map { "\($0.stringValue)" }.joined(separator: ".")
 				throw DecodingError.dataCorrupted(DecodingError.Context(codingPath: codingPath, debugDescription:
-					"Property '\(codingPath.map { "\($0.stringValue)" }.joined(separator: "."))' needs a single value, but multiple captures exists."))
+					"Property '\(property)' needs a single value, but multiple captures exists."))
 			}
 			let range = match.captures.first?.range ?? match.endIndex ..< match.endIndex
 			return StringDecoder(string: String(string[range]), codingPath: codingPath)
 		}
 
+		@usableFromInline
 		struct UDC: UnkeyedDecodingContainer {
+			@usableFromInline
 			var codingPath: [CodingKey]
+			@usableFromInline
 			let values: [Range<Pattern.Input.Index>]
+			@usableFromInline
 			let string: String
 
+			@usableFromInline
+			init(codingPath: [CodingKey], values: [Range<Pattern.Input.Index>], string: String) {
+				self.codingPath = codingPath
+				self.values = values
+				self.string = string
+			}
+
+			@usableFromInline
 			var count: Int? { values.count }
+			@usableFromInline
 			var isAtEnd: Bool { currentIndex >= values.endIndex }
+			@usableFromInline
 			var currentIndex: Int = 0
 
+			@usableFromInline
 			mutating func decodeNil() throws -> Bool { false }
 
-			mutating func nestedContainer<NestedKey>(keyedBy type: NestedKey.Type) throws -> KeyedDecodingContainer<NestedKey> where NestedKey: CodingKey {
+			@usableFromInline
+			mutating func nestedContainer<NestedKey>(keyedBy type: NestedKey.Type)
+				throws -> KeyedDecodingContainer<NestedKey> where NestedKey: CodingKey {
 				fatalError("Not implemented yet. If you want to help with that, go to https://github.com/kareman/Patterns")
 			}
 
+			@usableFromInline
 			mutating func nestedUnkeyedContainer() throws -> UnkeyedDecodingContainer {
 				fatalError("Not implemented yet. If you want to help with that, go to https://github.com/kareman/Patterns")
 			}
 
+			@usableFromInline
 			mutating func superDecoder() throws -> Decoder {
 				fatalError("Not implemented yet. If you want to help with that, go to https://github.com/kareman/Patterns")
 			}
 
+			@usableFromInline
 			mutating func decode<T>(_ type: T.Type) throws -> T where T: Decodable {
 				defer { currentIndex += 1 }
 				let text = String(string[values[currentIndex]])
 				return try type.init(from: StringDecoder(string: text, codingPath: codingPath))
 			}
 
+			@usableFromInline
 			mutating func decode<T>(_ type: T.Type) throws -> T where T: Decodable & LosslessStringConvertible {
 				guard let value = type.init(String(string[values[currentIndex]])) else {
 					throw DecodingError.typeMismatch(type, DecodingError.Context(codingPath: codingPath, debugDescription: ""))
@@ -95,82 +129,118 @@ extension Parser.Match where Input == String {
 			}
 		}
 
+		@usableFromInline
 		struct KDC<Key: CodingKey>: KeyedDecodingContainerProtocol {
+			@usableFromInline
 			var codingPath: [CodingKey] = []
+			@usableFromInline
 			var allKeys: [Key] {
 				matchDecoder.match.names.compactMap(Key.init(stringValue:))
 			}
 
+			@usableFromInline
 			let matchDecoder: MatchDecoder
 
+			@usableFromInline
+			init(codingPath: [CodingKey] = [], matchDecoder: MatchDecoder) {
+				self.codingPath = codingPath
+				self.matchDecoder = matchDecoder
+			}
+
+			@usableFromInline
 			func capture(for key: CodingKey) throws -> String {
 				guard let range = matchDecoder.match[one: key.stringValue] else {
 					throw DecodingError.keyNotFound(key, DecodingError.Context(codingPath: codingPath, debugDescription: ""))
 				}
 				return String(matchDecoder.string[range])
 			}
 
+			@usableFromInline
 			func contains(_ key: Key) -> Bool {
 				matchDecoder.match[one: key.stringValue] == nil
 			}
 
+			@usableFromInline
 			func decodeNil(forKey key: Key) throws -> Bool {
 				contains(key)
 			}
 
+			@usableFromInline
 			func decode<T>(_ type: T.Type, forKey key: Key) throws -> T where T: Decodable {
-				return try type.init(from: MatchDecoder(match: matchDecoder.match, string: matchDecoder.string, codingPath: codingPath + [key]))
+				return try type.init(from:
+					MatchDecoder(match: matchDecoder.match, string: matchDecoder.string, codingPath: codingPath + [key]))
 			}
 
+			@usableFromInline
 			func decode<T>(_ type: T.Type, forKey key: Key) throws -> T where T: Decodable & LosslessStringConvertible {
 				guard let value = type.init(try capture(for: key)) else {
 					throw DecodingError.typeMismatch(type, DecodingError.Context(codingPath: [key], debugDescription: ""))
 				}
 				return value
 			}
 
-			func nestedContainer<NestedKey>(keyedBy _: NestedKey.Type, forKey _: Key) throws -> KeyedDecodingContainer<NestedKey> where NestedKey: CodingKey {
+			@usableFromInline
+			func nestedContainer<NestedKey>(keyedBy _: NestedKey.Type, forKey _: Key)
+				throws -> KeyedDecodingContainer<NestedKey> where NestedKey: CodingKey {
 				fatalError("Not implemented yet. If you want to help with that, go to https://github.com/kareman/Patterns")
 			}
 
+			@usableFromInline
 			func nestedUnkeyedContainer(forKey _: Key) throws -> UnkeyedDecodingContainer {
 				fatalError("Not implemented yet. If you want to help with that, go to https://github.com/kareman/Patterns")
 			}
 
+			@usableFromInline
 			func superDecoder() throws -> Decoder {
 				fatalError("Not implemented yet. If you want to help with that, go to https://github.com/kareman/Patterns")
 			}
 
+			@usableFromInline
 			func superDecoder(forKey _: Key) throws -> Decoder {
 				fatalError("Not implemented yet. If you want to help with that, go to https://github.com/kareman/Patterns")
 			}
 		}
 	}
 }
 
+@usableFromInline
 struct StringDecoder: Decoder, SingleValueDecodingContainer {
+	@usableFromInline
 	let string: String
+	@usableFromInline
 	let codingPath: [CodingKey]
+	@usableFromInline
 	var userInfo: [CodingUserInfoKey: Any] = [:]
 
+	@usableFromInline
+	init(string: String, codingPath: [CodingKey], userInfo: [CodingUserInfoKey: Any] = [:]) {
+		self.string = string
+		self.codingPath = codingPath
+		self.userInfo = userInfo
+	}
+
+	@usableFromInline
 	func container<Key>(keyedBy type: Key.Type) throws -> KeyedDecodingContainer<Key> where Key: CodingKey {
 		fatalError("Not implemented yet. If you want to help with that, go to https://github.com/kareman/Patterns")
 	}
 
+	@usableFromInline
 	func unkeyedContainer() throws -> UnkeyedDecodingContainer {
 		fatalError("Not implemented yet. If you want to help with that, go to https://github.com/kareman/Patterns")
 	}
 
-	func singleValueContainer() throws -> SingleValueDecodingContainer {
-		self
-	}
+	@usableFromInline
+	func singleValueContainer() throws -> SingleValueDecodingContainer { self }
 
+	@usableFromInline
 	func decodeNil() -> Bool { false }
 
+	@usableFromInline
 	func decode<T>(_ type: T.Type) throws -> T where T: Decodable {
 		fatalError("Not implemented yet. If you want to help with that, go to https://github.com/kareman/Patterns")
 	}
 
+	@usableFromInline
 	func decode<T>(_ type: T.Type) throws -> T where T: Decodable & LosslessStringConvertible {
 		guard let value = type.init(string) else {
 			throw DecodingError.typeMismatch(type, DecodingError.Context(codingPath: codingPath, debugDescription: ""))

Sources/Patterns/General/General.swift

@@ -108,6 +108,7 @@ extension Sequence {
 }
 
 /// Used like e.g. `let a = optional ?? fatalError("Message")`.
+@inlinable
 func ?? <T>(b: T?, a: @autoclosure () -> Never) -> T {
 	if let b = b {
 		return b
@@ -116,6 +117,7 @@ func ?? <T>(b: T?, a: @autoclosure () -> Never) -> T {
 }
 
 /// Used like e.g. `let a = try optional ?? AnError()`.
+@inlinable
 func ?? <T, E: Error>(b: T?, a: @autoclosure () -> (E)) throws -> T {
 	if let b = b {
 		return b

Sources/Patterns/Operations on Patterns/Concatenation.swift

@@ -12,36 +12,46 @@ precedencegroup PatternConcatenationPrecedence {
 
 infix operator •: PatternConcatenationPrecedence
 
+/// A pattern which first tries the `first` pattern,
+/// if that succeeds it continues with the `second` pattern.
 public struct Concat<First: Pattern, Second: Pattern>: Pattern {
 	public let first: First
 	public let second: Second
 	public var description: String { "\(first) \(second)" }
 
+	@inlinable
 	init(_ first: First, _ second: Second) {
 		self.first = first
 		self.second = second
 	}
-}
 
-extension Concat {
+	@inlinable
 	public func createInstructions(_ instructions: inout Instructions) throws {
 		try first.createInstructions(&instructions)
 		try second.createInstructions(&instructions)
 	}
 }
 
+/// First tries the pattern to the left, if that succeeds it tries the pattern to the right.
+@inlinable
 public func • <Left, Right>(lhs: Left, rhs: Right) -> Concat<Left, Right> {
 	Concat(lhs, rhs)
 }
 
+/// First tries the pattern to the left, if that succeeds it tries the pattern to the right.
+@inlinable
 public func • <Right>(lhs: Literal, rhs: Right) -> Concat<Literal, Right> {
 	Concat(lhs, rhs)
 }
 
+/// First tries the pattern to the left, if that succeeds it tries the pattern to the right.
+@inlinable
 public func • <Left>(lhs: Left, rhs: Literal) -> Concat<Left, Literal> {
 	Concat(lhs, rhs)
 }
 
+/// First tries the pattern to the left, if that succeeds it tries the pattern to the right.
+@inlinable
 public func • (lhs: Literal, rhs: Literal) -> Concat<Literal, Literal> {
 	Concat(lhs, rhs)
 }

Sources/Patterns/Operations on Patterns/Not.swift

@@ -5,10 +5,18 @@
 //  Created by Kåre Morstøl on 25/05/2020.
 //
 
+/// A pattern which only succeeds if the `wrapped` pattern fails.
+/// The next pattern will continue from where `wrapped` started.
 public struct NotPattern<Wrapped: Pattern>: Pattern {
 	public let wrapped: Wrapped
 	public var description: String { "!\(wrapped)" }
 
+	@inlinable
+	init(_ wrapped: Wrapped) {
+		self.wrapped = wrapped
+	}
+
+	@inlinable
 	public func createInstructions(_ instructions: inout Instructions) throws {
 		let wrappedInstructions = try wrapped.createInstructions()
 		instructions.append(.choice(offset: wrappedInstructions.count + 3))
@@ -18,14 +26,14 @@ public struct NotPattern<Wrapped: Pattern>: Pattern {
 	}
 }
 
-extension Pattern {
-	public var not: NotPattern<Self> { NotPattern(wrapped: self) }
-
-	public static prefix func ! (me: Self) -> NotPattern<Self> {
-		me.not
-	}
+/// Will only succeed if the following pattern fails. Does not consume any input.
+@inlinable
+public prefix func ! <P: Pattern>(pattern: P) -> NotPattern<P> {
+	NotPattern(pattern)
 }
 
-public prefix func ! (me: Literal) -> NotPattern<Literal> {
-	me.not
+/// Will only succeed if the following pattern fails. Does not consume any input.
+@inlinable
+public prefix func ! (pattern: Literal) -> NotPattern<Literal> {
+	NotPattern(pattern)
 }