3 configuration es

Configuration

[ english ] [ spanish ]

sources

Toda la magia se configura desde 3 posibles archivos en formato json. Como se menciono antes no es necesario un proyecto "node", esta tool sirve para cualquier tipo de proyecto en el que quieras tener atajos de comandos.

Los archivos son: package.json, executor.json y elNombreQueQuieras.json, la configuracion puede estar en cualquiera de los tres y es idéntica en cada caso.

package.json

Clásico archivo de prácticamente cualquier aplicación node e incluso web.

Para utilizar este archivo como fuente, simplemente agregar el atributo: executor y dentro la configuracion de los shortcuts, ejemplo:

{
  "name": "myProject",
  "version": "0.0.1",
  "scripts": {
    ...
  },
  "dependencies": {
    ...
  },
  "devDependencies": {
    ...
  },
  "executor": {
    >> your configuration here! <<
  }
}

executor.json

Archivo "standalone" con la configuracion.

Notes:

• Puede convivir con package.json, ganando desacople, sin necesidad de agregar el atributo executor en el package.json

custom.json

Archivo "standalone" configurado desde package.json para el caso de que se quiera renombrar el archivo executor.json o ubicar en otro directorio, ejemplo:

  "executor": {
    "configFile": "configs/myConf.json"
  }

Notes:

• Si se configura este archivo, se omitirá la lectura de executor.json aunque este exista en la mismo directorio.

configuration

Comencemos a ver como se configura esta tool y que opciones tiene repartidas en dos conceptos: options y data veamos cada uno.

options

Opciones de configuración al momento de ejecutar el CLI

• dry: boolean = false
  Permite ejecutar esta tool pero no ejecuta el comando, útil para "debuguear" y armar nuevos shortcuts.
• showTime: boolean = true
  Muestra el tiempo total de ejecución al final del mismo.
• showCommand: boolean = true
  Muestra el comando a ejecutar.
  Nota: Si dry esta activo, se mostrará el comando sin importar el estado de showCommand.
• useColors: boolean = true
  La salida de la consola se mostrará con colores, si interfiere con los colores de tu consola, podes cancelarlo con false
• colors: {primary, secondary, alert}
  Se pueden personalizar estos colores, utilizar esta tabla.

data

La "data" es el contenido que luego se formateara/convertirá en un string simple para la consola.

Se interpola la "data" con el delimitador: '${ }', esto permite armar strings en formato de template, donde habrá placeholders (marcas) que serán reemplazados por el valor de la variable dentro del delimitador.

Como fuente de "data" tenemos a estas 5 posibilidades: def, env, pkg, templates, shortcuts.

Notes:

• No se interpola utilizando el feature de ECMAScript, se realiza un replace.
• El orden es importante, los templates deben definirse antes de utilizarse.

Veamos cada fuente de "data":

predefined (def)

Tenemos algunos valores predefinidos (read-only) para poder usar en los templates, por el momento solo existe el cwd, luego la lista irá creciendo "on demand".
Ejemplo: echo este es el directorio actual: ${def.cwd}

• cwd: directorio actual sin importar el sistema operativo ("/" or "", problema del pasado).

environments (env)

Variables del ambiente. Simplemente utilizar el objeto env y luego el nombre de la variable.
Ejemplo: echo this is the path: ${env.path}

package.json (pkg)

Se lee el archivo package.json (si es que existe en el directorio actual) pudiendo acceder a su configuración mediante el objeto pkg:

Ejemplo: echo current version: ${pkg.version}

O los scripts pueden ser fuente para los shortcuts!:

{
  "name": "myProject",
  "version": "0.0.1",
  "scripts": {
    "build": "ng build"
  },
  "executor": {
    "shortcuts": {
      "bp": "${pkg.scripts.build} --prod --output-path build/${pkg.version}"
    }
  }
}

Esto deberia invocar al cli de angular y setear al modo de build para produccion, y por otro lado generaria un folder con la version seteada en el package.json!

templates

Son los strings que pueden servir para armar varios commandos, con la consiguiente reutilización y fácil mantenimiento.

use

Ejemplo:

templates: {
  "variable1": "foo",
  "variable2": "${variable1} bar" 
}

El resultado de variable2 sera: foo bar

features

• Se pueden hacer templates con templates anidados.
  Ejemplo: templates: {templateUnion: "${template1} and ${template2}"}
• Se pueden crear sub-objetos para tenerlo mejor organizado
  Ejemplo:

"templates": {
  "project": "myProject",
  "imageName": {
    "base": "${project}-base",
    "dev": "${project}-dev",
    "prod": "${project}-prod"
  }
}

• Se puede acceder a sub-objetos utilizando el operador: '.'
  Ejemplo: Imagen: ${imageName.prod}, resultado: myProject-prod
• Soporta infinito número de sub-objetos

shortcuts

Llegamos a los famosos "shortcuts", se interpola de la misma manera que los templates, con lo cual hereda sus features, y agrega:

• Podemos utilizar otros shortcuts como templates.
• Cada sub-objeto no solo sirve como separador como en el caso de templates, sino que también es un separador de argumentos.

Ejemplo (disculpas por lo burdo, es para que se entienda):

"templates": {
  "project": "myProject",
  "imageName": {
    "prod": "${project}-prod"
  }
},
"shortcuts": {
  changeDir: "cd ${imageName.prod}", // unico argumento
  removeDir: "rm ${imageName.prod}", // unico argumento
  dir: {                             // primer argumento
    change: "cd ${imageName.prod}",  // segundo argumento
    remove: "rm ${imageName.prod}"   // segundo argumento 
  },
  showCommandChangeDir: "echo ${dir.change}" // único argumento, y utilizaría el "." como un template 
}

Los shortcuts listos para ejecutar serian:

> x changeDir
> x removeDir
> x dir change
> x dir remove
> x showCommandChangeDir

En este ejemplo podemos ver tres casos:

• Ejecución con 1 solo argumento (x changeDir)
• Ejecución con 2 argumentos (x dir change)
• Ejecución con 1 solo argumento, pero internamente lo armo con el operador de '.' como si fuese un template. (x showCommandChangeDir)

Como podemos ver queda a nuestro exclusivo criterio como queremos formarlo, la flexibilidad está dada.

Tip: En mi caso particular, prefiero: "sujeto + verbo" en 2 argumentos. Si bien no es gramaticalmente correcto, me es más útil para alternar comandos ya que muchas veces lo que más me cambia son los verbos entre comandos (generalizando obviamente). Como el caso de e dir change

Summary

Con lo cual, para conformar los shortcuts tenemos 5 fuentes y en este orden:

1. env
2. def
3. pkg
4. templates
5. shortcuts

Notes:

• Los parámetros siguientes al último argumento se enviaran al shortcut tal cual fueron enviados.
  Ejemplo: e mochaShortcut --watch
• En el caso de no encontrar alguna key en las diferentes fuentes, terminara la ejecución con un error (exit code 1).
• Tener en cuenta el orden, en el cual también se pueden ir sobre-escribiendo las fuentes.

[ prev ][ next ]