Provider CLI

Provider CLI

Un plugin si aggancia al ciclo di vita della build - config, nav, markdown/HTML di pagina, post-build. Un provider CLI è il punto di estensione gemello per il ciclo di vita dei comandi: consente a un modulo BoxLang installato e attivato di registrare propri comandi bxSites <verbo>, senza toccare bx-sites stesso.

Stesso modello di attivazione di un plugin - un modulo aderisce per nome, tramite l'array plugins proprio di bxsites.yaml:

plugins: [ myBxSitesAddon ]

Un modulo può implementare models/BxSitesPlugin.bx, models/BxSitesCliProvider.bx, entrambi, o nessuno dei due - installare/ attivare un modulo è un passaggio; quali contratti implementa decide cosa estende realmente.

Scrivere un provider CLI

Un provider CLI richiede esattamente una cosa oltre ai soliti box.json/ModuleConfig.bx: una classe models/BxSitesCliProvider.bx che espone un singolo metodo verbs(), che restituisce uno struct nome verbo → informazioni di dispatch:

// models/BxSitesCliProvider.bx
class {

	struct function verbs() {
		return {
			"cloud:publish" : {
				class       : "models.cli.cloud.Publish@myBxSitesAddon",
				description : "Build (if needed) and publish via the configured deploy target"
			},
			"cloud:status" : {
				class       : "models.cli.cloud.Status@myBxSitesAddon",
				description : "Show license/entitlement and last deploy status"
			}
		}
	}

}

Ogni classe di dispatch segue esattamente la stessa forma di una classe di verbo del core sotto il proprio models/cli/ di bx-sites - una struct function run( struct options ) che restituisce { exitCode, message }:

class {
	struct function run( struct options ) {
		// arguments.options carries the same parsed-flags-plus-projectRoot
		// shape every core verb receives - see the CLI reference's
		// "How dispatch works" section.
		return { exitCode : 0, message : "Published #arguments.options.projectRoot#" }
	}
}

Il suffisso @myBxSitesAddon è obbligatorio

Un semplice percorso puntato come "models.cli.cloud.Publish" si risolve solo relativamente al root di modulo proprio di bx-sites - è così che i verbi del core fanno riferimento a models/cli/Build.bx e simili, ma non può raggiungere un modulo diverso. Le proprie classi di verbo di un provider devono sempre fornire da sé il proprio suffisso @<mapping> di modulo, esattamente come mostrato sopra. Questo è anche il motivo per cui registrarsi nella tabella letterale dei verbi propria di bx-sites non è qualcosa in cui un provider possa intrufolarsi - il percorso della classe deve nominare esplicitamente il proprio modulo.

Nomi dei verbi: a token singolo e a due token ("composto")

Un nome di verbo viene registrato come un'unica stringa unita da due punti, la stessa convenzione già usata dal core per post:new/i18n:status/page:rename. bxSites accetta anche l'equivalente di due token argv separati da spazio come zucchero sintattico sulla stessa registrazione - bxSites cloud publish e bxSites cloud:publish fanno dispatch in modo identico, non appena "cloud:publish" è un nome di verbo registrato. Non c'è un meccanismo di registrazione a due parole separato da imparare; registra "cloud:publish", ed entrambe le grafie funzionano gratuitamente.

Precedenza e modalità di fallimento

• Il core vince sempre. Se un provider registra un nome di verbo che entra in collisione con uno dei verbi incorporati di bx-sites, viene fatto il dispatch del verbo del core e la voce del provider viene ignorata silenziosamente - un provider può aggiungere nuovi comandi, mai oscurarne uno esistente.
• In caso di collisione tra due provider, vince il primo. Se due moduli attivati diversi registrano lo stesso nome di verbo, vince quello elencato per primo nell'array plugins di bxsites.yaml.
• La discovery non rompe mai il dispatch del core. Un bxsites.yaml mancante o malformato, un progetto che non esiste ancora (es. eseguire --help fuori da qualsiasi progetto), un modulo elencato in plugins senza un proprio BxSitesCliProvider.bx, o un provider il cui verbs() genera un errore - nessuno di questi casi è un errore. Vengono trattati tutti allo stesso modo di un plugin non attivato: la tabella dei verbi del core resta semplicemente intatta, e ogni comando incorporato di bxSites continua a funzionare da solo.

Un esempio minimo

myBxSitesAddon/
├── box.json                          # boxlang.moduleName is what bxsites.yaml's [plugins] references
├── ModuleConfig.bx                    # a normal BoxLang module descriptor
└── models/
    ├── BxSitesPlugin.bx               # optional - build-lifecycle hooks, see plugins.md
    ├── BxSitesCliProvider.bx          # verbs()
    └── cli/
        └── cloud/
            ├── Publish.bx             # run( options )
            └── Status.bx              # run( options )

Vedi Plugin per il lato ciclo di vita della build dello stesso modulo, e la guida di riferimento CLI per ogni verbo che il core stesso include.