wader/fq
1
1
Fork 0
mirror of https://github.com/wader/fq.git synced 2024-11-24 03:05:22 +03:00
Code Issues Projects Releases Wiki Activity

Merge pull request #65 from wader/doc-dev-help

Browse Source 
doc,dev: Add some more decoder implementation help
This commit is contained in:
Mattias Wadman 2022-01-09 17:03:42 +01:00 committed by GitHub
commit a0ccde99a5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 15 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
doc/dev.md
View File

@ -4,20 +4,29 @@
- fq uses a readline fork that can be found at https://github.com/wader/readline/tree/fq (the "fq" branch) - fq uses a readline fork that can be found at https://github.com/wader/readline/tree/fq (the "fq" branch)
- cli readline uses raw mode so blocks ctrl-c to become a SIGINT - cli readline uses raw mode so blocks ctrl-c to become a SIGINT
## Decoder implementation help ## Implement a decoder
### Steps to add new decoder
- Create a directory `format/<name>`
- Copy some similar decoder, `format/format/bson.go` is quite small, to `format/<name>/<name>.go`
- Cleanup and fill in the register struct, rename `format.BSON` and don't forget to change the string constant.
- Add an import to `format/all/all.go`
## Things to think about
- Main goal in the end is to produce a tree that is user-friendly and easy to work with. - Main goal in the end is to produce a tree that is user-friendly and easy to work with.
Prefer a nice and easy to use tree over nice decoder implementation. Prefer a nice and easy to use tree over nice decoder implementation.
- Use same names, symbols, constant number base etc as in specification. - Use same names, symbols, constant number base etc as in specification. But prefer lowercase to jq/JSON-ish.
- Decode only ranges you know what it is. If possible let "parent" decide what to do with unknown - Decode only ranges you know what they are. If possible let "parent" decide what to do with unknown
bits by using `*Decode*Len/Range/Limit` functions. bits by using `*Decode*Len/Range/Limit` functions. fq will automatically add "unknown" fields.
- Try to no decode too much as one value. - Try to no decode too much as one value.
A length encoded int could be two fields, but maybe a length prefixed string should be one. A length encoded int could be two fields, but maybe a length prefixed string should be one.
Flags can be struct with bit-fields. Flags can be struct with bit-fields.
- Map as many value as possible to more usage symbolic values. - Map as many value as possible to more usage symbolic values.
- Endian inherited inside one format decoder, defaults to big endian for new format decoder - Endian is inherited inside one format decoder, defaults to big endian for new format decoder
- Make sure zero length or no frames etc found fails decoding - Make sure zero length or no frames etc found fails decoding
- Try validate input to make it non-ambiguous with other decoders - If in the probe group make sure to validate input to make it non-ambiguous with other decoders
- Try keep decoder code as declarative as possible - Try keep decoder code as declarative as possible
- Split into multiple sub formats if possible. Makes it possible to use them separately. - Split into multiple sub formats if possible. Makes it possible to use them separately.
- Validate/Assert - Validate/Assert