From 1c4cb30d6489f978ecf4ca27acf405a4babdbed7 Mon Sep 17 00:00:00 2001
From: Andrew Davis <pulpdrew@gmail.com>
Date: Tue, 17 Mar 2020 21:22:35 -0400
Subject: [PATCH] Add documentation for skip and skip-while (#1499)

---
 docs/commands/skip-while.md | 46 +++++++++++++++++++++++++++++++++++++
 docs/commands/skip.md       | 33 ++++++++++++++++++++++++++
 2 files changed, 79 insertions(+)
 create mode 100644 docs/commands/skip-while.md
 create mode 100644 docs/commands/skip.md

diff --git a/docs/commands/skip-while.md b/docs/commands/skip-while.md
new file mode 100644
index 0000000000..7453d33207
--- /dev/null
+++ b/docs/commands/skip-while.md
@@ -0,0 +1,46 @@
+# skip-while
+Skips rows while the condition matches. 
+
+## Usage
+```shell
+> [input-command] | skip-while <condition>
+```
+
+## Examples
+
+If we open a file with a list of contacts, we get all of the contacts. 
+```shell
+> open contacts.csv | sort-by "last name"
+───┬────────────┬───────────┬──────────────────
+ # │ first name │ last name │ email
+───┼────────────┼───────────┼──────────────────
+ 0 │ John       │ Abbot     │ abbot@email.com
+ 1 │ Chris      │ Beasly    │ beasly@email.com
+ 2 │ Jane       │ Carver    │ carver@email.com
+ 3 │ Francis    │ Davis     │ davis@email.com
+───┴────────────┴───────────┴──────────────────
+```
+
+To exclude skip contacts with last names startin with 'A' or 'B', use skip-while: 
+```shell
+> open contacts.csv | sort-by "last name" |  skip-while "last name" < "C"
+───┬────────────┬───────────┬──────────────────
+ # │ first name │ last name │ email
+───┼────────────┼───────────┼──────────────────
+ 0 │ Jane       │ Carver    │ carver@email.com
+ 1 │ Francis    │ Davis     │ davis@email.com
+───┴────────────┴───────────┴──────────────────
+```
+
+Note that the order of input rows matters. Once a single row does not match the condition, all following rows are included in the output, whether or not they match the condition:
+```shell
+> open contacts.csv | skip-while "last name" < "C"
+───┬────────────┬───────────┬──────────────────
+ # │ first name │ last name │ email
+───┼────────────┼───────────┼──────────────────
+ 0 │ Jane       │ Carver    │ carver@email.com
+ 1 │ Chris      │ Beasly    │ beasly@email.com
+ 2 │ Francis    │ Davis     │ davis@email.com
+───┴────────────┴───────────┴──────────────────
+```
+See the `where` command to filter each individual row by a condition, regardless of order.
\ No newline at end of file
diff --git a/docs/commands/skip.md b/docs/commands/skip.md
new file mode 100644
index 0000000000..71476b3b44
--- /dev/null
+++ b/docs/commands/skip.md
@@ -0,0 +1,33 @@
+# skip
+Skips the first 'n' rows of a table. 
+
+## Usage
+```shell
+> [input-command] | skip (n)
+```
+
+## Examples
+
+If we open a file with a list of contacts, we get all of the contacts. 
+```shell
+> open contacts.csv
+───┬─────────┬──────┬─────────────────
+ # │ first   │ last │ email
+───┼─────────┼──────┼─────────────────
+ 0 │ John    │ Doe  │ doe.1@email.com
+ 1 │ Jane    │ Doe  │ doe.2@email.com
+ 2 │ Chris   │ Doe  │ doe.3@email.com
+ 3 │ Francis │ Doe  │ doe.4@email.com
+───┴─────────┴──────┴─────────────────
+```
+
+To ignore the first 2 contacts, we can `skip` them.
+```shell
+> open contacts.csv | skip 2
+───┬─────────┬──────┬─────────────────
+ # │ first   │ last │ email
+───┼─────────┼──────┼─────────────────
+ 0 │ Chris   │ Doe  │ doe.3@email.com
+ 1 │ Francis │ Doe  │ doe.4@email.com
+───┴─────────┴──────┴─────────────────
+```
\ No newline at end of file