Documentation
¶
Overview ¶
Package explain resolves compiled schema identifiers and renders their support metadata.
Design ¶
Resolution covers Go names, wire identifiers and dotted paths across generated families. Ambiguity returns all matches, and suggestions help locate nearby identifiers. Unspecified tri-state values render as a dash; missing support or target OS renders as unknown. Reasons come directly from schema/support.
The package reads compiled tables and creates no HTTP client. It describes the binary's schema pin rather than live documentation or observed device capabilities.
References ¶
- Decision record: https://github.com/deploymenttheory/go-apple-dm/blob/main/docs/research/decisions/0036-dmctl-explain-over-schema-support.md
- Decision record: https://github.com/deploymenttheory/go-apple-dm/blob/main/docs/research/decisions/0035-dmctl-structure-and-credentials.md
- Apple: https://github.com/apple/device-management/blob/release/docs/schema.md
- Schema: third_party/device-management/docs/schema.yaml (supportedOS)
Index ¶
- Variables
- func Families() []string
- func IDs(family string) ([]string, error)
- func Keys(m Match) []string
- func ParseTarget(s string) (support.Target, error)
- func Paths(family string) ([]string, error)
- func Render(w io.Writer, m Match, t support.Target) error
- func Suggest(arg, family string, limit int) []string
- type Match
- type Verdict
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotFound is an argument that matches no type, id, or key path. ErrNotFound = errors.New("explain: not found") // ErrUnknownFamily is a -family value no schema package registers. ErrUnknownFamily = errors.New("explain: unknown family") )
Errors.
var ErrTarget = errors.New("explain: bad target")
ErrTarget is a malformed -target value.
Functions ¶
func ParseTarget ¶
ParseTarget reads a target expression:
macos:15.0 ios:18,channel=user,supervised macos:26.4,channel=device,supervised,dep,user-approved
The first field is the OS, optionally with a version; the rest are comma-separated flags, or channel=device|user.
func Render ¶
Render writes the answer for one match. With a zero target it prints the per-OS support table; with a target it grades the type and every key under it, printing Result.Reason verbatim so the wording matches the rejection an enqueue would return.
func Suggest ¶
Suggest returns up to limit identifiers and key paths close to arg, for the message printed when nothing resolved.
It tries a case-insensitive substring first, then falls back to a shared prefix. The fallback is what catches a dropped or transposed letter: "DeviceLok" is not a substring of "DeviceLock", so substring matching alone would answer a typo with silence.
Types ¶
type Match ¶
type Match struct {
// Family is the schema package: commands, ddm, profiles, and so on.
Family string
// TypeName is the Go type, which is also the root of its support path.
TypeName string
// ID is the wire identifier: RequestType, PayloadType, DeclarationType,
// the dotted status path, and so on.
ID string
// Title is Apple's title for the schema.
Title string
// Schema is the YAML path under third_party/device-management.
Schema string
// Kind is the declaration family, for schema/ddm only.
Kind string
// Path is the support key path this match is rooted at. For a type it is
// TypeName; for a dotted key it is the key itself.
Path string
// Key is set when the argument named one key rather than a whole type.
Key bool
}
Match is one thing an argument resolved to.
func Resolve ¶
Resolve finds everything arg names, searching family when given and every family in order otherwise.
The order is deliberate: an exact Go type name, then a wire identifier, then a dotted support path. A wire identifier may name several types -- six schema/profiles types report com.apple.MCX -- so the result is a slice and every match is returned rather than one being chosen.
Source Files