From d02c7c42ff23e27cdc2a798ebd41f5e5e42672d8 Mon Sep 17 00:00:00 2001
From: Mattias Wadman <mattias.wadman@gmail.com>
Date: Mon, 20 Dec 2021 15:15:43 +0100
Subject: [PATCH] doc: Add some more usage examples

---
 README.md    |  8 ++++----
 doc/usage.md | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 3fb9df09..b0552f33 100644
--- a/README.md
+++ b/README.md
@@ -5,11 +5,11 @@ Tool, language and decoders for inspecting binary data.
 ![fq demo](doc/demo.svg)
 
 In most cases fq works the same way as jq but instead of reading JSON it reads binary data.
-The result is a JSON compatbile structures where each value has a bit range, symbolic
+The result is a JSON compatible structures where each value has a bit range, symbolic
 interpretations and know how to be presented in a useful way.
 
 **NOTE:** fq is early in development and many things are missing, broken or do not make sense.
-That also means there is a great opportunity to help out.
+That also means there is a great opportunity to help out!
 
 ## Goals
 
@@ -21,13 +21,13 @@ That also means there is a great opportunity to help out.
 
 ## Usage
 
-Basic usage is: `fq . file`.
+Basic usage is `fq . file`.
 
 For details see [usage.md](doc/usage.md)
 
 ## Install
 
-Download archive from [releases](https://github.com/wader/fq/releases) page for your
+Download [release](https://github.com/wader/fq/releases) for your
 platform, unarchive it and move the executable to `PATH` etc.
 
 ### Homebrew
diff --git a/doc/usage.md b/doc/usage.md
index a4080d45..d67e7fa0 100644
--- a/doc/usage.md
+++ b/doc/usage.md
@@ -69,6 +69,43 @@ $
 
 Use Ctrl-D to exits, Ctrl-C to interrupt current evaluation.
 
+## Example usages
+
+Show AVC SPS difference between two mp4 files:
+```sh
+fq -n 'def f: .. | select(format=="avc_sps"); diff(input|f; input|f)' a.mp4 b.mp4
+```
+`-n` tells fq to not have an implicit `input`, `f` is function to select out some interesting value, call `diff` with two arguments,
+decoded value for `a.mp4` and `b.mp4` filtered thru `f`.
+
+Extract first JPEG found in file:
+```sh
+fq 'first(.. | select(format=="jpeg")) | tobytes' file > file.jpeg
+```
+Recursively look for first value that is a `jpeg` decode value root. Use `tobytes` to get bytes buffer for value. Redirect bytes to a file.
+
+Sample size histogram:
+```sh
+fq '.. | select(.type=="stsz")? as $stsz | .entries | count | max_by(.[1])[1] as $m | ($stsz | topath | path_to_expr), (.[] | "\(.[0]): \((100*.[1]/$m)*"=") \(.[1])") | println' file.mp4
+```
+Recursively look for a all sample size boxes "stsz" and use `?` to ignore errors when doing `.type` on arrays etc. Save reference to box, count unique values, save the max, output the path to the box and output a historgram scaled to 0-100.
+
+Find TCP streams that looks like HTTP GET requests in PCAP file:
+```sh
+fq '.tcp_connections | grep("GET /.* HTTP/1.?")' file.pcap
+```
+Use `grep` to recursively find strings matching a regexp.
+
+Widest PNG in a directory:
+```sh
+$ fq -rn '[inputs | [input_filename, first(.chunks[] | select(.type=="IHDR") | .width)]] | max_by(.[1]) | .[0]' *.png
+```
+
+What values include the byte at position 0x123?
+```sh
+$ fq '.. | select(scalars and in_bytes_range(0x123))' file
+```
+
 ## The jq langauge
 
 fq is based on the [jq language](https://stedolan.github.io/jq/) and for basic usage its syntax