Ţööļš

À ţööļ îš ţĥé üñîţ öƒ þŕöçéššîñĝ îñ ñéöķàþî. À ƒöŕḿàţ ŕéàđéŕ ţüŕñš à đöçüḿéñţ îñţö à šţŕéàḿ öƒ Þàŕţš, àñđ à ŵŕîţéŕ ţüŕñš ţĥé šţŕéàḿ ƃàçķ îñţö à đöçüḿéñţ. À ţööļ šîţš îñ ƃéţŵééñ: îţ ŕéàđš Þàŕţš ƒŕöḿ àñ îñþüţ çĥàññéļ, ţŕàñšƒöŕḿš ţĥéḿ, àñđ ŵŕîţéš ţĥéḿ ţö àñ öüţþüţ çĥàññéļ.

Ƃéçàüšé éṽéŕý ţööļ šþéàķš ţĥé šàḿé çĥàññéļ çöñţŕàçţ, ţööļš çöḿþöšé ƒŕééļý. À ţŕàñšļàţîöñ ŕüñ îš öñé çĥàîñ: ļéṽéŕàĝé ƒŕöḿ ḿéḿöŕý, ļööķ üþ ţéŕḿîñöļöĝý, ţŕàñšļàţé ţĥé ŕéḿàîñđéŕ, çĥéçķ ǫüàļîţý. À ḿöñöļîñĝüàļ ṽöîçé þàšš îš àñöţĥéŕ: çĥéçķ ţĥé šöüŕçé, ŕéŵŕîţé ţĥé öƒƒ-ṽöîçé ŕüñš, çĥéçķ àĝàîñ. Éàçĥ ţööļ ĥàñđļéš ţĥé Þàŕţš îţ çàŕéš àƃöüţ àñđ þàššéš ţĥé ŕéšţ ţĥŕöüĝĥ üñţöüçĥéđ. Ţĥé šàḿé îñţéŕƒàçé ƃàçķš àñàļýšîš, ţŕàñšƒöŕḿàţîöñ, éñŕîçĥḿéñţ àñđ ṽàļîđàţîöñ. Ţĥé ĝéñéŕàţéđ Ţööļ Ŕéƒéŕéñçé ļîšţš ţĥé ţööļš îñ ţĥé çüŕŕéñţ ƃüîļđ.

:::ţîþ Ţŕý à ţööļ öñ à ƒîļé Þîçķ à ţööļ, éđîţ îţš çöñƒîĝüŕàţîöñ îñ ţĥé ļîṽé ƒöŕḿ, àñđ ŕüñ îţ öñ à šàḿþļé ƒîļé ţö šéé ĥöŵ éàçĥ Ƃļöçķ çĥàñĝéš, šöüŕçé ƃéƒöŕé àñđ ţööļ öüţþüţ àƒţéŕ. Ţĥé šàḿé ƒöŕḿ ţĥàţ đŕîṽéš ţĥé çöñƒîĝüŕàţîöñ ĥéŕé îš ţĥé öñé ţĥé ṽîšüàļ éđîţöŕš àñđ ţĥé Ţööļ Ŕéƒéŕéñçé ŕéñđéŕ ƒŕöḿ ţĥé ţööļ'š šçĥéḿà. Ţĥîš ŕüñš ţĥé ŕéàļ kapi éñĝîñé îñ ýöüŕ ƃŕöŵšéŕ ṽîà ŴéƃÀššéḿƃļý. :::

Ļöàđîñĝ ţĥé îñţéŕàçţîṽé ļàƃ…

Ţĥé Ţööļ îñţéŕƒàçé

À ţööļ îš àñýţĥîñĝ ţĥàţ šàţîéš öñé šḿàļļ îñţéŕƒàçé:

type Tool interface {
    Name() string
    Description() string
    Process(ctx context.Context, in <-chan *model.Part, out chan<- *model.Part) error
    Config() ToolConfig
    SetConfig(cfg ToolConfig) error
}

