Format Converter (Delphi)

Conversor de formatos (JSON, XML, etc) para Delphi.

Format converter (JSON, XML, etc.) for Delphi.

Índice

1. Instalação/Configuração
2. Uso
3. Sitemap
4. Estrutura
5. Workgroup
6. Dependências
7. Contribuir
8. Checklist para Contribuir
9. Créditos
10. Licença
11. Padronização de Código
12. TODO
13. Árvore do Projeto

" class="reference-link">Instalação/Configuração

*Clique na Imagem para visualizar o vídeo

Correção: Substituir “$(variavel_criada)\dcu” por “$(variavel_criada)\output” no library path

" class="reference-link">Uso

Como Usar

*Clique na Imagem para visualizar o vídeo

Exemplo de Uso

*Clique na Imagem para visualizar o vídeo

Recursos

• JSONtoXML

  • stringToString: Converte um JSON em forma de String em um XML em forma de string (string);
    • Parametrização
      • strContent: JSON à converter (string);
  • stringToFile: Converte um JSON em forma de String em um arquivo XML (boolean);
    • Parametrização
      • strContent: JSON à converter (string);
      • filePathResult: Caminho do arquivo XML à ser salvo (string);
  • stringToReturnType: Converte um JSON em forma de String em um XML em forma de TXMLDocument (TXMLDocument);
    • Parametrização
      • strContent: JSON à converter (string);
  • fileToString: Converte um arquivo JSON em um XML em forma de string (string);
    • Parametrização
      • filePath: Caminho do arquivo JSON à converter (string);
  • fileToFile: Converte um arquivo JSON em um arquivo XML (boolean);
    • Parametrização
      • filePath: Caminho do arquivo JSON à converter (string);
      • filePathResult: Caminho do arquivo XML à ser salvo (string);
  • fileToReturnType: Converte um arquivo JSON em um XML em forma de TXMLDocument (TXMLDocument);
    • Parametrização
      • filePath: Caminho do arquivo JSON à converter (string);
  • originTypeToString: Converte um JSON em forma de TJSONObject em um XML em forma de string (string);
    • Parametrização
      • content: JSON à converter (TJSONObject);
  • originTypeToFile: Converte um JSON em forma de TJSONObject em um arquivo XML (boolean);
    • Parametrização
      • content: JSON à converter (TJSONObject);
      • filePathResult: Caminho do arquivo XML à ser salvo (string);
  • originTypeToReturnType: Converte um JSON em forma de TJSONObject em um XML em forma de TXMLDocument (TXMLDocument);
    • Parametrização
      • content: JSON à converter (TJSONObject);
  • normalizeOrigin: Converte um JSON em forma de String em um JSON em forma de TJSONObject (TJSONObject);
    • Parametrização
      • content: JSON à normalizar (string);
  • normalizeOrigin: Converte um JSON em forma de TJSONObject em um JSON em forma de TStringList (TStringList);
    • Parametrização
      • content: JSON à normalizar (TJSONObject);
  • normalizeOrigin: Converte um JSON em forma de TStringList em um JSON em forma de String (string);
    • Parametrização
      • content: JSON à normalizar (TStringList);
  • normalizeReturn: Converte um XML em forma de String em um XML em forma de TXMLDocument (TXMLDocument);
    • Parametrização
      • content: XML à normalizar (string);
  • normalizeReturn: Converte um XML em forma de TXMLDocument em um XML em forma de TStringList (TStringList);
    • Parametrização
      • content: XML à normalizar (TXMLDocument);
  • normalizeReturn: Converte um XML em forma de TStringList em um XML em forma de String (string);
    • Parametrização
      • content: XML à normalizar (TStringList);

