From 919d396ffb5ab4325c90f8213878dfdf02d68291 Mon Sep 17 00:00:00 2001
From: "Benjamin E. Seidenberg" <astronut@dlgeek.net>
Date: Fri, 20 Sep 2024 16:57:02 -0700
Subject: [PATCH] Add `filter` command as an alias for map(select())

I (and I've heard others) use this often enough that it makes sense to have more user-friendly syntax.
---
 docs/content/manual/dev/manual.yml | 15 +++++++++++++++
 jq.1.prebuilt                      | 20 +++++++++++++++++++-
 src/builtin.jq                     |  1 +
 tests/man.test                     |  4 ++++
 4 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/docs/content/manual/dev/manual.yml b/docs/content/manual/dev/manual.yml
index c98b3ca259..60de10c12a 100644
--- a/docs/content/manual/dev/manual.yml
+++ b/docs/content/manual/dev/manual.yml
@@ -1207,6 +1207,21 @@ sections:
             output: ['{"id": "second", "val": 2}']
 
 
+      - title: "`filter(boolean_expression)`"
+        body: |
+
+          The function `filter(f)` takes an array and returns an array
+          with only the elements for which `f` returns true for that element.
+
+          The behavior is identical to map(select(`f`)) but it's more user
+          friendly.
+
+        examples:
+          - program: 'filter(. >= 2)'
+            input: '[1,5,3,0,7]'
+            output: ['[5,3,7]']
+
+
       - title: "`arrays`, `objects`, `iterables`, `booleans`, `numbers`, `normals`, `finites`, `strings`, `nulls`, `values`, `scalars`"
         body: |
 
diff --git a/jq.1.prebuilt b/jq.1.prebuilt
index 1d1424f68d..3811d46669 100644
--- a/jq.1.prebuilt
+++ b/jq.1.prebuilt
@@ -1,5 +1,5 @@
 .
-.TH "JQ" "1" "August 2024" "" ""
+.TH "JQ" "1" "September 2024" "" ""
 .
 .SH "NAME"
 \fBjq\fR \- Command\-line JSON processor
@@ -1235,6 +1235,24 @@ jq \'\.[] | select(\.id == "second")\'
 .
 .IP "" 0
 .
+.SS "filter(boolean_expression)"
+The function \fBfilter(f)\fR takes an array and returns an array with only the elements for which \fBf\fR returns true for that element\.
+.
+.P
+The behavior is identical to map(select(\fBf\fR)) but it\'s more user friendly\.
+.
+.IP "" 4
+.
+.nf
+
+jq \'filter(\. >= 2)\'
+   [1,5,3,0,7]
+=> [5,3,7]
+.
+.fi
+.
+.IP "" 0
+.
 .SS "arrays, objects, iterables, booleans, numbers, normals, finites, strings, nulls, values, scalars"
 These built\-ins select only inputs that are arrays, objects, iterables (arrays or objects), booleans, numbers, normal numbers, finite numbers, strings, null, non\-null values, and non\-iterables, respectively\.
 .
diff --git a/src/builtin.jq b/src/builtin.jq
index aa33cd4b75..5ec2404487 100644
--- a/src/builtin.jq
+++ b/src/builtin.jq
@@ -2,6 +2,7 @@ def halt_error: halt_error(5);
 def error(msg): msg|error;
 def map(f): [.[] | f];
 def select(f): if f then . else empty end;
+def filter(f): map(select(f));
 def sort_by(f): _sort_by_impl(map([f]));
 def group_by(f): _group_by_impl(map([f]));
 def unique: group_by(.) | map(.[0]);
diff --git a/tests/man.test b/tests/man.test
index 6c5eba390a..ccd731f262 100644
--- a/tests/man.test
+++ b/tests/man.test
@@ -313,6 +313,10 @@ map(select(. >= 2))
 [{"id": "first", "val": 1}, {"id": "second", "val": 2}]
 {"id": "second", "val": 2}
 
+filter(. >= 2)
+[1,5,3,0,7]
+[5,3,7]
+
 .[]|numbers
 [[],{},1,"foo",null,true,false]
 1