GNU poke Manual

Table of Contents

Next: , Up: (dir)   [Contents][Index]

GNU poke Manual

This manual describes GNU poke (version 2.4, 25 July 2022).

Copyright © 2019-2022 The poke authors.

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. 

Getting Started
• Introduction:  Introducing GNU poke.
• Setting Up:  Preparing to use GNU poke. 

Using poke
• Basic Editing:  Poking bits, bytes and simple data.
• Structuring Data:  Poking your own abstractions.
• Maps and Map-files:  Working with views of data.
• Writing Pickles:  Sharing your abstractions the sane way.
• Writing Binary Utilities:  Standalone Poke programs.
• Configuration:  Tailoring the tool to your needs. 

Pickles
• Time:  Handling time.
• Colors:  Editing colors.
• Audio:  Poking audio files.
• Object Formats:  Editing executables and libraries.
• Programs:  Facilities to write binary utilities. 

poke and Emacs
• Programming Emacs Modes:  Modes to write Poke and RAS programs. 

poke and Vim
• Vim Syntax Highlighting:  Poke Syntax Highlighting in Vim. 

Reference Material
• Dot-Commands:  Commanding the tool.
• Commands:  Commands for editing data.
• The Poke Language:  Poke reference manual.
• The Standard Library:  Standard goodies for Poke programs.
• The Machine-Interface:  Communicating your program with poke. 

Internals
• The Poke Virtual Machine:  The PVM and its mysteries. 

Appendices
• Table of ASCII Codes:  The ASCII character set.
• GNU Free Documentation License:  Distribution terms for this document. 

Indexes
• Concept Index:   



Here are some other nodes which are really subnodes of the ones
already listed, mentioned here so you can get to them in one step:

Introduction
• Motivation:  Why a binary editor?
• Nomenclature:  poke, Poke and pickles.
• Invoking poke:  command line options.
• Commanding poke:  Interactive and non-interactive usage. 

Setting Up
• Setting up Hyperlinks:  GNU poke uses terminal hyperlinks.
• Simple Init File:  A simple initial ~/.pokerc. 

Basic Editing
• Binary Files:  Text vs. binary.
• Files as IO Spaces:  Poking files.
• Dumping File Contents:  A first look at a file’s bytes.
• Poking Bytes:  Reading, manipulating and writing bytes.
• Values and Variables:  Values can be stored in variables.
• From Bytes to Integers:  Building numbers with bytes.
• Big and Little Endians:  Pick your egg.
• Negative Integers:  Going behind zero.
• Weird Integers:  Incomplete bytes in numbers.
• Unaligned Integers:  IO spaces are bit-oriented.
• Integers of Different Sizes:  Promotion of integers in expressions.
• Offsets and Sizes:  United values.
• Buffers as IO Spaces:  Poking memory buffers.
• Copying Bytes:  Moving data between IO spaces.
• Saving Buffers in Files:  From memory to files.
• Character Sets:  ASCII, Unicode, …
• From Bytes to Characters:  Working with ASCII codes
• ASCII Strings:  NULL-terminated strings.
• From Strings to Characters:  Indexing strings. 

Structuring Data
• The SBM Format:  The Stupid BitMap Format
• Poking a SBM Image:  A need for abstraction.
• Modifying SBM Images:  Modifying existing data.
• Defining Types:  Abstracting data structures.
• Pickles:  Pickling useful abstractions.
• Poking Structs:  Abstracting heterogeneous data.
• How Structs are Built:  How poke builds struct values.
• Variables in Structs:  
• Functions in Structs:  
• Struct Methods:  Operations provided by built structs.
• Padding and Alignment:  Reserved fields, payloads and more.
• Dealing with Alternatives:  Conditional decoding.
• Structured Integers:  Structs that are stored like integers.
• Working with Incorrect Data:  Non-strict mapping to the rescue. 

Maps and Map-files
• Editing using Variables:  Data is usually edited mapping variables.
• poke Maps:  Maps and map-files.
• Loading Maps:  Using maps defined in files.
• Multiple Maps:  Multiple perspectives of the same data.
• Auto-map:  Loading maps automagically.
• Constructing Maps:  Creating and managing maps on the fly.
• Predefined Maps:  Collection of already-written maps. 