• XMLtoJSON

  • stringToString: Converte um XML em forma de String em um JSON em forma de string (string);
    • Parametrização
      • strContent: XML à converter (string);
  • stringToFile: Converte um XML em forma de String em um arquivo JSON (boolean);
    • Parametrização
      • strContent: XML à converter (string);
      • filePathResult: Caminho do arquivo JSON à ser salvo (string);
  • stringToReturnType: Converte um XML em forma de String em um JSON em forma de TJSONObject (TJSONObject);
    • Parametrização
      • strContent: XML à converter (string);
  • fileToString: Converte um arquivo XML em um JSON em forma de string (string);
    • Parametrização
      • filePath: Caminho do arquivo XML à converter (string);
  • fileToFile: Converte um arquivo XML em um arquivo JSON (boolean);
    • Parametrização
      • filePath: Caminho do arquivo XML à converter (string);
      • filePathResult: Caminho do arquivo JSON à ser salvo (string);
  • fileToReturnType: Converte um arquivo XML em um JSON em forma de TJSONObject (TJSONObject);
    • Parametrização
      • filePath: Caminho do arquivo XML à converter (string);
  • originTypeToString: Converte um XML em forma de TXMLDocument em um JSON em forma de string (string);
    • Parametrização
      • content: XML à converter (TXMLDocument);
  • originTypeToFile: Converte um XML em forma de TXMLDocument em um arquivo JSON (boolean);
    • Parametrização
      • content: XML à converter (TXMLDocument);
      • filePathResult: Caminho do arquivo JSON à ser salvo (string);
  • originTypeToReturnType: Converte um XML em forma de TXMLDocument em um JSON em forma de TJSONObject (TJSONObject);
    • Parametrização
      • content: XML à converter (TXMLDocument);
  • normalizeOrigin: Converte um XML em forma de String em um XML em forma de TXMLDocument (TXMLDocument);
    • Parametrização
      • content: XML à normalizar (string);
  • normalizeOrigin: Converte um XML em forma de TXMLDocument em um XML em forma de TStringList (TStringList);
    • Parametrização
      • content: XML à normalizar (TXMLDocument);
  • normalizeOrigin: Converte um XML em forma de TStringList em um XML em forma de String (string);
    • Parametrização
      • content: XML à normalizar (TStringList);
  • normalizeReturn: Converte um JSON em forma de String em um JSON em forma de TJSONObject (TJSONObject);
    • Parametrização
      • content: JSON à normalizar (string);
  • normalizeReturn: Converte um JSON em forma de TJSONObject em um JSON em forma de TStringList (TStringList);
    • Parametrização
      • content: JSON à normalizar (TJSONObject);
  • normalizeReturn: Converte um JSON em forma de TStringList em um JSON em forma de String (string);
    • Parametrização
      • content: JSON à normalizar (TStringList);

Sitemap

" class="reference-link">Estrutura

• app: Contém a compilação do(s) pacote(s) e testador(es);
• documentation: Contém a documentação do(s) pacote(s);
• images: Contém as imagens usadas no(s) pacote(s);
• modules: Módulos que executam cada conversão disponível no sistema;
  • JSONtoXML: Contém o pacote usado para conversão de XML para JSON;
  • XMLtoJSON: Contém o pacote usado para conversão de JSON para XML;
• output: Contém os arquivos pré compilados usados pelo Delphi (.dcu);
• project: Diretório com os projetos de cada pacote e testador;
• src: Contém o fonte essencial para o funcionamento do(s) pacote(s);
  • Padronizacao: Contém as interfaces que padronizao os pacoes;
  • FormatConverter: Contém o pacote com o registro desse componente (também usado para pegar o número de build);
  • FormatConverterTester: Contém o executável de este do Componente;
• vendor: Contém os pacotes de terceiros;

" class="reference-link">Workgroup

Deve-se manter a ordem de compilação do projeto como na imagem.

" class="reference-link">Dependências

• Sem dependências até o momento.

" class="reference-link">Contribuir

