GNU poke Manual

This manual describes GNU poke (version 3.0-dev-147-g93cec-dirty, 14 May 2023).

You can redistribute it and/or modify this manual under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

GNU poke is an interactive, extensible editor for binary data. Not limited to editing basic entities such as bits and bytes, it provides a full-fledged procedural, interactive programming language designed to describe data structures and to operate on them.

This manual describes the poke binary data editor as well as the Poke language.

1 Introduction
- 1.1 Motivation
  - 1.1.1 Decode-Compute-Encode
  - 1.1.2 Describe-Compute
- 1.2 Nomenclature
- 1.3 Invoking poke
- 1.4 Commanding poke
2 Setting Up
- 2.1 Setting up Hyperlinks
- 2.2 Simple Init File
3 Basic Editing
- 3.1 Binary Files
- 3.2 Files as IO Spaces
- 3.3 Dumping File Contents
- 3.4 Poking Bytes
- 3.5 Values and Variables
- 3.6 From Bytes to Integers
- 3.7 Big and Little Endians
- 3.8 Negative Integers
  - 3.8.1 Negative Encodings
  - 3.8.2 Signed Integers
  - 3.8.3 Mixing Signed and Unsigned Integers
- 3.9 Weird Integers
  - 3.9.1 Incomplete Bytes
  - 3.9.2 Quantum Bytenics
  - 3.9.3 Signed Weird Numbers
- 3.10 Unaligned Integers
- 3.11 Integers of Different Sizes
- 3.12 Offsets and Sizes
- 3.13 Buffers as IO Spaces
- 3.14 Copying Bytes
- 3.15 Saving Buffers in Files
- 3.16 Character Sets
- 3.17 From Bytes to Characters
  - 3.17.1 Character Literals
  - 3.17.2 Classifying Characters
  - 3.17.3 Non-printable Characters
- 3.18 ASCII Strings
  - 3.18.1 String Values
  - 3.18.2 Poking Strings
  - 3.18.3 From Characters to Strings
- 3.19 From Strings to Characters
- 3.20 Strings are not Arrays
4 Structuring Data
- 4.1 The SBM Format
- 4.2 Poking a SBM Image
- 4.3 Modifying SBM Images
- 4.4 Defining Types
  - 4.4.1 Naming your Own Abstractions
  - 4.4.2 Abstracting the Structure of Entities
- 4.5 Pickles
- 4.6 Poking Structs
- 4.7 How Structs are Built
- 4.8 Variables in Structs
- 4.9 Functions in Structs
- 4.10 Struct Methods
- 4.11 Padding and Alignment
- 4.12 Dealing with Alternatives
  - 4.12.1 BSON
  - 4.12.2 Unions are Tagged
- 4.13 Structured Integers
- 4.14 Working with Incorrect Data
5 Maps and Map-files
- 5.1 Editing using Variables
- 5.2 poke Maps
- 5.3 Loading Maps
- 5.4 Multiple Maps
- 5.5 Auto-map
- 5.6 Constructing Maps
- 5.7 Predefined Maps
6 Writing Pickles
- 6.1 Pretty-printers
  - 6.1.1 Convention for pretty-printed Output
  - 6.1.2 Pretty Printing Optional Fields
- 6.2 Setters and Getters
7 Writing Binary Utilities
- 7.1 Poke Scripts
- 7.2 Command-Line Arguments
- 7.3 Exiting from Scripts
- 7.4 Loading pickles as Modules
- 7.5 elfextractor
- 7.6 Filters
8 Configuration
- 8.1 .pokerc
- 8.2 Load Path
- 8.3 Styling
9 IOS
- 9.1 ios_dump_bytes
- 9.2 ios_copy_bytes
- 9.3 ios_save_bytes
10 Data Encodings
- 10.1 base64
11 Time
- 11.1 POSIX Time
12 Colors
- 12.1 The Color Registry
- 12.2 RGB24 Encoding
13 Audio
- 13.1 MP3
  - 13.1.1 ID3V1 Tags
    - 13.1.1.1 Song Genres
    - 13.1.1.2 The ID3V1_Tag Type