Process đöéš ţĥé ŵöŕķ. À ţööļ çöñšüḿéš Þàŕţš ƒŕöḿ in, đöéš îţš ŵöŕķ, àñđ éḿîţš Þàŕţš öñ out. Îţ ƃļöçķš üñţîļ ţĥé îñþüţ çĥàññéļ îš çļöšéđ (îñþüţ éẋĥàüšţéđ) öŕ ţĥé çöñţéẋţ îš çàñçéļļéđ. Ƒļöŵ çöḿþöšîţîöñ ŕéļîéš öñ ţĥîš ḿéţĥöđ àļöñé: çĥàîñîñĝ ţööļš ḿéàñš ŵîŕîñĝ öñé ţööļ'š out çĥàññéļ ţö ţĥé ñéẋţ ţööļ'š in çĥàññéļ.

Ţĥé ŕéḿàîñîñĝ ḿéţĥöđš çàŕŕý ţĥé ţööļ'š îđéñţîţý (Name, Description) àñđ îţš çöñƒîĝüŕàţîöñ. Çöñƒîĝüŕàţîöñ îš à šḿàļļ îñţéŕƒàçé öƒ îţš öŵñ. À ţööļ çöñƒîĝ ķñöŵš ŵĥîçĥ ţööļ îţ ƃéļöñĝš ţö, ĥöŵ ţö ŕéšéţ ţö đéƒàüļţš, àñđ ĥöŵ ţö ṽàļîđàţé îţšéļƒ:

type ToolConfig interface {
    ToolName() string
    Reset()
    Validate() error
}

Þàŕţ-ţýþé đîšþàţçĥ ŵîţĥ ƂàšéŢööļ

Ḿöšţ ţööļš öñļý çàŕé àƃöüţ öñé öŕ ţŵö ķîñđš öƒ Þàŕţ, üšüàļļý Ƃļöçķš (çöñţéñţ ƃļöçķš). Ŵŕîţîñĝ ţĥé ƒüļļ çĥàññéļ ļööþ ƒöŕ éṽéŕý ţööļ ŵöüļđ ƃé ŕéþéţîţîṽé àñđ éŕŕöŕ-þŕöñé, šö ţĥé ƒŕàḿéŵöŕķ þŕöṽîđéš BaseTool, àñ éḿƃéđđàƃļé ţýþé ţĥàţ îḿþļéḿéñţš Process öñçé àñđ đîšþàţçĥéš éàçĥ Þàŕţ ţö à þéŕ-ţýþé ĥàñđļéŕ:

type PartHandler func(part *model.Part) (*model.Part, error)

type BaseTool struct {
    ToolName        string
    ToolDescription string
    Cfg             ToolConfig

    // Block handler: set exactly one. The view type bounds what it may write.
    Annotate  func(BlockView) error             // read-only: overlays / annotations / properties
    Produce func(VariantView) error            // writes target
    Transform func(BlockView) (EditPlan, error) // edit producer: the framework applier rewrites source

    // Other Part types stay untyped.
    HandleDataFn       PartHandler
    HandleMediaFn      PartHandler
    HandleLayerStartFn PartHandler
    HandleLayerEndFn   PartHandler
    HandleGroupStartFn PartHandler
    HandleGroupEndFn   PartHandler
}

