mirror of
https://github.com/wader/fq.git
synced 2024-12-23 13:22:58 +03:00
Merge pull request #545 from wader/doc-decode-value-build-example
doc: Add _parent for decode values and clenaup doc a bit
This commit is contained in:
commit
162cb40d9f
@ -243,7 +243,8 @@ To build, run and test from source:
|
|||||||
```sh
|
```sh
|
||||||
# build and run
|
# build and run
|
||||||
go run .
|
go run .
|
||||||
go run . -d mp3 file.mp3
|
# build and run with arguments
|
||||||
|
go run . -d mp3 . file.mp3
|
||||||
# just build
|
# just build
|
||||||
go build -o fq .
|
go build -o fq .
|
||||||
# run all tests and build binary
|
# run all tests and build binary
|
||||||
|
34
doc/usage.md
34
doc/usage.md
@ -793,27 +793,31 @@ notable is support for arbitrary-precision integers.
|
|||||||
|
|
||||||
## Decoded values
|
## Decoded values
|
||||||
|
|
||||||
When you decode something you will get a decode value. A decode value work like
|
When decoding something, using `decode` or `mp3` etc, you a decode value is returned. They behave like
|
||||||
normal jq values but has special abilities and is used to represent a tree structure of the decoded
|
normal jq values but has special abilities and is used to represent the decoded structure. Each value
|
||||||
binary data. Each value always has a name, type and a bit range.
|
always has a name, type and a bit range.
|
||||||
|
|
||||||
A value has these special keys (TODO: remove, are internal)
|
A value has these special keys (TODO: remove, are internal)
|
||||||
|
|
||||||
|
- `_actual` decoded (not symbol mapped value)
|
||||||
|
- `_bits` bits in range as a binary
|
||||||
|
- `_buffer_root` first decode value for current buffer
|
||||||
|
- `_bytes` bits in range as binary using byte units
|
||||||
|
- `_description` description of value (optional)
|
||||||
|
- `_error` error message (optional)
|
||||||
|
- `_format` name of decoded format (optional, only format root)
|
||||||
|
- `_format_root` first decode value for current format
|
||||||
|
- `_gap` is a bit range gap (was not decoded)
|
||||||
|
- `_index` index in parent array (only for values in arrays)
|
||||||
|
- `_len` bit range length (TODO: rename)
|
||||||
- `_name` name of value
|
- `_name` name of value
|
||||||
- `_value` jq value of value
|
- `_out` decoded out value
|
||||||
|
- `_parent` parent decode value
|
||||||
|
- `_path` jq path to decode value
|
||||||
|
- `_root` root decode value
|
||||||
- `_start` bit range start
|
- `_start` bit range start
|
||||||
- `_stop` bit range stop
|
- `_stop` bit range stop
|
||||||
- `_len` bit range length (TODO: rename)
|
- `_sym` symbolic value (optional)
|
||||||
- `_bits` bits in range as a binary
|
|
||||||
- `_bytes` bits in range as binary using byte units
|
|
||||||
- `_path` jq path to value
|
|
||||||
- `_gap_` value is a un-decoded gap
|
|
||||||
- `_symbol` symbolic string representation of value (optional)
|
|
||||||
- `_description` longer description of value (optional)
|
|
||||||
- `_format` name of decoded format (optional)
|
|
||||||
- `_error` error message (optional)
|
|
||||||
|
|
||||||
- TODO: unknown gaps
|
|
||||||
|
|
||||||
## Own decoders and use as library
|
## Own decoders and use as library
|
||||||
|
|
||||||
|
@ -459,22 +459,21 @@ func (dvb decodeValueBase) ToBinary() (Binary, error) {
|
|||||||
func (decodeValueBase) ExtType() string { return "decode_value" }
|
func (decodeValueBase) ExtType() string { return "decode_value" }
|
||||||
func (dvb decodeValueBase) ExtKeys() []string {
|
func (dvb decodeValueBase) ExtKeys() []string {
|
||||||
kv := []string{
|
kv := []string{
|
||||||
"_start",
|
"_actual",
|
||||||
"_stop",
|
"_bits",
|
||||||
|
"_buffer_root",
|
||||||
|
"_bytes",
|
||||||
|
"_description",
|
||||||
|
"_format_root",
|
||||||
|
"_gap",
|
||||||
"_len",
|
"_len",
|
||||||
"_name",
|
"_name",
|
||||||
"_root",
|
|
||||||
"_buffer_root",
|
|
||||||
"_format_root",
|
|
||||||
"_parent",
|
"_parent",
|
||||||
"_actual",
|
|
||||||
"_sym",
|
|
||||||
"_description",
|
|
||||||
"_path",
|
"_path",
|
||||||
"_bits",
|
"_root",
|
||||||
"_bytes",
|
"_start",
|
||||||
"_gap",
|
"_stop",
|
||||||
"_index", // TODO: only if parent is array?
|
"_sym",
|
||||||
}
|
}
|
||||||
|
|
||||||
if _, ok := dvb.dv.V.(*decode.Compound); ok {
|
if _, ok := dvb.dv.V.(*decode.Compound); ok {
|
||||||
@ -496,27 +495,6 @@ func (dvb decodeValueBase) JQValueKey(name string) any {
|
|||||||
dv := dvb.dv
|
dv := dvb.dv
|
||||||
|
|
||||||
switch name {
|
switch name {
|
||||||
case "_start":
|
|
||||||
return big.NewInt(dv.Range.Start)
|
|
||||||
case "_stop":
|
|
||||||
return big.NewInt(dv.Range.Stop())
|
|
||||||
case "_len":
|
|
||||||
return big.NewInt(dv.Range.Len)
|
|
||||||
case "_name":
|
|
||||||
return dv.Name
|
|
||||||
case "_root":
|
|
||||||
return makeDecodeValue(dv.Root(), decodeValueValue)
|
|
||||||
case "_buffer_root":
|
|
||||||
// TODO: rename?
|
|
||||||
return makeDecodeValue(dv.BufferRoot(), decodeValueValue)
|
|
||||||
case "_format_root":
|
|
||||||
// TODO: rename?
|
|
||||||
return makeDecodeValue(dv.FormatRoot(), decodeValueValue)
|
|
||||||
case "_parent":
|
|
||||||
if dv.Parent == nil {
|
|
||||||
return nil
|
|
||||||
}
|
|
||||||
return makeDecodeValue(dv.Parent, decodeValueValue)
|
|
||||||
case "_actual":
|
case "_actual":
|
||||||
switch dv.V.(type) {
|
switch dv.V.(type) {
|
||||||
case Scalarable:
|
case Scalarable:
|
||||||
@ -524,12 +502,20 @@ func (dvb decodeValueBase) JQValueKey(name string) any {
|
|||||||
default:
|
default:
|
||||||
return nil
|
return nil
|
||||||
}
|
}
|
||||||
case "_sym":
|
case "_bits":
|
||||||
switch dv.V.(type) {
|
return Binary{
|
||||||
case Scalarable:
|
br: dv.RootReader,
|
||||||
return makeDecodeValue(dv, decodeValueSym)
|
r: dv.Range,
|
||||||
default:
|
unit: 1,
|
||||||
return nil
|
}
|
||||||
|
case "_buffer_root":
|
||||||
|
// TODO: rename?
|
||||||
|
return makeDecodeValue(dv.BufferRoot(), decodeValueValue)
|
||||||
|
case "_bytes":
|
||||||
|
return Binary{
|
||||||
|
br: dv.RootReader,
|
||||||
|
r: dv.Range,
|
||||||
|
unit: 8,
|
||||||
}
|
}
|
||||||
case "_description":
|
case "_description":
|
||||||
switch vv := dv.V.(type) {
|
switch vv := dv.V.(type) {
|
||||||
@ -547,33 +533,9 @@ func (dvb decodeValueBase) JQValueKey(name string) any {
|
|||||||
default:
|
default:
|
||||||
return nil
|
return nil
|
||||||
}
|
}
|
||||||
case "_path":
|
case "_format_root":
|
||||||
return valuePath(dv)
|
// TODO: rename?
|
||||||
case "_error":
|
return makeDecodeValue(dv.FormatRoot(), decodeValueValue)
|
||||||
var formatErr decode.FormatError
|
|
||||||
if errors.As(dv.Err, &formatErr) {
|
|
||||||
return formatErr.Value()
|
|
||||||
}
|
|
||||||
return nil
|
|
||||||
case "_bits":
|
|
||||||
return Binary{
|
|
||||||
br: dv.RootReader,
|
|
||||||
r: dv.Range,
|
|
||||||
unit: 1,
|
|
||||||
}
|
|
||||||
case "_bytes":
|
|
||||||
return Binary{
|
|
||||||
br: dv.RootReader,
|
|
||||||
r: dv.Range,
|
|
||||||
unit: 8,
|
|
||||||
}
|
|
||||||
case "_format":
|
|
||||||
if dv.Format != nil {
|
|
||||||
return dv.Format.Name
|
|
||||||
}
|
|
||||||
return nil
|
|
||||||
case "_out":
|
|
||||||
return dvb.out
|
|
||||||
case "_gap":
|
case "_gap":
|
||||||
switch vv := dv.V.(type) {
|
switch vv := dv.V.(type) {
|
||||||
case Scalarable:
|
case Scalarable:
|
||||||
@ -581,6 +543,45 @@ func (dvb decodeValueBase) JQValueKey(name string) any {
|
|||||||
default:
|
default:
|
||||||
return false
|
return false
|
||||||
}
|
}
|
||||||
|
case "_len":
|
||||||
|
return big.NewInt(dv.Range.Len)
|
||||||
|
case "_name":
|
||||||
|
return dv.Name
|
||||||
|
case "_parent":
|
||||||
|
if dv.Parent == nil {
|
||||||
|
return nil
|
||||||
|
}
|
||||||
|
return makeDecodeValue(dv.Parent, decodeValueValue)
|
||||||
|
case "_path":
|
||||||
|
return valuePath(dv)
|
||||||
|
case "_root":
|
||||||
|
return makeDecodeValue(dv.Root(), decodeValueValue)
|
||||||
|
case "_start":
|
||||||
|
return big.NewInt(dv.Range.Start)
|
||||||
|
case "_stop":
|
||||||
|
return big.NewInt(dv.Range.Stop())
|
||||||
|
case "_sym":
|
||||||
|
switch dv.V.(type) {
|
||||||
|
case Scalarable:
|
||||||
|
return makeDecodeValue(dv, decodeValueSym)
|
||||||
|
default:
|
||||||
|
return nil
|
||||||
|
}
|
||||||
|
|
||||||
|
case "_error":
|
||||||
|
var formatErr decode.FormatError
|
||||||
|
if errors.As(dv.Err, &formatErr) {
|
||||||
|
return formatErr.Value()
|
||||||
|
}
|
||||||
|
return nil
|
||||||
|
case "_format":
|
||||||
|
if dv.Format != nil {
|
||||||
|
return dv.Format.Name
|
||||||
|
}
|
||||||
|
return nil
|
||||||
|
case "_out":
|
||||||
|
return dvb.out
|
||||||
|
|
||||||
case "_index":
|
case "_index":
|
||||||
if dv.Index != -1 {
|
if dv.Index != -1 {
|
||||||
return dv.Index
|
return dv.Index
|
||||||
|
1
pkg/interp/testdata/completion.fqtest
vendored
1
pkg/interp/testdata/completion.fqtest
vendored
@ -46,7 +46,6 @@ _error
|
|||||||
_format
|
_format
|
||||||
_format_root
|
_format_root
|
||||||
_gap
|
_gap
|
||||||
_index
|
|
||||||
_len
|
_len
|
||||||
_name
|
_name
|
||||||
_out
|
_out
|
||||||
|
Loading…
Reference in New Issue
Block a user