Documentation
¶
Overview ¶
Package surface models the exported surface of the encxmobile Go package as it can be projected onto a C ABI.
It answers one question for every exported function and method: can this symbol be reached from PHP through a c-shared library and FFI, and if not, why not. The answer is a value, not a side effect — nothing is written and nothing is logged, so the PHP binding generator can diff two models byte for byte. Every list is sorted and no map ever reaches the output.
The model is built by parsing the package with go/parser. No type checking happens, which keeps the loader free of the dependency tree the target package pulls in.
Index ¶
Constants ¶
const HandleTypeName = handleTypeName
HandleTypeName lets the emitters name the receiver of a bound method the way the Go source spells it.
Variables ¶
This section is empty.
Functions ¶
func MethodCName ¶
MethodCName is the C symbol for a method on the client handle.
func SnakeCase ¶
SnakeCase converts a Go identifier to snake_case.
A run of consecutive capitals is one word, so an acronym stays glued together: ExportHAR becomes export_har and APIBaseURL becomes api_base_url. When such a run is followed by a lowercase letter the last capital starts the next word instead, which is what splits HARSnapshot into har_snapshot.
Types ¶
type Field ¶ added in v0.14.0
type Field struct {
// Name is the Go field name.
Name string
// JSONName is the object key the field marshals to. It is empty when the
// field carries `json:"-"` and therefore never appears in the JSON.
JSONName string
// OmitEmpty reports the `omitempty` option, which makes the key optional.
OmitEmpty bool
// Type is the Go spelling of the field type.
Type string
}
Field is one field of a KindJSONStruct result, as the PHP side will see it.
The three values together are the shape of the JSON object a consumer receives, so a rename, a retype or an edited json tag all change this struct and therefore every artifact derived from it.
type Func ¶
type Func struct {
// Name is the Go identifier, without the receiver.
Name string
// CName is the exported C symbol.
CName string
// Doc is the Go doc comment with the comment markers stripped.
Doc string
Params []Param
Result Result
}
Func is one bindable symbol.
type Model ¶
type Model struct {
Package string
ImportPath string
// Constructors are package functions returning the client handle.
Constructors []Func
// Methods have a *EncClient receiver.
Methods []Func
// Functions are the remaining bindable package-level functions.
Functions []Func
// Skipped holds every exported symbol that gets no C symbol.
Skipped []Skipped
}
Model is the full exported surface of one package.
type Result ¶
type Result struct {
Kind ResultKind
// Type is the value type, or TypeVoid for kinds carrying no value.
Type Type
// StructRef names the struct for KindJSONStruct and is empty otherwise.
StructRef string
// Fields is the shape of that struct in declaration order, and is empty
// for every other kind. Declaration order is part of the shape: it is
// what the emitters render, so it must not depend on the map iteration
// order of anything.
Fields []Field
}
Result describes what a bindable function returns.
type ResultKind ¶
type ResultKind int
ResultKind classifies the shape of a function's return values.
const ( // KindVoid is a function returning nothing. KindVoid ResultKind = iota // KindError is a function returning only error. KindError // KindValue is a function returning one bindable value and no error. KindValue // KindValueErr is a function returning (T, error) with T bindable. KindValueErr // KindJSONStruct is a function returning (*S, error) with S a // JSON-serializable struct of this package. KindJSONStruct // KindHandle is a function returning the opaque client handle. KindHandle )
func (ResultKind) String ¶
func (k ResultKind) String() string
String returns a stable identifier for the kind.
type Skipped ¶
type Skipped struct {
// Name is the Go identifier, prefixed with the receiver type for methods.
Name string
// Reason explains the rejection and is never empty.
Reason string
}
Skipped is an exported symbol that cannot be bound, with the reason why.
Source Files