codegen

Documentation

Overview

Command codegen generates code, metadata, and documentation for ip2x.

File format

The input file starts with one or more field blocks, which define and document field names, the database columns they map to, and their preferred output type (this can be different from the storage type). These fields are untyped; types are defined in the database blocks.

// `+FieldName type` (1 time)
//   "FieldName" is the Go identifier to refer to the field by. Must be
//               unique.
//   "type"      is the type to prefer to represent the field as for this
//               db.

// `@ column` (1 time)
//   "column"    is the database column name for the field. Must be unique.

// `| godoc` (0+ times)
//   "godoc"     is a line to place in the Go documentation comment. It
//               will be automatically rewrapped when generating the code.

Next, there are one or more database blocks, which define and document IP2Location database products and their variants. Each product has its own mappings of fields to types.

// `%N ProdName DB` (1 time)
//   "N"         is the product code (must be sequential from 1, but note
//               that dummy databases without fields are allowed).
//   "ProdName"  is the product name (must be a valid Go identifier).
//   "DB"        is the database prefix.

// `| godoc` (0+ times)
//   "godoc"     is a line to place in the Go documentation comment. It
//               will be automatically rewrapped when generating the code.

// `N type ptr column` (0+ times)
//   "N"         is a sequential number starting at 1. Every time it is
//               specified, a new database variant is started. Omit it for
//               additional columns for the database variant.
//   "type"      is the type of column to add.
//   "ptr"       is either:
//                 `=` if the column contains the value itself.
//                 `*` if the column contains a 32-bit file offset to the
//                     value.
//                 `X` if the value is a virtual field which reuses the
//                     offset from the previous '*' column (skipping any '+'
//                     ones), but adds X bytes before dereferencing it.
//   "column"    is the database column name.

Currently, the recognized types are:

// `str`
//   (DB) uint8 length followed by that many bytes.
//   (Go) string, can optionally be encoded from a DB f32.

// `f32`
//   (DB) 4-byte float32.
//   (Go) float32, can optionally be parsed from a DB str.

Leading and trailing whitespace is ignored. Empty lines or lines starting with "#" are ignored.