À çöñçŕéţé ţööļ éḿƃéđš BaseTool àñđ šéţš öñļý ţĥé ĥàñđļéŕš îţ ñééđš. BaseTool.Process ŕéàđš éàçĥ Þàŕţ, šŵîţçĥéš öñ îţš Type, àñđ çàļļš ţĥé ḿàţçĥîñĝ ĥàñđļéŕ. Àñý ĥàñđļéŕ ļéƒţ üñšéţ îš à þàšš-ţĥŕöüĝĥ, šö ţĥé Þàŕţ ƒļöŵš ţö ţĥé öüţþüţ çĥàññéļ üñçĥàñĝéđ. Ƒöŕ Ƃļöçķš, à ţööļ šéţš öñé öƒ ţĥŕéé çàþàƃîļîţý-ţýþéđ ĥàñđļéŕš, àñđ ţĥé ṽîéŵ îţ ŕéçéîṽéš ļîḿîţš ŵĥàţ îţ ḿàý ŵŕîţé (ţĥé îḿḿüţàƃîļîţý ḿöđéļ; šéé ţĥé ţööļ-šýšţéḿ ÀĐ): Annotate ŕéàđš šöüŕçé àñđ ţàŕĝéţ ƃüţ ŵŕîţéš öñļý öṽéŕļàýš, àññöţàţîöñš, àñđ þŕöþéŕţîéš; Produce ŵŕîţéš ţĥé ţàŕĝéţ; Transform îš à ŕéàđ-öñļý éđîţ þŕöđüçéŕ ţĥàţ ŕéţüŕñš àñ éđîţ þļàñ, àñđ à ƒŕàḿéŵöŕķ-öŵñéđ àþþļîéŕ þéŕƒöŕḿš ţĥé šöüŕçé ŕéŵŕîţé, ŕéƃàšîñĝ šüŕṽîṽîñĝ öṽéŕļàýš àñđ ṽàüļţîñĝ àñý šéçŕéţš. Ţĥé ṽîéŵ ĥàš ñö ḿéţĥöđ ƒöŕ à ƒöŕƃîđđéñ ŵŕîţé, šö à ǫüàļîţý çĥéçķ çàñ'ţ ḿüţàţé ţĥé šöüŕçé ƃý àççîđéñţ, àñđ à ţŕàñšƒöŕḿéŕ ĥöļđš ñö šöüŕçé šéţţéŕ.

Ţĥé çàšé-ţŕàñšƒöŕḿ ţööļ îš à ŕéþŕéšéñţàţîṽé éẋàḿþļé. Îţ çàñ ŕéŵŕîţé ţĥé šöüŕçé, šö îţ šéţš Transform àñđ ŕéţüŕñš ţĥé ŕéŵŕîţé àš à þļàñ:

func NewCaseTransformTool(cfg *CaseTransformConfig) *tool.BaseTool {
    t := &tool.BaseTool{
        ToolName:        "case-transform",
        ToolDescription: "Transforms the case of source and/or target text",
        Cfg:             cfg,
    }
    // Transform producer: returns the case rewrite as an edit plan; the
    // framework applier rewrites the block (E-03).
    t.Transform = func(v tool.BlockView) (tool.EditPlan, error) {
        if !v.Translatable() {
            return tool.EditPlan{}, nil // pass through
        }
        conf := t.Cfg.(*CaseTransformConfig)
        convert := unicode.ToUpper
        if conf.Mode == CaseLower {
            convert = unicode.ToLower
        }
        var plan tool.EditPlan
        if conf.ApplySource {
            // The zero key is the source.
            plan.AddTextEdits(model.EditionKey{}, caseEdits(v.SourceRuns(), convert))
        }
        return plan, nil
    }
    return t
}

// caseEdits returns one in-place edit for each run of characters convert
// changes. An edit never spans an inline code, so each code stays between the
// same two characters, and each edit keeps the length of the text it replaces,
// so every overlay span keeps the characters it covered.
func caseEdits(runs []model.Run, convert func(rune) rune) []change.TextEdit {
    var edits []change.TextEdit
    at := 0 // code points of text before the current character
    for _, r := range runs {
        if r.Text == nil {
            continue // a code, a plural or a select: no edit spans it
        }
        start, changed := -1, []rune(nil)
        flush := func() {
            if start >= 0 {
                s, e := start, at
                edits = append(edits, change.TextEdit{Start: &s, End: &e, Text: string(changed)})
                start, changed = -1, nil
            }
        }
        for _, c := range r.Text.Text {
            if u := convert(c); u != c {
                if start < 0 {
                    start = at
                }
                changed = append(changed, u)
            } else {
                flush()
            }
            at++
        }
        flush()
    }
    return edits
}

Ţĥé çàšé-ţŕàñšƒöŕḿ ţööļ îñ core/tools ŵöŕķš ţĥé šàḿé ŵàý àñđ àļšö éđîţš ţĥé ţéẋţ öƒ éàçĥ þļüŕàļ ƒöŕḿ àñđ šéļéçţ çàšé.

Ŵĥéñ à ţööļ ñééđš ƒüļļ çöñţŕöļ öƒ ţĥé ļööþ, ƒöŕ éẋàḿþļé ţö àççüḿüļàţé šţàţé àçŕöšš ḿàñý Þàŕţš öŕ ţö éḿîţ ḿöŕé Þàŕţš ţĥàñ îţ çöñšüḿéš, îţ çàñ îḿþļéḿéñţ Process đîŕéçţļý îñšţéàđ öƒ üšîñĝ ţĥé ĥàñđļéŕ ƒîéļđš.

Ĥöŵ ţööļš çöḿþöšé

Çöḿþöšîţîöñ ƒöļļöŵš ƒŕöḿ ţĥé šţŕéàḿîñĝ çöñţŕàçţ. Ţĥŕéé Þàŕţš (à ļàýéŕ šţàŕţ, à ƃļöçķ, à ļàýéŕ éñđ) ƒļöŵîñĝ ţĥŕöüĝĥ à ţŵö-ţööļ çĥàîñ ļööķ ļîķé ţĥîš:

Éàçĥ ţööļ ŕüñš îñ îţš öŵñ ĝöŕöüţîñé, çöññéçţéđ ƃý ƃüƒƒéŕéđ çĥàññéļš. À ţööļ ţĥàţ đöéš ñöţ ĥàñđļé ļàýéŕ ḿàŕķéŕš ŕéļàýš ţĥéḿ, šö šţŕüçţüŕàļ çöñţéẋţ šüŕṽîṽéš ţĥé ŵĥöļé çĥàîñ éṽéñ ţĥöüĝĥ öñļý šöḿé šţàĝéš àçţ öñ îţ. Öŕđéŕîñĝ îš þŕéšéŕṽéđ: ţĥé šéĝḿéñţàţîöñ ţööļ'š öüţþüţ ƒöŕ à ƃļöçķ ŕéàçĥéš ţĥé ţŕàñšļàţîöñ ţööļ ƃéƒöŕé ţĥé ñéẋţ ƃļöçķ đöéš. Ţĥé ḿéçĥàñîçš öƒ ţĥàţ çöñçüŕŕéñçý (ĝöŕöüţîñéš, ƃüƒƒéŕéđ çĥàññéļš, ƃàçķþŕéššüŕé, éŕŕöŕ þŕöþàĝàţîöñ) àŕé çöṽéŕéđ îñ Þîþéļîñé; ĥöŵ çĥàîñš àŕé đéšçŕîƃéđ àñđ ƃüîļţ îš çöṽéŕéđ îñ Ƒļöŵš.

Ŵŕàþþîñĝ ţööļš

Ƃéçàüšé à ţööļ îš àñ îñţéŕƒàçé, öñé ţööļ çàñ ŵŕàþ àñöţĥéŕ ţö àđđ ƃéĥàṽîöŕ ŵîţĥöüţ ţĥé îññéŕ ţööļ ķñöŵîñĝ. Ţĥé ƒŕàḿéŵöŕķ üšéš ţĥîš ƒöŕ îñţŕà-ţööļ ƃļöçķ þàŕàļļéļîšḿ: ParallelBlockTool ŵŕàþš à ƃļöçķ-ĥàñđļîñĝ ţööļ àñđ ƒàñš îţš ƃļöçķ ĥàñđļéŕ öüţ àçŕöšš Ñ ĝöŕöüţîñéš ŵĥîļé þŕéšéŕṽîñĝ Þàŕţ öŕđéŕ. Ţĥîš ĥéļþš ÎÖ-ƃöüñđ ţööļš šüçĥ àš ÀÎ öŕ ḾŢ ţŕàñšļàţîöñ, ŵĥéŕé éàçĥ ƃļöçķ îš àñ îñđéþéñđéñţ ñéţŵöŕķ çàļļ. Ţĥé ŵŕàþþéŕ þŕéšéñţš ţĥé šàḿé Tool îñţéŕƒàçé, šö ţĥé ŕéšţ öƒ ţĥé ƒļöŵ îš üñàƒƒéçţéđ.

Çàţéĝöŕîéš öƒ ŵöŕķ

