From e7619aeece7f30e52063591d1487874c36b2dec7 Mon Sep 17 00:00:00 2001
From: Anton Medvedev <anton@medv.io>
Date: Thu, 9 Jan 2020 12:49:19 +0300
Subject: [PATCH] Update DOCS.md

---
 DOCS.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/DOCS.md b/DOCS.md
index 1dbb187b..e469becf 100644
--- a/DOCS.md
+++ b/DOCS.md
@@ -5,6 +5,7 @@
   + [Anonymous function](#anonymous-function)
   + [Binding](#binding)
   + [Dot](#dot)
+  + [Map](#map)
   + [Chaining](#chaining)
   + [Updating](#updating)
   + [Edit-in-place](#edit-in-place)
@@ -71,6 +72,50 @@ $ echo '{"foo": "bar"}' | fx .
 }
 ```
 
+### Map
+
+One of the frequent operations is mapping some function on an array. For example, to extract some values.
+
+```
+[
+  {
+    "author": {
+      "name": "antonmedv"
+    }, 
+    ...
+  },
+  {...},
+  {...},
+  ...
+]
+```
+
+And we want to collect names of each object in array. We can do this by mapping anonymous function:
+
+```bash
+$ cat ... | fx '.map(x => x.author.name)'
+```
+
+Or we can do the same by using `@` prefix:
+
+```bash
+$ cat ... | fx @.author.name
+[
+  "antonmedv",
+  ...
+]
+```
+
+Expression followed by `@` symbol will be mapped to each element of array.
+
+> Note what `@` can be applied to map object values.
+> ```bash
+> $ echo '{"foo": 1, "bar": 2}' | fx @+1
+> [2, 3]
+> ```
+> 
+> Also note what symbol `@` alone is equivalent of `Object.values` function.
+
 ### Chaining
 
 You can pass any number of anonymous functions for reducing JSON: