diff --git a/documentation/.generator/pages/presentation/how-it-works.md b/documentation/.generator/pages/presentation/how-it-works.md index 4ac7752f..c956dcf8 100644 --- a/documentation/.generator/pages/presentation/how-it-works.md +++ b/documentation/.generator/pages/presentation/how-it-works.md @@ -2,11 +2,17 @@ Ele funciona como um analisador automatizado de linha de comando, permitindo que o programador se concentre nas regras de negócios de sua aplicação. +Para isso, você pode escolher 3 maneiras de trabalho: + +* Método **Main tipado**: Equivale ao modelo tradicional `Main(string[] args)`, mas de forma tipada. +* **Propriedades**: Cada propriedade será transformada em argumentos. +* **Métodos**: Cada método será transformado em um sub-comando: **Ação** + Além disso, ele dispõe de um recurso para simular um prompt de comando dentro do proprio Visual Studio, eliminando a necessidade de testar sua aplicação fora do ambiente de desenvolvimento. Outros recursos essênciais como `help`, `verbose`, `error handling` e outros também são suportados. -**Exemplo simples:** +**Exemplo de `Main-typed`:** ```csharp namespace Example.Initialization.Simple @@ -25,53 +31,113 @@ namespace Example.Initialization.Simple // and its public properties and methods will be available for use. public class MyCommand : Command { - public string MyProperty { get; set; } - - // This signature "Main()" is reserved to process arguments/properties. - public void Main() + // This signature "Main(...)" is reserved to process arguments fastly. + public void Main(string myArgument, int? myArgument2 = null) { - // verify if property was inputed by user. - if (MyProperty != null) - { - this.App.Console.Write(string.Format("Main MyProperty='{0}'", MyProperty)); - } - } + // this arg is obrigatory + this.App.Console.Write(string.Format("myArgument='{0}'", myArgument)); - public void MyAction(bool a) - { - this.App.Console.Write(string.Format("MyAction a='{0}'", a)); + // verify if property was inputed by user. + if (myArgument2 != null) + this.App.Console.Write(string.Format("myArgument2='{0}'", myArgument2)); } } } ``` -**Testes no prompt de comando:** +_Testes em um prompt externo:_ ``` C:\Users\MyUser> MyApp.exe help ... the automatic help text will be shown ... -C:\Users\MyUser> MyApp.exe --my-property value -Main MyProperty='value' +C:\Users\MyUser> MyApp.exe --my-argument "value" +myArgument='value' -C:\Users\MyUser> MyApp.exe my-action -a -MyAction a='True' +C:\Users\MyUser> MyApp.exe --my-argument "value" --my-argument2 1000 +myArgument='value' +myArgument2='1000' ``` -**Testes no Visual Studio usando o simulador de console:** +_Testes no Visual Studio usando o simulador de console:_ ``` cmd> help ... the automatic help text will be shown ... -cmd> --my-property value -Main MyProperty='value' +cmd> --my-argument "value" +myArgument='value' + +cmd> --my-argument "value" --my-argument2 1000 +myArgument='value' +myArgument2='1000' +``` + +**Exemplo de uso com propriedades:** + +```csharp +namespace Example.Initialization.Simple +{ + using SysCommand.ConsoleApp; + + public class Program + { + public static int Main(string[] args) + { + return App.RunApplication(); + } + } + + public class MyCommand : Command + { + public string MyArgument { get; set; } + // This signature "Main()" is reserved to process properties. + public void Main() + { + if (MyArgument != null) + this.App.Console.Write(string.Format("Main MyArgument='{0}'", MyArgument)); + } + } +} +``` + +``` +cmd> --my-argument value +Main MyArgument='value' +``` + +**Exemplo de ações:** + +```csharp +namespace Example.Initialization.Simple +{ + using SysCommand.ConsoleApp; + + public class Program + { + public static int Main(string[] args) + { + return App.RunApplication(); + } + } + + public class MyCommand : Command + { + public void MyAction(bool a) + { + this.App.Console.Write(string.Format("MyAction a='{0}'", a)); + } + } +} +``` + +``` cmd> my-action -a MyAction a='True' ``` -**_Note que não existe nenhum código de parse, seu código está limpo e pronto para receber comandos._** +**_Note que não existe nenhum código de analise em nenhum exemplo, seu código está limpo e pronto para receber comandos._** ### Entenda melhor... @@ -81,13 +147,13 @@ Tecnicamente, existem quatro entidades de domínio que são a base do framework: É o contexto da aplicação, onde uma `App` contém diversos `Commands`. É representada pela classe `SysCommand.ConsoleApp.App` e deve ser a primeira entidade a ser configurada em seu método `Main(string[] args)`. -A inicialização do contexto da aplicação pode ser feita de duas formas, por uma instância da class `App` ou através do método estático `App.RunApplication` que fornece um recurso de simulação de console que ajuda você a testar seus inputs dentro do próprio Visual Studio, sem a necessidade de executar seu ".exe" em um console externo, basta apertar o _Play_. Veja e . +A inicialização do contexto da aplicação pode ser feita de duas formas, por uma instância da class `App` ou através do método estático `App.RunApplication` que fornece um recurso de simulação de console que ajuda você a testar seus inputs dentro do próprio Visual Studio, sem a necessidade de executar seu ".exe" em um console externo, basta apertar o _Play_. Saiba mais: , . **`Command`** Os comandos representam um agrupamento de funcionalidades do mesmo contexto de negócio, similar aos _Controllers do MVC_. Programaticamente eles são representadas por classes que herdam de `SysCommand.ConsoleApp.Command`. Cada instância de `Command` terá acesso ao contexto corrente pela propriedade `this.App`. -Por padrão, o sistema tenta encontrar, de forma automática, qualquer classe que extenda de `Command`, sendo assim não é necessário especifica-los na inicializaçao, embora isso seja possível. Veja e . +Por padrão, o sistema tenta encontrar, de forma automática, qualquer classe que extenda de `Command`, sendo assim não é necessário especifica-los na inicializaçao, embora isso seja possível. Saiba mais: , . **`Argument`** @@ -95,7 +161,7 @@ Os argumentos representam o meio mais básico de uma aplicação console, são o Do lado do usuário, nenhuma sintaxe especial foi criada, os padrões mais conhecidos foram implementados. Os argumentos longos são acessados com o prefixo `--` e são acompanhados do nome do argumento. Os argumentos curtos são acessados com um traço `-` ou uma barra `/` e são acompanhados de apenas um caracter. Os valores dos argumentos devem estar na frente do nome do argumento separados por um espaço ` ` ou `:` ou `=`. Inputs posicionais também são suportados, possibilitando a omissão do nome do argumento. -Por padrão, todas as propriedades publicas de seu `Command` serão habilitadas para serem `arguments`. Veja , , e . +Por padrão, todas as propriedades publicas de seu `Command` serão habilitadas para serem `arguments`. Saiba mais: , , , . **`Action`** @@ -103,9 +169,9 @@ Representam ações iguais as _Actions dos Controllers do MVC_. Programaticament Seu uso é similar ao modo como usamos os recursos do `git` como: `git add -A`; `git commit -m "comments"`, onde `add` e `commit` seriam o nome das ações e `-A`, `-m` seus respectivos argumentos. -Ainda é possível omitir o nome da ação no input do usuário. Esse recurso é chamado de `Método Padrão` e se assemelha muito com o uso de propriedades. +Ainda é possível omitir o nome da ação no input do usuário. Esse recurso é chamado de **Método Padrão** e se assemelha muito com o uso de propriedades. -Por padrão, todos os métodos publicos de seu `Command` serão habilitadas para serem `actions`. Veja , e . +Por padrão, todos os métodos publicos de seu `Command` serão habilitadas para serem `actions`. Saiba mais: , , . **Exemplo avançado:** @@ -299,13 +365,13 @@ Commit **Saiba mais...** -* Note que os tipos primitivos de cada propriedade estão configurados como `Nullable`. Isso é importante para ter condições de identificar que o usuário inseriu uma determinada propriedade. Veja . +* Note que os tipos primitivos de cada propriedade estão configurados como `Nullable`. Isso é importante para ter condições de identificar que o usuário inseriu uma determinada propriedade. Saiba mais: . * Todos os tipos primitivos do .NET, Enums, Enums Flags e Collections são suportados. Veja o tópico de . -* Use `App.Console.Write()`, `App.Console.Error()` (entre outros) para imprimir seus outputs e usufruir de recursos como o `verbose`. Veja . -* Você pode utilizar o retorno dos métodos como `output`, inclusive o método reservado `Main()`. Ou use `void` se não quiser usar esse recurso. Veja . -* Se desejar, customize seus `arguments` ou `actions` usando os atributos `ArgumentAttribute` e `ActionAttribute`. Você pode customizar diversos atributos como nomes, texto de ajuda e dentro outros. Veja e . -* Você pode usar métodos com o mesmo nome (sobrecargas) para definir diferentes `actions`. Elas podem ser chamadas no prompt de comando com o mesmo nome, mas os argumentos definirão qual o método a ser chamado, igual ocorre em `c#`. Veja +* Use `App.Console.Write()`, `App.Console.Error()` (entre outros) para imprimir seus outputs e usufruir de recursos como o `verbose`. Saiba mais: . +* Você pode utilizar o retorno dos métodos como `output`, inclusive o método reservado `Main()`. Ou use `void` se não quiser usar esse recurso. Saiba mais: . +* Se desejar, customize seus `arguments` ou `actions` usando os atributos `ArgumentAttribute` e `ActionAttribute`. Você pode customizar diversos atributos como nomes, texto de ajuda e dentro outros. Saiba mais: e . +* Você pode usar métodos com o mesmo nome (sobrecargas) para definir diferentes `actions`. Elas podem ser chamadas no prompt de comando com o mesmo nome, mas os argumentos definirão qual o método a ser chamado, igual ocorre em `c#`. Saiba mais: * Opte por usar o método `int Program.Main(string[] args)` com retorno, assim você pode retornar o status code para o console. (ERROR=1 ou SUCCESS=0). -* Existe também o suporte nativo para gerar o texto de ajuda. Veja . +* Existe também o suporte nativo para gerar o texto de ajuda. Saiba mais: . Esse foi apenas um resumo, para conhecer mais sobre esse projeto veja a nossa . \ No newline at end of file diff --git a/documentation/en.md b/documentation/en.md index fdb66a33..03383a1d 100644 --- a/documentation/en.md +++ b/documentation/en.md @@ -82,7 +82,7 @@ public App( ``` * `commandsTypes`: Specifies the `Command` types that will be used throughout the process. If it is `null` then the system will try to automatically any class that extend from `Command` . Understand better in [Specifying the types of commands](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#specifying-commands). -* `enableMultiAction`: Turns the `MultiAction` behavior. By default, this behavior will be enabled. Understand better in [Multi-action](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#using-the-multi-action-feature). +* `enableMultiAction`: Turns the `MultiAction` behavior. By default, this behavior is enabled. Understand better in [Multi-action](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#using-the-multi-action-feature). * `addDefaultAppHandler`: If `false` so does not create the event handler that is responsible for the `outputs` standard engine and `erros` controls, and among others. The default is `true` . Understand better in [Event control](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#events). ## Booting with the console Simulator diff --git a/documentation/pt-br.md b/documentation/pt-br.md index 40a71e46..986be930 100644 --- a/documentation/pt-br.md +++ b/documentation/pt-br.md @@ -82,7 +82,7 @@ public App( ``` * `commandsTypes`: Especifica os tipos dos `Command` que serão utilizados em todo o processo. Caso seja `null` então o sistema buscará automáticamente qualquer classe que extenda de `Command`. Entenda melhor em [Especificando os tipos de comandos](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#specifying-commands). -* `enableMultiAction`: Liga ou desliga o comportamento de `MultiAction`. Por padrão, esse comportamento estará habilidado. Entenda melhor em [Multi-action](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#using-the-multi-action-feature). +* `enableMultiAction`: Liga ou desliga o comportamento de `MultiAction`. Por padrão, esse comportamento estará habilitado. Entenda melhor em [Multi-action](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#using-the-multi-action-feature). * `addDefaultAppHandler`: Caso seja `false` então NÃO cria o handler de eventos que é responsável pelo mecanismo padrão de `outputs` e controles de `erros` e dentre outros. O padrão é `true`. Entenda melhor em [Controle de eventos](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#events). ## Inicializando com o simulador de console diff --git a/readme-pt-br.md b/readme-pt-br.md index 196ea0fb..8b8d3f5a 100644 --- a/readme-pt-br.md +++ b/readme-pt-br.md @@ -43,11 +43,17 @@ Install-Package SysCommand Ele funciona como um analisador automatizado de linha de comando, permitindo que o programador se concentre nas regras de negócios de sua aplicação. +Para isso, você pode escolher 3 maneiras de trabalho: + +* Método **Main tipado**: Equivale ao modelo tradicional `Main(string[] args)`, mas de forma tipada. +* **Propriedades**: Cada propriedade será transformada em argumentos. +* **Métodos**: Cada método será transformado em um sub-comando: **Ação** + Além disso, ele dispõe de um recurso para simular um prompt de comando dentro do proprio Visual Studio, eliminando a necessidade de testar sua aplicação fora do ambiente de desenvolvimento. Outros recursos essênciais como `help`, `verbose`, `error handling` e outros também são suportados. -**Exemplo simples:** +**Exemplo de `Main-typed`:** ```csharp namespace Example.Initialization.Simple @@ -66,53 +72,113 @@ namespace Example.Initialization.Simple // and its public properties and methods will be available for use. public class MyCommand : Command { - public string MyProperty { get; set; } - - // This signature "Main()" is reserved to process arguments/properties. - public void Main() + // This signature "Main(...)" is reserved to process arguments fastly. + public void Main(string myArgument, int? myArgument2 = null) { - // verify if property was inputed by user. - if (MyProperty != null) - { - this.App.Console.Write(string.Format("Main MyProperty='{0}'", MyProperty)); - } - } + // this arg is obrigatory + this.App.Console.Write(string.Format("myArgument='{0}'", myArgument)); - public void MyAction(bool a) - { - this.App.Console.Write(string.Format("MyAction a='{0}'", a)); + // verify if property was inputed by user. + if (myArgument2 != null) + this.App.Console.Write(string.Format("myArgument2='{0}'", myArgument2)); } } } ``` -**Testes no prompt de comando:** +_Testes em um prompt externo:_ ``` C:\Users\MyUser> MyApp.exe help ... the automatic help text will be shown ... -C:\Users\MyUser> MyApp.exe --my-property value -Main MyProperty='value' +C:\Users\MyUser> MyApp.exe --my-argument "value" +myArgument='value' -C:\Users\MyUser> MyApp.exe my-action -a -MyAction a='True' +C:\Users\MyUser> MyApp.exe --my-argument "value" --my-argument2 1000 +myArgument='value' +myArgument2='1000' ``` -**Testes no Visual Studio usando o simulador de console:** +_Testes no Visual Studio usando o simulador de console:_ ``` cmd> help ... the automatic help text will be shown ... -cmd> --my-property value -Main MyProperty='value' +cmd> --my-argument "value" +myArgument='value' + +cmd> --my-argument "value" --my-argument2 1000 +myArgument='value' +myArgument2='1000' +``` + +**Exemplo de uso com propriedades:** + +```csharp +namespace Example.Initialization.Simple +{ + using SysCommand.ConsoleApp; + + public class Program + { + public static int Main(string[] args) + { + return App.RunApplication(); + } + } + + public class MyCommand : Command + { + public string MyArgument { get; set; } + // This signature "Main()" is reserved to process properties. + public void Main() + { + if (MyArgument != null) + this.App.Console.Write(string.Format("Main MyArgument='{0}'", MyArgument)); + } + } +} +``` + +``` +cmd> --my-argument value +Main MyArgument='value' +``` + +**Exemplo de ações:** + +```csharp +namespace Example.Initialization.Simple +{ + using SysCommand.ConsoleApp; + + public class Program + { + public static int Main(string[] args) + { + return App.RunApplication(); + } + } + + public class MyCommand : Command + { + public void MyAction(bool a) + { + this.App.Console.Write(string.Format("MyAction a='{0}'", a)); + } + } +} +``` + +``` cmd> my-action -a MyAction a='True' ``` -**_Note que não existe nenhum código de parse, seu código está limpo e pronto para receber comandos._** +**_Note que não existe nenhum código de analise em nenhum exemplo, seu código está limpo e pronto para receber comandos._** ### Entenda melhor... @@ -122,13 +188,13 @@ Tecnicamente, existem quatro entidades de domínio que são a base do framework: É o contexto da aplicação, onde uma `App` contém diversos `Commands`. É representada pela classe `SysCommand.ConsoleApp.App` e deve ser a primeira entidade a ser configurada em seu método `Main(string[] args)`. -A inicialização do contexto da aplicação pode ser feita de duas formas, por uma instância da class `App` ou através do método estático `App.RunApplication` que fornece um recurso de simulação de console que ajuda você a testar seus inputs dentro do próprio Visual Studio, sem a necessidade de executar seu ".exe" em um console externo, basta apertar o _Play_. Veja [Iniciando](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#class-app) e [Inicializando com o simulador de console](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#initializing-by-static-method). +A inicialização do contexto da aplicação pode ser feita de duas formas, por uma instância da class `App` ou através do método estático `App.RunApplication` que fornece um recurso de simulação de console que ajuda você a testar seus inputs dentro do próprio Visual Studio, sem a necessidade de executar seu ".exe" em um console externo, basta apertar o _Play_. Saiba mais: [Iniciando](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#class-app) , [Inicializando com o simulador de console](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#initializing-by-static-method). **`Command`** Os comandos representam um agrupamento de funcionalidades do mesmo contexto de negócio, similar aos _Controllers do MVC_. Programaticamente eles são representadas por classes que herdam de `SysCommand.ConsoleApp.Command`. Cada instância de `Command` terá acesso ao contexto corrente pela propriedade `this.App`. -Por padrão, o sistema tenta encontrar, de forma automática, qualquer classe que extenda de `Command`, sendo assim não é necessário especifica-los na inicializaçao, embora isso seja possível. Veja [Tipos de comandos](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#kind-of-commands) e [Especificando os tipos de comandos](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#specifying-commands). +Por padrão, o sistema tenta encontrar, de forma automática, qualquer classe que extenda de `Command`, sendo assim não é necessário especifica-los na inicializaçao, embora isso seja possível. Saiba mais: [Tipos de comandos](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#kind-of-commands) , [Especificando os tipos de comandos](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#specifying-commands). **`Argument`** @@ -136,7 +202,7 @@ Os argumentos representam o meio mais básico de uma aplicação console, são o Do lado do usuário, nenhuma sintaxe especial foi criada, os padrões mais conhecidos foram implementados. Os argumentos longos são acessados com o prefixo `--` e são acompanhados do nome do argumento. Os argumentos curtos são acessados com um traço `-` ou uma barra `/` e são acompanhados de apenas um caracter. Os valores dos argumentos devem estar na frente do nome do argumento separados por um espaço ` ` ou `:` ou `=`. Inputs posicionais também são suportados, possibilitando a omissão do nome do argumento. -Por padrão, todas as propriedades publicas de seu `Command` serão habilitadas para serem `arguments`. Veja [Trabalhando com propriedades](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#properties), [Escolha manual de propriedades via atributo](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#properties-ignore-public), [Input](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#input) e [Tipos suportados](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#support-types). +Por padrão, todas as propriedades publicas de seu `Command` serão habilitadas para serem `arguments`. Saiba mais: [Trabalhando com propriedades](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#properties), [Escolha manual de propriedades via atributo](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#properties-ignore-public), [Input](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#input), [Tipos suportados](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#support-types). **`Action`** @@ -144,9 +210,9 @@ Representam ações iguais as _Actions dos Controllers do MVC_. Programaticament Seu uso é similar ao modo como usamos os recursos do `git` como: `git add -A`; `git commit -m "comments"`, onde `add` e `commit` seriam o nome das ações e `-A`, `-m` seus respectivos argumentos. -Ainda é possível omitir o nome da ação no input do usuário. Esse recurso é chamado de `Método Padrão` e se assemelha muito com o uso de propriedades. +Ainda é possível omitir o nome da ação no input do usuário. Esse recurso é chamado de **Método Padrão** e se assemelha muito com o uso de propriedades. -Por padrão, todos os métodos publicos de seu `Command` serão habilitadas para serem `actions`. Veja [Trabalhando com métodos](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#methods), [Ignorar métodos publicos por uma escolha manual usando atributo](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#methods-ignore-public) e [Métodos padrão](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#methods-default). +Por padrão, todos os métodos publicos de seu `Command` serão habilitadas para serem `actions`. Saiba mais: [Trabalhando com métodos](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#methods), [Ignorar métodos publicos por uma escolha manual usando atributo](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#methods-ignore-public), [Métodos padrão](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#methods-default). **Exemplo avançado:** @@ -340,14 +406,14 @@ Commit **Saiba mais...** -* Note que os tipos primitivos de cada propriedade estão configurados como `Nullable`. Isso é importante para ter condições de identificar que o usuário inseriu uma determinada propriedade. Veja [Trabalhando com propriedades](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#properties). +* Note que os tipos primitivos de cada propriedade estão configurados como `Nullable`. Isso é importante para ter condições de identificar que o usuário inseriu uma determinada propriedade. Saiba mais: [Trabalhando com propriedades](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#properties). * Todos os tipos primitivos do .NET, Enums, Enums Flags e Collections são suportados. Veja o tópico de [Tipos suportados](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#support-types). -* Use `App.Console.Write()`, `App.Console.Error()` (entre outros) para imprimir seus outputs e usufruir de recursos como o `verbose`. Veja [Verbose](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#verbose). -* Você pode utilizar o retorno dos métodos como `output`, inclusive o método reservado `Main()`. Ou use `void` se não quiser usar esse recurso. Veja [Output](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#output). -* Se desejar, customize seus `arguments` ou `actions` usando os atributos `ArgumentAttribute` e `ActionAttribute`. Você pode customizar diversos atributos como nomes, texto de ajuda e dentro outros. Veja [Customizando os nomes dos argumentos](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#properties-customizing-name) e [Customizando nomes de ações e argumentos](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#methods-customizing-names). -* Você pode usar métodos com o mesmo nome (sobrecargas) para definir diferentes `actions`. Elas podem ser chamadas no prompt de comando com o mesmo nome, mas os argumentos definirão qual o método a ser chamado, igual ocorre em `c#`. Veja [Sobrecargas](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#methods-overloads) +* Use `App.Console.Write()`, `App.Console.Error()` (entre outros) para imprimir seus outputs e usufruir de recursos como o `verbose`. Saiba mais: [Verbose](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#verbose). +* Você pode utilizar o retorno dos métodos como `output`, inclusive o método reservado `Main()`. Ou use `void` se não quiser usar esse recurso. Saiba mais: [Output](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#output). +* Se desejar, customize seus `arguments` ou `actions` usando os atributos `ArgumentAttribute` e `ActionAttribute`. Você pode customizar diversos atributos como nomes, texto de ajuda e dentro outros. Saiba mais: [Customizando os nomes dos argumentos](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#properties-customizing-name) e [Customizando nomes de ações e argumentos](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#methods-customizing-names). +* Você pode usar métodos com o mesmo nome (sobrecargas) para definir diferentes `actions`. Elas podem ser chamadas no prompt de comando com o mesmo nome, mas os argumentos definirão qual o método a ser chamado, igual ocorre em `c#`. Saiba mais: [Sobrecargas](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#methods-overloads) * Opte por usar o método `int Program.Main(string[] args)` com retorno, assim você pode retornar o status code para o console. (ERROR=1 ou SUCCESS=0). -* Existe também o suporte nativo para gerar o texto de ajuda. Veja [Help](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#help). +* Existe também o suporte nativo para gerar o texto de ajuda. Saiba mais: [Help](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#help). Esse foi apenas um resumo, para conhecer mais sobre esse projeto veja a nossa [Documentação](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/pt-br.md#documentation). diff --git a/readme.md b/readme.md index 2fc0836f..f30fc21d 100644 --- a/readme.md +++ b/readme.md @@ -43,11 +43,17 @@ Install-Package SysCommand It works like an automated command-line parser, allowing the programmer to focus on the business rules of your application. +To do this, you can choose 3 ways of working: + +* **Main-typed**method: this is equivalent to the traditional model `Main(string[] args)` , but typed. +* **Properties**: each property will be transformed into arguments. +* **Methods**: each method will be transformed into a sub-command: **Action** + In addition, he has a feature to simulate a command prompt within the own Visual Studio, eliminating the need to test your application outside of the development environment. Other essential resources as `help` , `verbose` , `error handling` and others are also supported. -**Simple example:** +**`Main-typed`Example:** ```csharp namespace Example.Initialization.Simple @@ -66,53 +72,113 @@ namespace Example.Initialization.Simple // and its public properties and methods will be available for use. public class MyCommand : Command { - public string MyProperty { get; set; } - - // This signature "Main()" is reserved to process arguments/properties. - public void Main() + // This signature "Main(...)" is reserved to process arguments fastly. + public void Main(string myArgument, int? myArgument2 = null) { - // verify if property was inputed by user. - if (MyProperty != null) - { - this.App.Console.Write(string.Format("Main MyProperty='{0}'", MyProperty)); - } - } + // this arg is obrigatory + this.App.Console.Write(string.Format("myArgument='{0}'", myArgument)); - public void MyAction(bool a) - { - this.App.Console.Write(string.Format("MyAction a='{0}'", a)); + // verify if property was inputed by user. + if (myArgument2 != null) + this.App.Console.Write(string.Format("myArgument2='{0}'", myArgument2)); } } } ``` -**Tests at the command prompt:** +_Tests at a command prompt:_ ``` C:\Users\MyUser> MyApp.exe help ... the automatic help text will be shown ... -C:\Users\MyUser> MyApp.exe --my-property value -Main MyProperty='value' +C:\Users\MyUser> MyApp.exe --my-argument "value" +myArgument='value' -C:\Users\MyUser> MyApp.exe my-action -a -MyAction a='True' +C:\Users\MyUser> MyApp.exe --my-argument "value" --my-argument2 1000 +myArgument='value' +myArgument2='1000' ``` -**Tests in Visual Studio using the Simulator from console:** +_Tests in Visual Studio using the Simulator from console:_ ``` cmd> help ... the automatic help text will be shown ... -cmd> --my-property value -Main MyProperty='value' +cmd> --my-argument "value" +myArgument='value' + +cmd> --my-argument "value" --my-argument2 1000 +myArgument='value' +myArgument2='1000' +``` + +**Example of use with properties:** + +```csharp +namespace Example.Initialization.Simple +{ + using SysCommand.ConsoleApp; + + public class Program + { + public static int Main(string[] args) + { + return App.RunApplication(); + } + } + + public class MyCommand : Command + { + public string MyArgument { get; set; } + // This signature "Main()" is reserved to process properties. + public void Main() + { + if (MyArgument != null) + this.App.Console.Write(string.Format("Main MyArgument='{0}'", MyArgument)); + } + } +} +``` + +``` +cmd> --my-argument value +Main MyArgument='value' +``` + +**Example of actions:** + +```csharp +namespace Example.Initialization.Simple +{ + using SysCommand.ConsoleApp; + + public class Program + { + public static int Main(string[] args) + { + return App.RunApplication(); + } + } + + public class MyCommand : Command + { + public void MyAction(bool a) + { + this.App.Console.Write(string.Format("MyAction a='{0}'", a)); + } + } +} +``` + +``` cmd> my-action -a MyAction a='True' ``` -**_Note that there is no parse code, your code is clean and ready to receive commands._** +**_Note that there is no analysis code in any example, your code is clean and ready to receive commands._** ### Understand better ... @@ -122,13 +188,13 @@ Technically, there are four entities that are the basis of the framework: Is the application context, where a `App` contains several `Commands` . Is represented by the class `SysCommand.ConsoleApp.App` and must be the first entity to be configured in your `Main(string[] args)` method. -The application context initialization can be done in two ways, by an instance of the class `App` or static method `App.RunApplication` that provides a console simulation feature that helps you test your inputs inside the Visual Studio itself, without the need to perform your ".exe" in an external console, just press the _Play_. Veja [Starting](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#class-app) e [Booting with the console Simulator](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#initializing-by-static-method). +The application context initialization can be done in two ways, by an instance of the class `App` or static method `App.RunApplication` that provides a console simulation feature that helps you test your inputs inside the Visual Studio itself, without the need to perform your ".exe" in an external console, just press the _Play_. Learn more: [Starting](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#class-app) , [Booting with the console Simulator](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#initializing-by-static-method). **`Command`** The commands represent a grouping of features the same business context, similar to _MVC Controllers_. Programmatically they are represented by classes that inherit from `SysCommand.ConsoleApp.Command` . Each `Command` instance will have access to the current context by the property `this.App` . -By default, the system attempts to find automatically, any class that extend to `Command` , therefore it is not necessary to specify them in the boot record, although this is possible. Veja [Types of commands](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#kind-of-commands) e [Specifying the types of commands](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#specifying-commands). +By default, the system attempts to find automatically, any class that extend to `Command` , therefore it is not necessary to specify them in the boot record, although this is possible. Learn more: [Types of commands](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#kind-of-commands) , [Specifying the types of commands](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#specifying-commands). **`Argument`** @@ -136,7 +202,7 @@ The arguments represent the most basic of a console application, are known `--ar User-side, no special syntax was created, known standards were implemented. The long arguments are accessed with the prefix `--` and are accompanied by the name of the argument. The short arguments are accessed with a dash `-` or a `/` bar and are accompanied by only one character. The values of the arguments must be in front of the argument name separated by a space ` ` or `:` or `=` . Positional inputs are also supported, allowing the omission of the name of the argument. -By default, all public properties of your `Command` are enabled to be `arguments` . Veja [Working with properties](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#properties), [Manual choice of properties via attribute](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#properties-ignore-public), [Input](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#input) e [Supported types](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#support-types). +By default, all public properties of your `Command` are enabled to be `arguments` . Saiba mais: [Working with properties](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#properties), [Manual choice of properties via attribute](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#properties-ignore-public), [Input](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#input), [Supported types](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#support-types). **`Action`** @@ -144,9 +210,9 @@ Represent the same actions the _Actions of MVC Controllers_. Programmatically re Its use is similar to the way we use `git` resources like: `git add -A` ; `git commit -m "comments"` , where `add` and `commit` would be the name of the stock and `-A` , `-m` their respective arguments. -It is still possible to omit the name of the action in the user input. This feature is called `Método Padrão` and resembles a lot with the use of properties. +It is still possible to omit the name of the action in the user input. This feature is called the **default method** and looks very similar to the use of properties. -By default, all public methods of your `Command` are enabled to be `actions` . Veja [Working with methods](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#methods), [Ignore public methods by a manual choice using attribute](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#methods-ignore-public) e [Standard methods](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#methods-default). +By default, all public methods of your `Command` are enabled to be `actions` . Learn more: [Working with methods](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#methods), [Ignore public methods by a manual choice using attribute](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#methods-ignore-public), [Standard methods](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#methods-default). **Advanced example:** @@ -340,14 +406,14 @@ Commit **Learn more ...** -* Note, the primitive types for each property are configured as `Nullable` . It is important to be able to identify that the user entered a particular property. See [Working with properties](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#properties). +* Note, the primitive types for each property are configured as `Nullable` . It is important to be able to identify that the user entered a particular property. Learn more: [Working with properties](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#properties). * All primitive types of .NET, Enums, Enums and Flags Collections are supported. See the [Supported types](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#support-types)topic. -* Use `App.Console.Write()` , `App.Console.Error()` (among others) to print their outputs and enjoy features like the `verbose` . See [Verbose](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#verbose). -* You can use the return of methods like `output` , including the reserved method `Main()` . Or use `void` If you do not want to use this feature. See [Output](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#output). -* If you want, customize your `arguments` or `actions` using the attributes `ArgumentAttribute` and `ActionAttribute` . You can customize several attributes such as names, help text and in others. Veja [Customizing the names of the arguments](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#properties-customizing-name) e [Customizing actions names and arguments](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#methods-customizing-names). -* You can use methods with the same name (overloads) to define different `actions` . They can be invoked from the command prompt with the same name, but the arguments define which method to invoke, the same occurs in `c#` . See[Overloads](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#methods-overloads) +* Use `App.Console.Write()` , `App.Console.Error()` (among others) to print their outputs and enjoy features like the `verbose` . Learn more: [Verbose](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#verbose). +* You can use the return of methods like `output` , including the reserved method `Main()` . Or use `void` If you do not want to use this feature. Learn more: [Output](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#output). +* If you want, customize your `arguments` or `actions` using the attributes `ArgumentAttribute` and `ActionAttribute` . You can customize several attributes such as names, help text and in others. Learn more: [Customizing the names of the arguments](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#properties-customizing-name) and [Customizing actions names and arguments](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#methods-customizing-names). +* You can use methods with the same name (overloads) to define different `actions` . They can be invoked from the command prompt with the same name, but the arguments define which method to invoke, the same occurs in `c#` . Learn more:[Overloads](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#methods-overloads) * Choose to use the `int Program.Main(string[] args)` return method, so you can return the status code for the console. (ERROR = 1 or SUCCESS = 0). -* There is also native support to generate help text. See [Help](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#help). +* There is also native support to generate help text. Learn more: [Help](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#help). This was just a summary, for more on this see our project [Documentation](https://github.com/juniorgasparotto/SysCommand/blob/master/documentation/en.md#documentation).