Ţĥé ƒŕàḿéŵöŕķ éñƒöŕçéš ñö ţööļ çàţéĝöŕîéš. Àš à ĝüîđé, ţĥé ƃüîļţ-îñ ţööļš ƒàļļ îñţö ƒîṽé ƃŕöàđ ķîñđš:

Ķîñđ	Ŵĥàţ îţ đöéš	Éẋàḿþļéš
Ţŕàñšƒöŕḿ	Ḿöđîƒý çöñţéñţ îñ þļàçé	çàšé çĥàñĝé, šéàŕçĥ/ŕéþļàçé, ŕéđàçţ
Éñŕîçĥ	Àţţàçĥ ḿàţçĥéš öŕ ḿéţàđàţà ţö çöñţéñţ	šéĝḿéñţàţîöñ, ḿéḿöŕý ļéṽéŕàĝé, ţéŕḿîñöļöĝý ļööķüþ, ÀÎ ţŕàñšļàţîöñ
Ṽàļîđàţé	Çĥéçķ çöñţéñţ ŵîţĥöüţ ḿöđîƒýîñĝ îţ	ŕüļé-ƃàšéđ çĥéçķš, ļéñĝţĥ çĥéçķš, ţéŕḿîñöļöĝý éñƒöŕçéḿéñţ
Àñàļýžé	Àççüḿüļàţé šţàţîšţîçš àçŕöšš ţĥé šţŕéàḿ	ŵöŕđ çöüñţ, ŕéþéţîţîöñ àñàļýšîš, çĥàŕàçţéŕ îñṽéñţöŕý
Çöñṽéŕţ	Àđĵüšţ ŕéþŕéšéñţàţîöñ	éñçöđîñĝ çöñṽéŕšîöñ, ļîñé-ƃŕéàķ ñöŕḿàļîžàţîöñ

Éñŕîçĥ àñđ ṽàļîđàţé ţööļš çöḿḿöñļý ŵŕîţé ţö ţĥé Ƃļöçķ àññöţàţîöñ šýšţéḿ àñđ ļéàṽé ţĥé ţéẋţ àļöñé: ţĥé recycle ţööļ àţţàçĥéš çàñđîđàţé ḿéḿöŕý ḿàţçĥéš, à çĥéçķ ţööļ àţţàçĥéš ƒîñđîñĝš, àñđ đöŵñšţŕéàḿ ţööļš öŕ àñ éđîţöŕ ŕéàđ ţĥöšé àññöţàţîöñš. Çöñţéñţ ḿéḿöŕý, ţéŕḿîñöļöĝý àñđ ṽöîçé þŕöƒîļé ŕéšüļţš ŕéàçĥ ţĥé šàḿé çöñšüḿéŕ ţĥŕöüĝĥ ţĥîš šĥàŕéđ çĥàññéļ ŵîţĥöüţ çöļļîđîñĝ.

Çöñƒîĝüŕàţîöñ àñđ šçĥéḿàš

Ţööļš ţĥàţ éẋþöšé çöñƒîĝüŕàţîöñ đéçļàŕé îţ àš à šţŕüçţ ŵîţĥ schema:"…" ƒîéļđ ţàĝš. Ţĥé ƒŕàḿéŵöŕķ đéŕîṽéš à ĴŠÖÑ-Šçĥéḿà-šţýļé đéšçŕîþţöŕ ƒŕöḿ ţĥàţ šţŕüçţ ƃý ŕéƒļéçţîöñ. Ţĥé đéšçŕîþţöŕ đŕîṽéš ţĥé ĝéñéŕàţéđ ÇĻÎ ƒļàĝš, ṽàļîđàţîöñ àñđ ţĥé çöñƒîĝüŕàţîöñ ƒöŕḿš îñ ţĥé ṽîšüàļ éđîţöŕš. À ţööļ ţĥàţ öþţš îñţö ţĥîš àđṽéŕţîšéš îţš šçĥéḿà ţĥŕöüĝĥ àñ öþţîöñàļ îñţéŕƒàçé; ţĥé ĝéñéŕàţéđ Ţööļ Ŕéƒéŕéñçé ŕéñđéŕš éàçĥ ţööļ'š þàŕàḿéţéŕš ƒŕöḿ ţĥéšé šçĥéḿàš, šö îţ ḿàţçĥéš ţĥé ƃüîļđ.

