Pular para o conteúdo principal
Versão: 0.2.0

Flags

Flags são opções nomeadas passadas com sintaxe --name=value. São ideais para configurações opcionais, switches booleanos e configurações que não seguem uma ordem estrita.

Definindo Flags​

{
    name: "deploy"
    flags: [
        {
            name: "environment"
            description: "Target environment"
            required: true
        },
        {
            name: "dry-run"
            description: "Simulate without changes"
            type: "bool"
            default_value: "false"
        },
        {
            name: "replicas"
            description: "Number of replicas"
            type: "int"
            default_value: "1"
        }
    ]
    implementations: [...]
}

Propriedades das Flags​

PropriedadeObrigatóriaDescrição
nameSimNome da flag (alfanumérico, hífens, underscores)
descriptionSimTexto de ajuda
typeNãostring, bool, int, float (padrão: string)
default_valueNãoValor padrão se não fornecido
requiredNãoDeve ser fornecido (não pode ter default)
shortNãoAlias de uma letra
validationNãoPadrão regex para o valor

Tipos​

String (Padrão)​

{name: "message", description: "Custom message", type: "string"}
// or simply
{name: "message", description: "Custom message"}
invowk cmd run --message="Hello World"

Boolean​

{name: "verbose", description: "Enable verbose output", type: "bool", default_value: "false"}
# Enable
invowk cmd run --verbose
invowk cmd run --verbose=true

# Disable (explicit)
invowk cmd run --verbose=false

Flags booleanas só aceitam true ou false.

Integer​

{name: "count", description: "Number of iterations", type: "int", default_value: "5"}
invowk cmd run --count=10
invowk cmd run --count=-1  # Negative allowed

Float​

{name: "threshold", description: "Confidence threshold", type: "float", default_value: "0.95"}
invowk cmd run --threshold=0.8
invowk cmd run --threshold=1.5e-3  # Scientific notation

Obrigatório vs Opcional​

Flags Obrigatórias​

{
    name: "target"
    description: "Deployment target"
    required: true  // Must be provided
}
# Error: missing required flag
invowk cmd deploy
# Error: flag 'target' is required

# Success
invowk cmd deploy --target=production

Flags obrigatórias não podem ter um default_value.

Flags Opcionais​

{
    name: "timeout"
    description: "Request timeout in seconds"
    type: "int"
    default_value: "30"  // Used if not provided
}
# Uses default (30)
invowk cmd request

# Override
invowk cmd request --timeout=60

Aliases Curtos​

Adicione atalhos de uma letra:

flags: [
    {name: "verbose", description: "Verbose output", type: "bool", short: "v"},
    {name: "output", description: "Output file", short: "o"},
    {name: "force", description: "Force overwrite", type: "bool", short: "f"},
]
# Long form
invowk cmd build --verbose --output=./dist --force

# Short form
invowk cmd build -v -o=./dist -f

# Mixed
invowk cmd build -v --output=./dist -f

Padrões de Validação​

Valide valores de flag com regex:

flags: [
    {
        name: "env"
        description: "Environment name"
        validation: "^(dev|staging|prod)$"
        default_value: "dev"
    },
    {
        name: "version"
        description: "Semantic version"
        validation: "^[0-9]+.[0-9]+.[0-9]+$"
    }
]
# Valid
invowk cmd deploy --env=prod --version=1.2.3

# Invalid - fails before execution
invowk cmd deploy --env=production
# Error: flag 'env' value 'production' does not match required pattern '^(dev|staging|prod)$'
Limites de Complexidade de Padrão

Padrões de validação têm limites de complexidade para prevenir problemas de desempenho:

  • Comprimento máximo do padrão: 1000 caracteres
  • Máximo de grupos aninhados: 10 níveis
  • Operadores de repetição excessivos são detectados

Padrões complexos como (a+)+ ou grupos profundamente aninhados serão rejeitados durante a validação.

Acessando em Scripts​

Flags estão disponíveis como variáveis de ambiente INVOWK_FLAG_*:

