1
1
mirror of https://github.com/wader/fq.git synced 2024-12-23 05:13:30 +03:00

doc: Add some more usage examples

This commit is contained in:
Mattias Wadman 2021-12-20 15:15:43 +01:00
parent eb9698fce7
commit d02c7c42ff
2 changed files with 41 additions and 4 deletions

View File

@ -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

View File

@ -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