Šçŕîþţîñĝ: ŵŕîţé à ţŕàñšƒöŕḿ îñ ĴàṽàŠçŕîþţ

Ƒöŕ à ţŕàñšƒöŕḿ ţöö šḿàļļ ţö ñééđ îţš öŵñ Ĝö ţööļ, ţĥé ƃüîļţ-îñ script ţööļ ŕüñš à šḿàļļ ĴàṽàŠçŕîþţ þŕöĝŕàḿ àĝàîñšţ éàçĥ Þàŕţ. Đéƒîñé process(part), éđîţ part.block.source öŕ part.block.targets, àñđ ŕéţüŕñ ţĥé þàŕţ ţö ķééþ îţ (öŕ null ţö đŕöþ îţ). Àļţéŕñàţîṽéļý, öḿîţ ţĥé ƒüñçţîöñ àñđ ŵŕîţé ţöþ-ļéṽéļ çöđé àĝàîñšţ ţĥé ĝļöƃàļ part, çàļļîñĝ emit(part) / skip(). Üšé îţ ţö þŕöţöţýþé à öñé-öƒƒ ŕüļé. Îţ ŕüñš àñýŵĥéŕé ţĥé éñĝîñé ŕüñš, ţĥé ƃŕöŵšéŕ îñçļüđéđ, ṽîà ţĥé éḿƃéđđéđ îñţéŕþŕéţéŕ.

:::ţîþ Ŵŕîţé à šçŕîþţ, ŕüñ îţ öñ ýöüŕ ƒîļé Éđîţ ţĥé ĴàṽàŠçŕîþţ ƃéļöŵ, ŵĥéŕé process(part) ŕüñš öñçé þéŕ Þàŕţ ŵîţĥ ƒüļļ àüţöçöḿþļéţé ƒöŕ ţĥé part ÀÞÎ, öŕ ļöàđ àñ éẋàḿþļé, ţĥéñ ŕüñ îţ öñ à šàḿþļé öŕ ýöüŕ öŵñ ƒîļé àñđ ŕéàđ ţĥé þéŕ-Ƃļöçķ ƃéƒöŕé/àƒţéŕ öƒ šöüŕçé àñđ ţàŕĝéţ. :::

Ļöàđîñĝ ţĥé îñţéŕàçţîṽé ļàƃ…

Ŵĥéŕé ţööļš çöḿé ƒŕöḿ

Ƃüîļţ-îñ ţööļš ļîṽé îñ ţĥé ƒŕàḿéŵöŕķ àñđ àŕé ŕéĝîšţéŕéđ îñţö à ToolRegistry, ŵĥîçĥ ḿàþš à ţööļ ñàḿé ţö à ƒàçţöŕý. Ţööļš çàñ àļšö ƃé šüþþļîéđ ƃý þļüĝîñš, đîšçöṽéŕéđ àţ ŕüñţîḿé àñđ đîšþàţçĥéđ àš šüƃþŕöçéššéš öṽéŕ ĝŔÞÇ. À þļüĝîñ àđđš ţööļš ţö à ƃîñàŕý ŵîţĥöüţ çĥàñĝîñĝ ţĥé îñţéŕƒàçé ţĥéý šàţý.

Ŕéļàţéđ ŕéàđîñĝ

• Ţööļ Ŕéƒéŕéñçé: ţĥé ĝéñéŕàţéđ ļîšţ öƒ ƃüîļţ-îñ ţööļš àñđ ţĥéîŕ þàŕàḿéţéŕš.
• Ƒļöŵš: çöḿþöšîñĝ ţööļš îñţö à ñàḿéđ þîþéļîñé.
• Þîþéļîñé: ţĥé šţŕéàḿîñĝ éẋéçüţöŕ ţĥàţ ŕüñš ţĥé çĥàîñ.
• Îḿþļéḿéñţîñĝ à Ţööļ àñđ Ţööļ Àüţĥöŕîñĝ: ŵŕîţîñĝ ýöüŕ öŵñ.