doc: Add per format documentation

doc/formats.md

@@ -1,3 +1,81 @@
+## Format specific functions
+
+[./formats_collect.sh]: sh-start
+
+### bencode
+
+Supports `torepr`, ex:
+
+```
+fq -d bencode torepr file.torrent
+```
+### bson
+
+Supports `torepr`, ex:
+
+```
+fq -d bson torepr file.bson
+```
+### cbor
+
+Supports `torepr`, ex:
+
+```
+fq -d cbor torepr file.cbor
+fq -d cbor 'torepr.field' file.cbor
+fq -d cbor 'torepr | .field' file.cbor
+fq -d cbor 'torepr | grep("abc")' file.cbor
+```
+### matroska
+
+Supports `matroska_path`, ex:
+
+```
+$ fq 'matroska_path(".Segment.Tracks[0]") file.mkv
+     │00 01 02 03 04 05 06 07 08 09│0123456789│.elements[1].elements[3]{}:
+0x122│         16 54 ae 6b         │   .T.k   │  id: "Tracks" (0x1654ae6b) (A Top-Level Element of information with many tracks described.)
+     │                             │          │  type: "master" (7)
+0x122│                     4d bf   │       M. │  size: 3519
+0x122│                           bf│         .│  elements[0:3]:
+0x12c│84 cf 8b db a0 ae 01 00 00 00│..........│
+0x136│00 00 00 78 d7 81 01 73 c5 88│...x...s..│
+*    │until 0xee9.7 (3519)         │          │
+```
+
+```
+$ fq 'first(grep_by(.id == "Tracks")) | matroska_path' testfiles/test.mkv
+".Segment.Tracks"
+```
+### mp4
+
+Supports `mp4_path`, ex:
+
+```
+$ fq 'mp4_path(".moov.trak[1]")' file.mp4
+     │00 01 02 03 04 05 06 07 08 09│0123456789│.boxes[3].boxes[1]{}:
+0x4f6│                     00 00 02│       ...│  size: 573
+0x500│3d                           │=         │
+0x500│   74 72 61 6b               │ trak     │  type: "trak" (Container for an individual track or stream)
+0x500│               00 00 00 5c 74│     ...\t│  boxes[0:3]:
+0x50a│6b 68 64 00 00 00 03 00 00 00│khd.......│
+0x514│00 00 00 00 00 00 00 00 01 00│..........│
+*    │until 0x739.7 (565)          │          │
+```
+
+```
+$ fq 'first(grep_by(.type == "trak")) | mp4_path' file.mp4
+".moov.trak"
+```
+### msgpack
+
+Supports `torepr`, ex:
+
+```
+fq -d msgpack torepr file.msgpack
+```
+
+[#]: sh-end
+
 ## Supported formats
 
 [./formats_table.jq]: sh-start

doc/formats_collect.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+
+for i in $(cd $REPODIR/format && ls -1 | sort); do
+    if [ ! -e $REPODIR/format/$i/doc.md ]; then
+        continue
+    fi
+
+    echo "### $i"
+    echo
+    cat "$REPODIR/format/$i/doc.md"
+done

doc/mdsh.sh

@@ -5,6 +5,7 @@ FQ="$1"
 shift
 
 REPODIR=$(pwd)
+export REPODIR
 TEMPDIR=$(mktemp -d)
 cp -a doc/* "${TEMPDIR}"
 cp "$FQ" "${TEMPDIR}/fq"

doc/usage.md

@@ -310,9 +310,9 @@ Usage: fq [OPTIONS] [--] [EXPR] [FILE...]
 --include-path,-L PATH   Include search path
 --join-output,-j         No newline between outputs
 --monochrome-output,-M   Force monochrome output
---null-input,-n          Null input (use input and inputs to read input)
+--null-input,-n          Null input (use input and inputs functions to read input)
 --null-output,-0         Null byte between outputs
---option,-o KEY=VALUE    Set option, eg: color=true (use options to see all options)
+--option,-o KEY=VALUE    Set option, eg: color=true (use options function to see all options)
 --raw-file NAME PATH     Set variable $NAME to string content of file
 --raw-input,-R           Read raw input strings (don't decode)
 --raw-output,-r          Raw string output (without quotes)

format/bencode/doc.md

@@ -0,0 +1,5 @@
+Supports `torepr`, ex:
+
+```
+fq -d bencode torepr file.torrent
+```

format/bson/doc.md

@@ -0,0 +1,5 @@
+Supports `torepr`, ex:
+
+```
+fq -d bson torepr file.bson
+```

format/cbor/doc.md

@@ -0,0 +1,8 @@
+Supports `torepr`, ex:
+
+```
+fq -d cbor torepr file.cbor
+fq -d cbor 'torepr.field' file.cbor
+fq -d cbor 'torepr | .field' file.cbor
+fq -d cbor 'torepr | grep("abc")' file.cbor
+```

format/matroska/doc.md

@@ -0,0 +1,18 @@
+Supports `matroska_path`, ex:
+
+```
+$ fq 'matroska_path(".Segment.Tracks[0]") file.mkv
+     │00 01 02 03 04 05 06 07 08 09│0123456789│.elements[1].elements[3]{}:
+0x122│         16 54 ae 6b         │   .T.k   │  id: "Tracks" (0x1654ae6b) (A Top-Level Element of information with many tracks described.)
+     │                             │          │  type: "master" (7)
+0x122│                     4d bf   │       M. │  size: 3519
+0x122│                           bf│         .│  elements[0:3]:
+0x12c│84 cf 8b db a0 ae 01 00 00 00│..........│
+0x136│00 00 00 78 d7 81 01 73 c5 88│...x...s..│
+*    │until 0xee9.7 (3519)         │          │
+```
+
+```
+$ fq 'first(grep_by(.id == "Tracks")) | matroska_path' testfiles/test.mkv
+".Segment.Tracks"
+```

format/mp4/doc.md

@@ -0,0 +1,18 @@
+Supports `mp4_path`, ex:
+
+```
+$ fq 'mp4_path(".moov.trak[1]")' file.mp4
+     │00 01 02 03 04 05 06 07 08 09│0123456789│.boxes[3].boxes[1]{}:
+0x4f6│                     00 00 02│       ...│  size: 573
+0x500│3d                           │=         │
+0x500│   74 72 61 6b               │ trak     │  type: "trak" (Container for an individual track or stream)
+0x500│               00 00 00 5c 74│     ...\t│  boxes[0:3]:
+0x50a│6b 68 64 00 00 00 03 00 00 00│khd.......│
+0x514│00 00 00 00 00 00 00 00 01 00│..........│
+*    │until 0x739.7 (565)          │          │
+```
+
+```
+$ fq 'first(grep_by(.type == "trak")) | mp4_path' file.mp4
+".moov.trak"
+```

format/msgpack/doc.md

@@ -0,0 +1,5 @@
+Supports `torepr`, ex:
+
+```
+fq -d msgpack torepr file.msgpack
+```