Writing Pickles
• Pretty-printers:  Conventions for pretty-printed output.
• Setters and Getters:  Anatomy getters and setters. 

Writing Binary Utilities
• Poke Scripts:  Using poke as an interpreter.
• Command-Line Arguments:  Handling command-line arguments.
• Exiting from Scripts:  Exit with an error status.
• Loading pickles as Modules:  Importing pickles in programs.
• elfextractor:  An example Poke binary utility.
• Filters:  Writing filters for binary data. 

Configuration
• pokerc:  User’s initialization file.
• Load Path:  Determining location of modules.
• Styling:  Changing the appearance of poke’s output. 

Time
• POSIX Time:  Encoding POSIX dates. 

Colors
• The Color Registry:  The color pickle.
• RGB24 Encoding:  Encoding colors with three bytes. 

Audio
• MP3:  Editing MP3 files. 

Programming Emacs Modes
• poke-mode:  Major mode for writing Poke programs.
• poke-map-mode:  Major mode for writing map-files.
• poke-ras-mode:  Major mode for writing RAS programs. 

Vim Syntax Highlighting
• poke.vim:  Poke syntax highlighter 

Dot-Commands
• load command:  Loading pickles.
• source command:  Executing commands in files.
• file command:  Opening and selecting file IO spaces.
• mem command:  Opening and selecting memory IO spaces.
• nbd command:  Opening and selecting NBD IO spaces.
• proc command:  Opening and selecting process IO spaces.
• ios command:  Switching between IO spaces.
• close command:  Closing IO spaces.
• doc command:  Online manual.
• editor command:  Using an external editor for input.
• info command:  Getting information about open files, etc.
• set command:  Querying and setting global options.
• vm command:  Poke Virtual Machine services.
• exit command:  Exiting poke :(
• quit command:  Likewise. 

Commands
• dump:  Binary dumps.
• copy:  Copying data around.
• save:  Save data into a file.
• extract:  Extract contents of values to buffers.
• scrabble:  Scrabble memory chunks based on patterns. 

The Poke Language
• Integers:  Whole numbers.
• Offsets:  Memory sizes and offsets.
• Strings:  NULL-terminated strings.
• Arrays:  Homogeneous collections.
• Structs:  Heterogeneous collections.
• Types:  Declaring types.
• Assignments:  Changing the value of variables.
• Compound Statements:  Sequences of statements.
• Conditionals:  Conditional statements and expressions.
• Loops:  Statements to iterate on conditions.
• Expression Statements:  Using expressions for their side-effects.
• Functions:  Procedural abstraction.
• Endianness:  Byte ordering.
• Mapping:  Accessing IO spaces.
• Exception Handling:  Dealing with exceptional conditions.
• Terminal:  Dealing with the terminal.
• Printing:  Output in Poke programs.
• Comments:  Documenting Poke programs.
• Modules:  Loading pickles from Poke programs.
• System:  Accessing the system from within Poke.
• VM:  Tweaking the PVM in Poke programs.
• Debugging:  Debugging Poke programs. 

The Standard Library
• Standard Integral Types:  int, long and the like.
• Standard Offset Types:  off64 and the like.
• Standard Units:  b, B, Kb and the like.
• Conversion Functions:  catos, atoi, etc.
• Array Functions:  Functions which deal with arrays.
• String Functions:  Functions which deal with strings.
• Sorting Functions:  qsort.
• CRC Functions:  Cyclic Redundancy Checksums.
• Dates and Times:  Processing and displaying dates and times.
• Offset Functions:  Useful functions that operate on offsets. 


The Machine-Interface
• MI overview:  Description of the MI.
• Running poke in MI mode:  Running poke with –mi
• MI transport:  Frame messages.
• MI protocol:  Messages, requests, responses, events. 

The Poke Virtual Machine
• PVM Instructions:  Virtual Machine instructions.

Next: , Up: (dir)   [Contents][Index]