Documentation
¶
Overview ¶
Package idioconf loads the per-framework idiomatic.json sidecar — the declarative configuration surface of the idiomatic emitter. Where overrides.json corrects the *scanned metadata* (and therefore affects every pipeline), idiomatic.json shapes only the *idiomatic layer's* output: curated Go names for methods and C functions whose mechanical translation is poor, the set of protocols surfaced as Go delegate interfaces, and the status-code typedefs (hv_return_t, kern_return_t, …) whose returns become Go errors.
The file lives next to the framework's committed .gometa.json (metadata/frameworks/<name>/idiomatic.json), is discovered the same way as overrides.json, and follows the same rot guard: entries that no longer match any declaration produce warnings at generation time so a stale sidecar can never fail silently after an SDK re-scan.
Index ¶
- Constants
- Variables
- func Validate(file *File, framework *meta.FrameworkMeta) []string
- type DelegateConfig
- type ErrorTypedef
- type File
- func (f *File) ErrorTypedefFor(typedefName string) (ErrorTypedef, bool)
- func (f *File) FunctionGoName(cName string) (string, bool)
- func (f *File) IsDelegateExcluded(protocolName string) bool
- func (f *File) IsDelegateIncluded(protocolName string) bool
- func (f *File) IsInOutCountParam(cName, param string) bool
- func (f *File) MethodGoName(className, selector string, isClassMethod bool) (string, bool)
- type FunctionRename
- type InOutCountParam
- type MethodRename
Constants ¶
const FileName = "idiomatic.json"
FileName is the sidecar file name, discovered next to a .gometa.json file.
Variables ¶
var ErrInvalidConfig = errors.New("invalid idiomatic config entry")
ErrInvalidConfig marks a malformed idiomatic.json entry — one that can never have been correct, as opposed to a stale one (which only warns).
Functions ¶
Types ¶
type DelegateConfig ¶
type DelegateConfig struct {
Include []string `json:"include,omitempty"`
Exclude []string `json:"exclude,omitempty"`
}
DelegateConfig adjusts which protocols the emitter surfaces as Go delegate interfaces beyond its auto-detection.
type ErrorTypedef ¶
type ErrorTypedef struct {
Typedef string `json:"typedef"`
// SuccessValue is the return value that means "no error" (usually 0).
SuccessValue int64 `json:"success_value"`
// Domain names the error domain used for errkit sentinels and messages.
Domain string `json:"domain"`
// SentinelEnum optionally names the C enum whose members become exported
// errkit sentinels (e.g. hv_error → ErrBusy, ErrDenied, …).
SentinelEnum string `json:"sentinel_enum,omitempty"`
}
ErrorTypedef declares a C status-code typedef (e.g. hv_return_t) whose non-success return values the idiomatic layer converts to Go errors.
type File ¶
type File struct {
// RenameMethods assigns curated Go names to ObjC methods whose mechanical
// selector translation reads poorly (e.g. stringWithContentsOfFile:… →
// NewStringFromFile).
RenameMethods []MethodRename `json:"rename_methods,omitempty"`
// RenameFunctions assigns curated Go names to C functions.
RenameFunctions []FunctionRename `json:"rename_functions,omitempty"`
// Delegates force-includes or force-excludes protocols from delegate
// interface generation, overriding the emitter's auto-detection.
Delegates DelegateConfig `json:"delegates,omitzero"`
// ErrorTypedefs registers status-code typedefs whose function returns the
// idiomatic layer converts to Go errors.
ErrorTypedefs []ErrorTypedef `json:"error_typedefs,omitempty"`
// InOutCountParams marks specific C-function parameters as in/out element-
// count pointers.
InOutCountParams []InOutCountParam `json:"inout_count_params,omitempty"`
}
File is the parsed idiomatic.json sidecar for one framework.
func LoadAdjacent ¶
LoadAdjacent looks for an idiomatic.json next to metaPath. A missing file is not an error; found reports whether one was read.
func (*File) ErrorTypedefFor ¶
func (f *File) ErrorTypedefFor(typedefName string) (ErrorTypedef, bool)
ErrorTypedefFor returns the status-code registration for the typedef, if one is configured. Safe to call on a nil receiver.
func (*File) FunctionGoName ¶
FunctionGoName returns the curated Go name for the C function, if one is configured. Safe to call on a nil receiver.
func (*File) IsDelegateExcluded ¶
IsDelegateExcluded reports whether the protocol is force-excluded from delegate interface generation. Safe to call on a nil receiver.
func (*File) IsDelegateIncluded ¶
IsDelegateIncluded reports whether the protocol is force-included for delegate interface generation. Safe to call on a nil receiver.
func (*File) IsInOutCountParam ¶ added in v0.18.0
IsInOutCountParam reports whether the named parameter of the C function is a configured in/out element-count pointer. Safe to call on a nil receiver.
type FunctionRename ¶
FunctionRename maps one C function to a curated Go name.
type InOutCountParam ¶ added in v0.18.0
InOutCountParam marks one C-function parameter as an in/out element-count pointer — the C "(T *buf, int *count)" idiom where *count is the buffer capacity on input and the number of elements processed on output (e.g. vmnet_read / vmnet_write). Such a parameter is threaded through the idiomatic wrapper as a caller-supplied *N rather than lifted into a return value: the default emitter treats a lone scalar pointer as a pure out-parameter and declares it as a zero-initialised local, which for an in/out count would tell the framework the buffer holds zero elements and make the call a no-op. This opt-in is needed only where the count is read on input; pure out counts (the common case) are left to the default lift.
type MethodRename ¶
type MethodRename struct {
Class string `json:"class"`
Selector string `json:"selector"`
// IsClassMethod restricts the match to class methods (true) or instance
// methods (false). When omitted the rename matches either kind.
IsClassMethod *bool `json:"class_method,omitempty"`
GoName string `json:"go_name"`
}
MethodRename maps one ObjC method to a curated Go name.
Source Files