1. Faça um “fork” com base no master;
2. Faça “commit” de suas alterações (Caso estiver resolvendo alguma “issue” não esqueça de na mensagem escrever “Fixed #numeroIssue”);
3. Faça “push” de seus commits;
4. Solicite um “pull request” para o master do repositório principal.

Criando uma Issue

Para criar uma issue atente para o seguinte:

• Selecionar o label adequado para a issue (esse label poderá vir a ser alterado, mas a não designação faz com que a issue fique perdida).

• Selecionar o projeto FormatConverter - Kanban, isso organizará o que está sendo feito e o que deverá ser feito.

" class="reference-link">Checklist para Contribuir

• Testar as funcionalidades criadas / alteradas;
• Marcar com “#” os issues concluídos, nos commits;
• Readme (caso nescessário)
  • Número do build;
  • Alterar indice;
  • Alterar / adicionar forma de uso;
  • Incluir pacotes / classes / métodos / parâmetros nas formas de uso;
  • Alterar sitemap;
  • Alterar estrutura da aplicação;
  • Imagem atualizada do Workgroup;
  • Adicionar / Remover dependências (pacotes de terceiros);
  • Atualizar métodos de instalação / configuração do pacote;
  • Atualizar a documentação do fonte;
  • Remover / adicionar itens ao TODO;
  • Atualizar árvore do projeto;
• Ao adicionar itens ao TODO, não esquecer de criar a “issue” correspondente;
  • Labels principais
    • bug: Correção de algum problema;
    • documentation: Alteração na documentação;
    • enhacement: Alteração de funcionalidade existente para melhorá-la;
    • feature: Nova funcionalidade;
  • Projeto
    • FormatConverter - Kanban: Para melhor organizar o projeto;

" class="reference-link">Créditos

@bomrafinha

Licença

" class="reference-link">Padronização de Código

Versionamento

Para versionar o FormatConverter deve-se usar como base, o versionamento do pacote FormatConverter.bpl para windows 32 bits, da forma que se segue:

onde:

1. Versão principal, só muda quando o funcionamento básico do sistema altera de forma considerável;
2. Quantidade de módulos funcionais do sistema;
3. Quantidade de funções públicas disponíveis no sistema;
4. Versão de build do sistema auto-gerado pelo Delphi;
5. Deve-se manter o build como auto incremento;

Para cada teste compilado com sucesso deve-se dar build no FormatConverter.bpl para versionar (shift + F9).

Os releases do repositório serão feitos a cada vez que um módulo estiver 100% finalizado, ou quando um conserto muito relevante for realizado.

Padrões adotados no projeto

Para um melhor entendimento do projeto foi-se adotado alguns padrões que facilitam a identificação de cada estrutura usada. São, basicamente, o uso de camelCase, e PascalCase;

Variáveis de método

Variáveis locais devem ser camelCase.

Observar o espaçamento entre a declaração de variáveis e o inicio do método.

Variáveis privadas

A declaração de váriaveis privadas deve ocorrer sempre dentro dos modificadores de acesso.

Devem ser camelCase começando sempre com “f” seguido por seu nome.

Propriedades

Propriedades devem usar PascalCase.

Devem ter exatamente o nome de sua variável privada e/ou metodo de acesso, eliminando apenas o prefixo (f, get, set).

Métodos

A declaração de métodos deve ocorrer sempre dentro dos modificadores de acesso.

Métodos devem ser camelCase.

Os parâmetros do método devem ser camelCase iniciando com “a”.

Procurar, quando possível, usar prefixos get, set, eh, etc de acordo com a função do método e/ou seu retorno.

Ao serem chamados usar sempre parentesis em sua chamada, mesmo quando sem parâmetros. Ex: meuMetodo();

Interfaces

Interfaces devem começar sempre com a letra “I” (maiúsculo), seguido por seu nome em PascalCase.

Classes

Classes devem começar sempre com a letra “T” (maiúsculo), seguido por seu nome em PascalCase.

Classes que não extendem nenhuma outra classes em específico devem extender TInterfacedObject.

Chamada de métodos em múltiplas linhas

Métodos com chamadas muito extensas devem ser chamados usando padrão de identação JSON.

Uso de blocos begin end

Estruturas que não se utilizam do bloco de abertura e fechamento de código, como ifs de uma linha, em um código muito extenso geralmente atrapalham na leitura do código para posteriores modificações. Por esse motivo todas as estruturas devem possuir o bloco de abertura e fechamento (begin .. end)

Identação

Modificadores de acesso devem ser declarados de forma a ficarem alinhados à declaração da classe.

Declaração de métodos, propriedades, construtores/destrutores, bem como o var da declaração de variáveis, devem estar alinhados.

Agrupar procedures e functions sem alterná-los.

Separar declações de variáveis, métodos, construtores, destrutores e propriedades com uma linha em branco, bem como deixar uma linha em branco antes da declaração de modificador de acesso, ou fim do bloco, exceto no primeiro modificador após a declaração da classes.

Chamada de métodos e variaveis internas da classe

Devem ser precedidas da palavra reservada Self, para facilitar a leitura do código.

Palavras Reservadas

Dá-se preferência ao uso de iniciais minúsculas para palavras reservadas. Porém isso não é uma regra para o projeto tendo em vista que por serem reservadas a IDE às sinaliza, não atrapalhando, assim, a leitura do código.

Nomenclatura dos Arquivos

Deve-se nomear os arquivos começando-se com U_.

Para uma melhor localização dos arquivos no gerenciador de arquivos, e das unidades dentro do Delphi, devemos montar o nome dos arquivos compondo-os de seus módulos, submódulos, e função final, todos separados por ponto. Como segue na imagem a seguir:

Um código bem padronizado é muito mais fácil de ler, mesmo por programadores que utilizam outras linguagens.

" class="reference-link">TODO

• Conversor JSON -> CSV

  • Entrada JSON -> Saída CSV
  • Entrada JSON -> Saída string
  • Entrada JSON -> Saída arquivo
  • Entrada string -> Saída CSV
  • Entrada string -> Saída string
  • Entrada string -> Saída arquivo
  • Entrada arquivo -> Saída CSV
  • Entrada arquivo -> Saída string
  • Entrada arquivo -> Saída arquivo
  • Normalizar origin String -> JSON
  • Normalizar origin JSON -> TStringList
  • Normalizar origin TStringList -> String
  • Normalizar return String -> CSV
  • Normalizar return CSV -> TStringList
  • Normalizar return TStringList -> String

• Conversor XML -> CSV

  • Entrada XML -> Saída CSV
  • Entrada XML -> Saída string
  • Entrada XML -> Saída arquivo
  • Entrada string -> Saída CSV
  • Entrada string -> Saída string
  • Entrada string -> Saída arquivo
  • Entrada arquivo -> Saída CSV
  • Entrada arquivo -> Saída string
  • Entrada arquivo -> Saída arquivo
  • Normalizar origin String -> XML
  • Normalizar origin XML -> TStringList
  • Normalizar origin TStringList -> String
  • Normalizar return String -> CSV
  • Normalizar return CSV -> TStringList
  • Normalizar return TStringList -> String

• Conversor CSV -> JSON

  • Entrada CSV -> Saída JSON
  • Entrada CSV -> Saída string
  • Entrada CSV -> Saída arquivo
  • Entrada string -> Saída JSON
  • Entrada string -> Saída string
  • Entrada string -> Saída arquivo
  • Entrada arquivo -> Saída JSON
  • Entrada arquivo -> Saída string
  • Entrada arquivo -> Saída arquivo
  • Normalizar origin String -> CSV
  • Normalizar origin CSV -> TStringList
  • Normalizar origin TStringList -> String
  • Normalizar return String -> JSON
  • Normalizar return JSON -> TStringList
  • Normalizar return TStringList -> String

• Conversor CSV -> XML

  • Entrada CSV -> Saída XML
  • Entrada CSV -> Saída string
  • Entrada CSV -> Saída arquivo
  • Entrada string -> Saída XML
  • Entrada string -> Saída string
  • Entrada string -> Saída arquivo
  • Entrada arquivo -> Saída XML
  • Entrada arquivo -> Saída string
  • Entrada arquivo -> Saída arquivo
  • Normalizar origin String -> CSV
  • Normalizar origin CSV -> TStringList
  • Normalizar origin TStringList -> String
  • Normalizar return String -> XML
  • Normalizar return XML -> TStringList
  • Normalizar return TStringList -> String

" class="reference-link">Árvore do Projeto

FormatConverter
├── app
│   └── .gitkeep
├── documentation
│   └── images
│       ├── exemplo.png
│       ├── install_config.png
│       ├── label_issue.png
│       ├── nomenclatura.png
│       ├── padrao_blocos_01.png
│       ├── padrao_blocos_02.png
│       ├── padrao_chamadas_01.png
│       ├── padrao_chamadas_02.png
│       ├── padrao_classes.png
│       ├── padrao_identacao_01.png
│       ├── padrao_interfaces.png
│       ├── padrao_metodos.png
│       ├── padrao_propriedades.png
│       ├── padrao_self_01.png
│       ├── padrao_variaveis_locais.png
│       ├── padrao_variaveis_privadas.png
│       ├── project_issue.png
│       ├── sitemap.png
│       ├── uso.png
│       ├── versionamento.png
│       └── workgroup.png
├── images
│   └── icone
│       ├── FormatConverter.bmp
│       ├── icon 150x150.png
│       ├── icon 44x44.png
│       ├── icon.ico
│       ├── icon.png
│       └── icon.psd
├── modules
│   ├── CSVtoJSON
│   │   └── U_CSV.JSON.pas
│   ├── CSVtoXML
│   │   └── U_CSV.XML.pas
│   ├── JSONtoCSV
│   │   └── U_JSON.CSV.pas
│   ├── JSONtoXML
│   │   └── U_JSON.XML.pas
│   ├── XMLtoCSV
│   │   └── U_XML.CSV.pas
│   └── XMLtoJSON
│       └── U_XML.JSON.pas
├── output
│   └── .gitkeep
├── project
│   ├── CSVtoJSON.dpk
│   ├── CSVtoJSON.dproj
│   ├── CSVtoXML.dpk
│   ├── CSVtoXML.dproj
│   ├── Format_Converter.groupproj
│   ├── FormatConverter.dpk
│   ├── FormatConverter.dproj
│   ├── FormatConverterTester.dpr
│   ├── FormatConverterTester.dproj
│   ├── JSONtoCSV.dpk
│   ├── JSONtoCSV.dproj
│   ├── JSONtoXML.dpk
│   ├── JSONtoXML.dproj
│   ├── Padronizacao.dpk
│   ├── Padronizacao.dproj
│   ├── XMLtoCSV.dpk
│   ├── XMLtoCSV.dproj
│   ├── XMLtoJSON.dpk
│   └── XMLtoJSON.dproj
├── src
│   ├── FormatConverter
│   │   └── U_FormatConverter.pas
│   ├── FormatConverterTester
│   │   ├── U_FormatConverterTester.View.fmx
│   │   └── U_FormatConverterTester.View.pas
│   └── Padronizacao
│       ├── U_Normalize.pas
│       └── U_Origin.Return.pas
├── vendor
│   └── .gitkeep
├── .gitattributes
├── .gitignore
├── LICENSE
└── README.md