Add 'every' command to select (or skip) every nth row (#1992)

* Add 'every' command

* Add --skip option to 'every' command

This option skips instead of selects every nth row

* Fix descriptions for 'every' command

* Add docummentation for 'every' command

* Check actual filenames in 'every' command tests

crates/nu-cli/src/cli.rs

@@ -320,6 +320,7 @@ pub fn create_default_context(
             whole_stream_command(GroupByDate),
             whole_stream_command(First),
             whole_stream_command(Last),
+            whole_stream_command(Every),
             whole_stream_command(Nth),
             whole_stream_command(Drop),
             whole_stream_command(Format),

crates/nu-cli/src/commands.rs

@@ -30,6 +30,7 @@ pub(crate) mod echo;
 pub(crate) mod enter;
 #[allow(unused)]
 pub(crate) mod evaluate_by;
+pub(crate) mod every;
 pub(crate) mod exit;
 pub(crate) mod first;
 pub(crate) mod format;
@@ -160,6 +161,7 @@ pub(crate) mod touch;
 pub(crate) use enter::Enter;
 #[allow(unused_imports)]
 pub(crate) use evaluate_by::EvaluateBy;
+pub(crate) use every::Every;
 pub(crate) use exit::Exit;
 pub(crate) use first::First;
 pub(crate) use format::Format;

crates/nu-cli/src/commands/every.rs

@@ -0,0 +1,105 @@
+use crate::commands::WholeStreamCommand;
+use crate::context::CommandRegistry;
+use crate::prelude::*;
+use nu_errors::ShellError;
+use nu_protocol::{ReturnSuccess, Signature, SyntaxShape, UntaggedValue};
+use nu_source::Tagged;
+
+pub struct Every;
+
+#[derive(Deserialize)]
+pub struct EveryArgs {
+    stride: Tagged<u64>,
+    skip: Tagged<bool>,
+}
+
+#[async_trait]
+impl WholeStreamCommand for Every {
+    fn name(&self) -> &str {
+        "every"
+    }
+
+    fn signature(&self) -> Signature {
+        Signature::build(self.name())
+            .required(
+                "stride",
+                SyntaxShape::Int,
+                "how many rows to skip between (and including) each row returned",
+            )
+            .switch(
+                "skip",
+                "skip the rows that would be returned, instead of selecting them",
+                Some('s'),
+            )
+    }
+
+    fn usage(&self) -> &str {
+        "Show (or skip) every n-th row, starting from the first one."
+    }
+
+    async fn run(
+        &self,
+        args: CommandArgs,
+        registry: &CommandRegistry,
+    ) -> Result<OutputStream, ShellError> {
+        every(args, registry).await
+    }
+
+    fn examples(&self) -> Vec<Example> {
+        vec![
+            Example {
+                description: "Get every second row",
+                example: "echo [1 2 3 4 5] | every 2",
+                result: Some(vec![
+                    UntaggedValue::int(1).into(),
+                    UntaggedValue::int(3).into(),
+                    UntaggedValue::int(5).into(),
+                ]),
+            },
+            Example {
+                description: "Skip every second row",
+                example: "echo [1 2 3 4 5] | every 2 --skip",
+                result: Some(vec![
+                    UntaggedValue::int(2).into(),
+                    UntaggedValue::int(4).into(),
+                ]),
+            },
+        ]
+    }
+}
+
+async fn every(args: CommandArgs, registry: &CommandRegistry) -> Result<OutputStream, ShellError> {
+    let registry = registry.clone();
+    let (EveryArgs { stride, skip }, input) = args.process(&registry).await?;
+    let v: Vec<_> = input.into_vec().await;
+
+    let stride_desired = if stride.item < 1 { 1 } else { stride.item } as usize;
+
+    let mut values_vec_deque = VecDeque::new();
+
+    for (i, x) in v.iter().enumerate() {
+        let should_include = if skip.item {
+            i % stride_desired != 0
+        } else {
+            i % stride_desired == 0
+        };
+
+        if should_include {
+            values_vec_deque.push_back(ReturnSuccess::value(x.clone()));
+        }
+    }
+
+    Ok(futures::stream::iter(values_vec_deque).to_output_stream())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::Every;
+
+    #[test]
+    fn examples_work_as_expected() {
+        use crate::examples::test as test_examples;
+
+        test_examples(Every {})
+    }
+}