Merge pull request #545 from wader/doc-decode-value-build-example

doc: Add _parent for decode values and clenaup doc a bit

README.md

@@ -243,7 +243,8 @@ To build, run and test from source:
 ```sh
 # build and run
 go run .
-go run . -d mp3 file.mp3
+# build and run with arguments
+go run . -d mp3 . file.mp3
 # just build
 go build -o fq .
 # run all tests and build binary

doc/usage.md

@@ -793,27 +793,31 @@ notable is support for arbitrary-precision integers.
 
 ## Decoded values
 
-When you decode something you will get a decode value. A decode value work like
-normal jq values but has special abilities and is used to represent a tree structure of the decoded
-binary data. Each value always has a name, type and a bit range.
+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 the decoded structure. Each value
+always has a name, type and a bit range.
 
 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
-- `_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
 - `_stop` bit range stop
-- `_len` bit range length (TODO: rename)
-- `_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
+- `_sym` symbolic value (optional)
 
 ## Own decoders and use as library
 

pkg/interp/decode.go

@@ -459,22 +459,21 @@ func (dvb decodeValueBase) ToBinary() (Binary, error) {
 func (decodeValueBase) ExtType() string { return "decode_value" }
 func (dvb decodeValueBase) ExtKeys() []string {
 	kv := []string{
-		"_start",
-		"_stop",
+		"_actual",
+		"_bits",
+		"_buffer_root",
+		"_bytes",
+		"_description",
+		"_format_root",
+		"_gap",
 		"_len",
 		"_name",
-		"_root",
-		"_buffer_root",
-		"_format_root",
 		"_parent",
-		"_actual",
-		"_sym",
-		"_description",
 		"_path",
-		"_bits",
-		"_bytes",
-		"_gap",
-		"_index", // TODO: only if parent is array?
+		"_root",
+		"_start",
+		"_stop",
+		"_sym",
 	}
 
 	if _, ok := dvb.dv.V.(*decode.Compound); ok {
@@ -496,27 +495,6 @@ func (dvb decodeValueBase) JQValueKey(name string) any {
 	dv := dvb.dv
 
 	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":
 		switch dv.V.(type) {
 		case Scalarable:
@@ -524,12 +502,20 @@ func (dvb decodeValueBase) JQValueKey(name string) any {
 		default:
 			return nil
 		}
-	case "_sym":
-		switch dv.V.(type) {
-		case Scalarable:
-			return makeDecodeValue(dv, decodeValueSym)
-		default:
-			return nil
+	case "_bits":
+		return Binary{
+			br:   dv.RootReader,
+			r:    dv.Range,
+			unit: 1,
+		}
+	case "_buffer_root":
+		// TODO: rename?
+		return makeDecodeValue(dv.BufferRoot(), decodeValueValue)
+	case "_bytes":
+		return Binary{
+			br:   dv.RootReader,
+			r:    dv.Range,
+			unit: 8,
 		}
 	case "_description":
 		switch vv := dv.V.(type) {
@@ -547,33 +533,9 @@ func (dvb decodeValueBase) JQValueKey(name string) any {
 		default:
 			return nil
 		}
-	case "_path":
-		return valuePath(dv)
-	case "_error":
-		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 "_format_root":
+		// TODO: rename?
+		return makeDecodeValue(dv.FormatRoot(), decodeValueValue)
 	case "_gap":
 		switch vv := dv.V.(type) {
 		case Scalarable:
@@ -581,6 +543,45 @@ func (dvb decodeValueBase) JQValueKey(name string) any {
 		default:
 			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":
 		if dv.Index != -1 {
 			return dv.Index

pkg/interp/testdata/completion.fqtest

@@ -46,7 +46,6 @@ _error
 _format
 _format_root
 _gap
-_index
 _len
 _name
 _out