14 Object Formats
- 14.1 ELF
- 14.2 Dwarf
15 Programs
- 15.1 argp
16 poked
17 Programming Emacs Modes
- 17.1 poke-mode
- 17.2 poke-map-mode
- 17.3 poke-ras-mode
18 Vim Syntax Highlighting
- 18.1 poke.vim
19 Dot-Commands
- 19.1 .load
- 19.2 .source
- 19.3 .file
- 19.4 .mem
- 19.5 .nbd
- 19.6 .proc
- 19.7 .sub
- 19.8 .ios
- 19.9 .close
- 19.10 .doc
- 19.11 .editor
- 19.12 .info
- 19.13 .set
- 19.14 .vm
- 19.15 .exit
- 19.16 .quit
20 Commands
- 20.1 dump
  - 20.1.1 Information dump shows
  - 20.1.2 Presentation options for dump
- 20.2 copy
- 20.3 save
- 20.4 sdiff
- 20.5 extract
- 20.6 scrabble
21 The Poke Language
- 21.1 Integers
  - 21.1.1 Integer Literals
    - 21.1.1.1 The digits separator _
    - 21.1.1.2 Types of integer literals
  - 21.1.2 Characters
  - 21.1.3 Booleans
  - 21.1.4 Integer Types
  - 21.1.5 Casting Integers
  - 21.1.6 Relational Operators
  - 21.1.7 Arithmetic Operators
  - 21.1.8 Bitwise Operators
  - 21.1.9 Boolean Operators
  - 21.1.10 Integer Attributes
- 21.2 Offsets
  - 21.2.1 Offset Literals
  - 21.2.2 Offset Units
  - 21.2.3 Offset Types
  - 21.2.4 Casting Offsets
  - 21.2.5 Offset Operations
  - 21.2.6 Offset Attributes
- 21.3 Strings
  - 21.3.1 String Literals
  - 21.3.2 String Types
  - 21.3.3 String Indexing
  - 21.3.4 String Concatenation
  - 21.3.5 String Attributes
  - 21.3.6 String Formatting
- 21.4 Arrays
  - 21.4.1 Array Literals
  - 21.4.2 Array Types
    - 21.4.2.1 Writing unbounded array literals
    - 21.4.2.2 Array boundaries and closures
  - 21.4.3 Casting Arrays
  - 21.4.4 Array Constructors
  - 21.4.5 Array Comparison
  - 21.4.6 Array Indexing
    - 21.4.6.1 Indexing an array by number of element
    - 21.4.6.2 Indexing an array by offset of element
  - 21.4.7 Array Trimming
  - 21.4.8 Array Elements
  - 21.4.9 Array Concatenation
  - 21.4.10 Array Attributes
  - 21.4.11 Arrays as Stacks
- 21.5 Structs
  - 21.5.1 Struct Types
  - 21.5.2 Struct Constructors
  - 21.5.3 Struct Comparison
  - 21.5.4 Field Endianness
  - 21.5.5 Accessing Fields
  - 21.5.6 Field Constraints
  - 21.5.7 Field Initializers
  - 21.5.8 Field Labels
  - 21.5.9 Pinned Structs
  - 21.5.10 The OFFSET variable
  - 21.5.11 Integral Structs
  - 21.5.12 Unions
  - 21.5.13 Union Constructors
  - 21.5.14 Integral Unions
  - 21.5.15 Optional Fields
  - 21.5.16 Casting Structs
  - 21.5.17 Declarations in Structs
  - 21.5.18 Methods
  - 21.5.19 Struct Pretty Printers
  - 21.5.20 Computed Fields
  - 21.5.21 Struct Attributes
- 21.6 Types
  - 21.6.1 type
  - 21.6.2 The any Type
  - 21.6.3 The isa Operator
  - 21.6.4 typeof
