Improve and fix documentation for Skip.

Author: kareman

Sources/Patterns/Operations on Patterns/Skip.swift

@@ -5,9 +5,32 @@
 //  Created by Kåre Morstøl on 25/05/2020.
 //
 
-/// Skips 0 or more elements until a match for the next patterns are found.
+/// Skips 0 or more elements until a match for the next patterns is found.
 ///
-/// If this is at the end of a pattern, it skips to the end of input.
+/// ```swift
+/// let s = Skip() • a
+/// ```
+/// is the same as `|S <- A / . <S>|` in standard PEG.
+///
+/// - note:
+/// If `Skip` is at the end of a pattern, it just succeeds without consuming input. So it will be pointless.
+///
+/// But this works:
+/// ```swift
+/// let s = Skip()
+/// let p = s • " "
+/// ```
+/// because here the `s` pattern is "inlined".
+///
+/// This, however, does not work:
+/// ```swift
+/// let g = Grammar { g in
+///   g.nextSpace <- g.skip • " "
+///   g.skip <- Skip()
+/// }
+/// ```
+/// because in grammars the subexpressions are called, like functions, not "inlined", like Swift variables.
+/// So the `Skip()` in `g.skip` can't tell what will come after it.
 public struct Skip<Input: BidirectionalCollection>: Pattern where Input.Element: Hashable {
 	public var description: String { "Skip()" }
 

Tests/PatternsTests/SkipTests.swift

@@ -46,10 +46,6 @@ class SkipTests: XCTestCase {
 		               input: lines, result: ["1", "2", "", "3"])
 		assertParseAll(Capture(Line.start • Skip() • Line.end),
 		               input: lines, result: ["1", "2", "", "3"])
-
-		// undefined (Skip at end)
-		_ = try Parser(search: " " • Capture(Skip()))
-			.matches(in: text)
 	}
 
 	func testInsideOptional() throws {
@@ -73,6 +69,22 @@ class SkipTests: XCTestCase {
 		assertParseMarkers(try Parser(Skip() • Skip() • " "), input: "This |is")
 	}
 
+	func testAtTheEnd() throws {
+		assertParseMarkers(" " • Skip(), input: "a |bee")
+		assertParseAll(" " • Capture(Skip()), input: "a bee", result: [""])
+
+		// used in documentation for Skip.
+
+		let s = Skip()
+		assertParseMarkers(try Parser(s • " "), input: "jfd | |jlj |")
+
+		let g = Grammar { g in
+			g.nextSpace <- g.skip • " "
+			g.skip <- Skip() // Does not work.
+		}
+		assertParseMarkers(try Parser(g), input: "sdf ksj")
+	}
+
 	func testBeforeGrammarTailCall() throws {
 		let recursive = Grammar { g in
 			g.a <- " " • Skip() • g.a