{
    name: "deploy"
    flags: [
        {name: "env", description: "Environment", required: true},
        {name: "dry-run", description: "Dry run", type: "bool", default_value: "false"},
        {name: "replica-count", description: "Replicas", type: "int", default_value: "1"},
    ]
    implementations: [{
        script: """
            echo "Environment: $INVOWK_FLAG_ENV"
            echo "Dry run: $INVOWK_FLAG_DRY_RUN"
            echo "Replicas: $INVOWK_FLAG_REPLICA_COUNT"
            
            if [ "$INVOWK_FLAG_DRY_RUN" = "true" ]; then
                echo "Would deploy $INVOWK_FLAG_REPLICA_COUNT replicas to $INVOWK_FLAG_ENV"
            else
                ./deploy.sh "$INVOWK_FLAG_ENV" "$INVOWK_FLAG_REPLICA_COUNT"
            fi
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Convenção de Nomenclatura​

Nome da FlagVariável de Ambiente
envINVOWK_FLAG_ENV
dry-runINVOWK_FLAG_DRY_RUN
output-fileINVOWK_FLAG_OUTPUT_FILE
retryCountINVOWK_FLAG_RETRYCOUNT

Hífens se tornam underscores, maiúsculo.

Exemplos do Mundo Real​

Comando de Build​

{
    name: "build"
    description: "Build the application"
    flags: [
        {name: "mode", description: "Build mode", validation: "^(debug|release)$", default_value: "debug"},
        {name: "output", description: "Output directory", short: "o", default_value: "./build"},
        {name: "verbose", description: "Verbose output", type: "bool", short: "v"},
        {name: "parallel", description: "Parallel jobs", type: "int", short: "j", default_value: "4"},
    ]
    implementations: [{
        script: """
            mkdir -p "$INVOWK_FLAG_OUTPUT"
            
            VERBOSE=""
            if [ "$INVOWK_FLAG_VERBOSE" = "true" ]; then
                VERBOSE="-v"
            fi
            
            go build $VERBOSE -o "$INVOWK_FLAG_OUTPUT/app" ./...
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Comando de Deploy​

{
    name: "deploy"
    description: "Deploy to cloud"
    flags: [
        {
            name: "env"
            description: "Target environment"
            short: "e"
            required: true
            validation: "^(dev|staging|prod)$"
        },
        {
            name: "version"
            description: "Version to deploy"
            short: "v"
            validation: "^[0-9]+.[0-9]+.[0-9]+$"
        },
        {
            name: "dry-run"
            description: "Simulate deployment"
            type: "bool"
            short: "n"
            default_value: "false"
        },
        {
            name: "timeout"
            description: "Deployment timeout (seconds)"
            type: "int"
            default_value: "300"
        }
    ]
    implementations: [{
        script: """
            echo "Deploying version ${INVOWK_FLAG_VERSION:-latest} to $INVOWK_FLAG_ENV"
            
            ARGS="--timeout=$INVOWK_FLAG_TIMEOUT"
            if [ "$INVOWK_FLAG_DRY_RUN" = "true" ]; then
                ARGS="$ARGS --dry-run"
            fi
            
            ./scripts/deploy.sh "$INVOWK_FLAG_ENV" $ARGS
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Variações de Sintaxe de Flag​

Todas funcionam:

# Equals sign
--output=./dist

# Space separator
--output ./dist

# Short with equals
-o=./dist

# Short with value
-o ./dist

# Boolean toggle (enables)
--verbose
-v

# Boolean explicit
--verbose=true
--verbose=false

Flags Reservadas​

Não use esses nomes - são reservados pelo Invowk™:

FlagCurtoDescrição
ivk-env-fileeCarregar ambiente de arquivo
ivk-env-varEDefinir variável de ambiente
ivk-env-inherit-modeHerdar variáveis de ambiente do host: none, allow, all
ivk-env-inherit-allowLista de permissão de variáveis de ambiente do host
ivk-env-inherit-denyLista de negação de variáveis de ambiente do host
ivk-workdirwSobrescrever diretório de trabalho
ivk-runtimerSobrescrever runtime
ivk-fromfOrigem para executar comando (ex.: 'invowkfile' ou nome do módulo)
ivk-force-rebuildForçar reconstrução do container
ivk-verbosevHabilitar saída verbose
ivk-configcCaminho do arquivo de configuração
ivk-interactiveiExecutar em modo interativo
helphMostrar ajuda
versionMostrar informação de versão

Além disso, os prefixos ivk-, invowk- e i- são reservados para flags do sistema. Não use esses prefixos para nomes de flags.

Melhores Práticas​

  1. Use nomes descritivos: --output-dir não --od
  2. Forneça padrões quando faz sentido: Reduzir entradas obrigatórias
  3. Adicione validação para valores restritos: Falhe rápido em entrada inválida
  4. Use aliases curtos para flags comuns: -v, -o, -f
  5. Flags booleanas devem ter padrão false: Comportamento opt-in

Próximos Passos​