- 21.7 Assignments
  - 21.7.1 Simple Assignments
  - 21.7.2 Bit Assignments
- 21.8 Compound Statements
- 21.9 Conditionals
  - 21.9.1 if-else
  - 21.9.2 Conditional Expressions
- 21.10 Loops
  - 21.10.1 while
  - 21.10.2 for
  - 21.10.3 for-in
- 21.11 Expression Statements
- 21.12 Functions
  - 21.12.1 Function Declarations
  - 21.12.2 Optional Arguments
  - 21.12.3 Variadic Functions
  - 21.12.4 Calling Functions
  - 21.12.5 Function Types
  - 21.12.6 Lambdas
  - 21.12.7 Function Comparison
  - 21.12.8 Function Attributes
- 21.13 Assembler
- 21.14 Endianness
  - 21.14.1 .set endian
  - 21.14.2 Endian in Fields
  - 21.14.3 Endian built-ins
- 21.15 Mapping
  - 21.15.1 IO Spaces
  - 21.15.2 The Map Operator
  - 21.15.3 Mapping Simple Types
  - 21.15.4 Mapping Structs
  - 21.15.5 Mapping Arrays
  - 21.15.6 Mapping Functions
  - 21.15.7 Non-strict Mapping
  - 21.15.8 Auto-Remapping
  - 21.15.9 Unmapping
- 21.16 Exception Handling
  - 21.16.1 Exceptions
  - 21.16.2 try-catch
  - 21.16.3 try-until
  - 21.16.4 raise
  - 21.16.5 exception-predicate
  - 21.16.6 assert
- 21.17 Terminal
  - 21.17.1 Terminal Colors
  - 21.17.2 Terminal Styling
  - 21.17.3 Terminal Hyperlinks
- 21.18 Printing
  - 21.18.1 print
  - 21.18.2 printf
- 21.19 Comments
  - 21.19.1 Multi-line comments
  - 21.19.2 Single line comments
  - 21.19.3 Vertical separator
- 21.20 Modules
- 21.21 System
  - 21.21.1 getenv
  - 21.21.2 rand
- 21.22 VM
  - 21.22.1 vm_obase
  - 21.22.2 vm_set_obase
  - 21.22.3 vm_opprint
  - 21.22.4 vm_set_opprint
  - 21.22.5 vm_oacutoff
  - 21.22.6 vm_set_oacutoff
  - 21.22.7 vm_odepth
  - 21.22.8 vm_set_odepth
  - 21.22.9 vm_oindent
  - 21.22.10 vm_set_oindent
  - 21.22.11 vm_omaps
  - 21.22.12 vm_set_omaps
  - 21.22.13 vm_omode
  - 21.22.14 vm_set_omode
  - 21.22.15 vm_autoremap
  - 21.22.16 vm_set_autoremap
- 21.23 Debugging
  - 21.23.1 __LINE__ and __FILE__
  - 21.23.2 strace
  - 21.23.3 rtrace
22 The Standard Library
- 22.1 Standard Integral Types
- 22.2 Standard Offset Types
- 22.3 Standard Units
- 22.4 Conversion Functions
- 22.5 Array Functions
  - 22.5.1 reverse
- 22.6 String Functions
- 22.7 Character Functions
- 22.8 Values Functions
  - 22.8.1 eoffset
- 22.9 IO Space Functions
  - 22.9.1 with_cur_ios
  - 22.9.2 with_temp_ios
- 22.10 Sorting Functions
  - 22.10.1 qsort
- 22.11 CRC Functions
- 22.12 Dates and Times
- 22.13 Offset Functions
  - 22.13.1 alignto
- 22.14 Other Standard Library Functions
  - 22.14.1 GNU poke Version String Parsing Utilities
23 The Poke Virtual Machine
- 23.1 PVM Instructions
Appendix A Table of ASCII Codes
Appendix B GNU Free Documentation License
Appendix C Indices
- C.1 Concept Index
- C.2 PVM Instruction Index

GNU poke Manual

Table of Contents