README

📚 Parameters versão 1.0.7 - Documentação Completa

Versão: 1.0.7
Data de Criação: 01/01/2026
Data de Atualização: 23/04/2026
Status Geral: ✅ ~99.5% COMPLETO - Pronto para uso em produção (multithread, totalmente testado)
Compatibilidade: ✅ Delphi XE7+ | ✅ FPC 3.3.1 (build completo com Attributes) ou FPC 3.2.2+ (sem Attributes) | ✅ Lazarus | ✅ FPCUnit (Testes). Linux suportado via FPC; GUI e TUI (mensagens por callback).

🔄 Patch 1.0.7 (23/04/2026) — Parameters.DynamicLibrary (SSOT de DLLs)

• ✅ Nova unit src/Commons/Parameters.DynamicLibrary.pas — SSOT para resolução de DLLs cliente de banco (dispatcher por engine + tipo de BD, leitura de database_dll em .ini/.json/.db, configuradores ConfigureZeosLibraryLocation e ConfigureFireDACVendorLib, helper AppendPathEnv, record helper TParameterDatabaseTypesDLLHelper). Alinhado ao padrão ProvidersORM Commons.Types V1.0.5.
• ✅ Firebird no dispatcher de DLL (GDS32.DLL Win32 / fbclient.dll Win64) — antes ausente.
• ✅ Consolidação massiva em Parameters.Database.pas — ~430 linhas removidas (GetDatabaseDllBasePath, ReadDatabaseDllFromConfigFile, ConfigureZeosLibraryLocation + VendorLib FireDAC duplicado em CreateInternalConnection e ConnectConnection), substituídas por ~20 linhas de chamadas à nova unit.
• 💥 Breaking change: DEFAULT_PARAMETERS_SECTION_NAME passou de 'paramenters' (typo) para 'parameters'. Afecta config.ini ([parameters]), config.json (objecto parameters) e config.db (titulo = 'parameters'). Sem camada de compat — ver CHANGELOG.md para guia de migração SQL/INI/JSON.
• ✅ Documentação Commons — cobertura completa 7/7 em Documentation/Analise/Commons/ (docs para Consts, DynamicLibrary, Exceptions, IOUtils, Messages, Parameter, Version).
• ✅ Robustez: leitores em Parameters.DynamicLibrary protegidos com try/except — primeiro arranque (tabela config ausente em config.db) deixou de propagar EZSQLException/EAccessViolation.

🔄 Mudanças na Versão 1.0.7 (15/02/2026)

• ✅ Engine SQLdb (Lazarus/FPC): Suporte ao pacote SQLdb (TSQLConnection, TSQLTransaction, TSQLQuery) como alternativa ao Zeos no FPC; FromConfig com Config.db via TSQLite3Connection; roteiro consolidado em Documentation/ROTEIROS_CONSOLIDADO.md. Ver CHANGELOG.md.
• ✅ MySQL/MariaDB – DLL e SSL: Busca de DLL com libmariadb.dll como 1ª opção e libmysql.dll como 2ª na pasta MySql (FireDAC e Zeos); Zeos com MYSQL_SSL=0 e UseSSL=0 para evitar erro 2026 (SSL connection error).
• ✅ Label DLL no pnlTop: O label lblDLLPath nos formulários exibe o caminho em que o módulo busca a DLL para o tipo de banco selecionado (PostgreSQL, MySQL, SQL Server); atualizado ao mudar o combo e em UpdateConnectionInfo.
• ✅ Passo a passo Database: Novo documento src/Database/PASSO_A_PASSO_RECRIAR_LOGIC_DATABASE.md para outra IA recriar a lógica da unit de acesso a banco (engines, DLLs, CRUD, FromConfig, tabela config).

🔄 Mudanças na Versão 1.0.6 (14/02/2026)

• ✅ Access – Delphi 64-bit e FPC/Lazarus (correções): Verificação de tabela usando apenas [tabela] no SQL (lógica unificada); GetFullTableNameForSQL retorna [config] em Access; EnsureTableExists / ValidateTableStructure tratam "tabela já existe" como sucesso; List(), Count() e GetTableColumns em FPC+Access não bloqueiam quando InternalTableExists devolve False (fallback + try/except + Assigned(LDataSet.Fields)); QuerySQL / ExecuteSQL fecham queries antes de reabrir (evita "Operação não permitida quando o objeto está fechado"); CreateAccessDatabase em 64-bit usa apenas ACE com ExpandFileName, fallback para Jet apenas em 32-bit; mensagens específicas para 64-bit e FPC/Lazarus; Connect() sem Writeln/Halt (re-raise da excepção ao chamador — evita RunError 103 no Lazarus). Ver CHANGELOG.md.
• ✅ Mensagens Access: TableNotFoundMessage (Parameters.Exceptions.pas) para .mdb/.accdb sugere agora CreateTable ou MS Access/ODBC (já não menciona sqlite3.exe).
• ✅ Documentação: docs/CONEXAO_ACCESS_POR_ENGINE.md secção 5 — 64-bit usa apenas ACE, caminho absoluto recomendado, tabela de erros com entradas para falha de criação de .mdb em 64-bit e para FPC/Lazarus.

🔄 Mudanças na Versão 1.0.5 (11/02/2026)

• ✅ Localização dinâmica de DLLs e nome do banco: Caminho base das DLLs cliente (libpq, libmysql etc.) configurável via DllBasePath() ou lido do parâmetro database_dll pelo FromConfig() / FromConfig(APath) (Config.db, config.ini, config.json); Zeos e FireDAC aplicam o valor em LibraryLocation/VendorLib ao conectar. Database() e ConfigFilePath() completam a resolução (instância → FromConfig → .inc → padrões).
• ✅ Conexão Access por engine: Ajustes completos para UniDAC, FireDAC e Zeos com Microsoft Access (.mdb/.accdb): criação do .mdb via ADOX antes de conectar; aplicação de FUsername/FPassword na conexão; FireDAC com CREATE TABLE ODBC (LONG, LONGTEXT) e ClearFireDACAccessSchemaParams; Zeos com connection string OLE DB (Jet para .mdb, ACE para .accdb) e senha; sem MSysObjects/INFORMATION_SCHEMA para listar tabelas/colunas. Ver CHANGELOG.md.
• ✅ Guia Access: Documento docs/CONEXAO_ACCESS_POR_ENGINE.md com todos os passos por engine para reutilização no ecossistema ORM (conexão, criação do .mdb, sintaxe CREATE TABLE, listagens sem MSysObjects, erros comuns).
• ✅ ORM.Defines.inc: Mensagens dos engines (RESUMO FINAL) corrigidas (USE_ZEOS exibia "UniDAC" e vice-versa); cabeçalho WebSocket padronizado; referência a USE_INFOEMBED corrigida para USE_VERSIONINFO.
• ✅ EnsureTableExists: Passa a criar a tabela automaticamente quando AutoCreateTable está ativo e a tabela não existe.
• ✅ Parameters.Consts.pas: SQL_CREATE_TABLE_ACCESS (sintaxe nativa Jet/ACE para UniDAC e Zeos) e SQL_CREATE_TABLE_ACCESS_ODBC (LONG/LONGTEXT para FireDAC MSAcc).

🔄 Mudanças na Versão 1.0.4 (10/02/2026)

• ✅ Versionamento por arquivo: Cada unit .pas passou a ter cabeçalho com ProjectVersion, FileVersion e Changelog (file). Regras em .cursor/rules/Inicial.mdc; referências em local_arquivos.mdc e roadmap.mdc. Ver CHANGELOG.md.
• ✅ Export INI/JSON → Database (upsert): Ao exportar parâmetros do INI ou do JSON para o Database, o fluxo passou a usar sempre Setter em cada item. Assim, se já existir registro com a mesma chave (contrato_id, produto_id, titulo, chave), é feito UPDATE; caso contrário, INSERT. Isso elimina o erro EZSQLException: column chave is not unique na importação.
• ✅ SQL da tabela config (conformidade): Os scripts de CREATE TABLE e de índice UNIQUE foram alinhados ao config.sql de referência: constraint ChaveUnica com ordem (contrato_id, produto_id, titulo, chave); contrato_id e produto_id com DEFAULT 0; ordem sem NOT NULL; tipos e defaults por banco (PostgreSQL, MySQL, SQL Server, SQLite, FireBird, Access) ajustados; índice nomeado idx_%s_ChaveUnica.
• ✅ Alterações unit a unit: Detalhamento por arquivo em CHANGELOG.md: Parameters.Inifiles.pas e Parameters.JsonObject.pas (ExportToDatabase); Parameters.Consts.pas (constantes SQL); Parameters.Database.pas (CreateTable e migração de índice).

🔄 Mudanças na Versão 1.0.3 (Atualização 21/01/2026)

• ✅ Testes de Thread-Safety: Suite completa de 15 testes validando acesso concorrente
• ✅ Testes de Integração: 20 testes cobrindo CRUD, hierarquia, import/export, casos extremos
• ✅ Testes de Performance: Framework de benchmarking para todas as operações
• ✅ Executável de Testes: ParametersTestSuite.lpr agregando todas as suites
• ✅ Documentação de Testes: Guia completo em Testes/README_Testes.md
• ✅ +2.550 linhas de código de testes (uThreadSafetyTests, uIntegrationTests, uPerformanceTests)

🔄 Mudanças na Versão 1.0.2

• ✅ Nomenclatura: Get() → Getter(), Update() → Setter() (métodos antigos mantidos como deprecated)
• ✅ Hierarquia Completa: Todos os métodos CRUD respeitam ContratoID, ProdutoID, Title, Name (constraint UNIQUE)
• ✅ Compatibilidade: Busca ampla quando hierarquia não está configurada (código legado)

🔄 Mudanças na Versão 1.0.1 (02/01/2026)

• ✅ Validação de chaves duplicadas: Permite inserir chaves com o mesmo nome em títulos diferentes. A validação passou a considerar Nome + Título + ContratoID + ProdutoID como chave única (antes bloqueava qualquer duplicata). Novos helpers: ExistsWithTitulo (Database), ExistsInSection (Inifiles), ExistsInObject (JsonObject).
• ✅ Remoção de secções/objetos vazios: Ao deletar a última chave de um título, a secção/objeto é removido automaticamente (preservando especiais como [Contrato] / "Contrato"). Novo RemoveEmptySection em Inifiles; Delete actualizado em todas as fontes. Ver CHANGELOG.md.

🔄 Mudanças na Versão 1.0.0 (01/01/2026)

• ✅ Versão inicial: Sistema unificado de gerenciamento de parâmetros com suporte a múltiplas fontes (Database, INI Files, JSON Objects), fallback automático entre fontes, multi-engine (UNIDAC, FireDAC, Zeos), multi-database (PostgreSQL, MySQL, SQL Server, SQLite, FireBird, Access), thread-safety com TCriticalSection, interface fluente, import/export bidirecional, encapsulamento total (apenas 2 arquivos públicos).
• ✅ Compatibilidade: Delphi 10.3+, FPC 3.2.2+ / Lazarus 2.0+; diretivas de compilação adaptadas para FPC.
• ✅ Documentação: README.md completo com exemplos, documentação HTML em Analises/, exemplos práticos e guias FPC/Lazarus. Ver CHANGELOG.md.

📋 ÍNDICE

1. Descrição Geral
2. Arquitetura
3. Instalação e Configuração
4. Documentação por Unit
   • Parameters.pas
   • Parameters.Intefaces.pas
   • Parameters.Types.pas
   • Parameters.Consts.pas
   • Parameters.Exceptions.pas
   • Parameters.Database.pas
   • Parameters.Inifiles.pas
   • Parameters.JsonObject.pas
5. Exemplos de Uso
6. Tratamento de Erros
7. FAQ
8. Compatibilidade FPC/Lazarus
9. Castle Engine (Opcional)
10. Estatísticas do Projeto
11. Documentação Adicional

📋 DESCRIÇÃO GERAL

O Parameters (ParamentersORM) é um sistema unificado de gerenciamento de parâmetros de configuração com suporte a múltiplas fontes de dados (Banco de Dados, Arquivos INI, Objetos JSON) e fallback automático para contingência.

🎯 Objetivo Principal

Centralizar o acesso a parâmetros de configuração do sistema, permitindo que o programa busque configurações de múltiplas fontes de forma transparente e unificada, com suporte a fallback automático quando uma fonte falha.

✨ Características Principais

• ✅ Multi-fonte: Suporte a Database, INI Files e JSON Objects
• ✅ Fallback Automático: Busca em cascata quando uma fonte falha
• ✅ Multi-engine Database: UNIDAC, FireDAC, Zeos
• ✅ Multi-database: PostgreSQL, MySQL, SQL Server, SQLite, FireBird, Access
• ✅ Thread-safe: Todas as operações protegidas com TCriticalSection
• ✅ Fluent Interface: Métodos encadeáveis para código mais legível
• ✅ Importação/Exportação: Bidirecional entre todas as fontes (export INI/JSON → Database com upsert via Setter)
• ✅ Encapsulamento Total: Apenas 2 arquivos públicos
• ✅ Versionamento por arquivo: Cada unit com ProjectVersion, FileVersion e Changelog (file) no cabeçalho (regras em .cursor/rules/Inicial.mdc)
• ✅ Compatibilidade FPC/Lazarus: Totalmente adaptado para Free Pascal Compiler e Lazarus IDE
• ✅ Multi-plataforma: Windows, Linux, macOS (com limitações específicas do Windows)
• ✅ Tabela config padronizada: CREATE TABLE e índice alinhados ao config.sql (ChaveUnica, DEFAULT 0, tipos por banco)

🏗️ ARQUITETURA

Estrutura de Arquivos

???? src/

??? ARQUIVOS P??BLICOS (2 - Acess??veis externamente):
????????? Parameters.pas              ??? Ponto de Entrada (Factory methods + TParametersImpl) [??? 1.271 linhas]
????????? Parameters.Interfaces.pas   ??? Interfaces P??blicas [??? 306 linhas]
    ???????????? IParameters (interface principal de converg??ncia)
    ???????????? IParametersDatabase
    ???????????? IParametersInifiles
    ???????????? IParametersJsonObject
    ???????????? Re-exporta tipos p??blicos (TParameter, TParameterList, etc.)

???? ARQUIVOS INTERNOS (Apenas na se????o implementation):
????????? Commons/
???   ????????? Parameters.Types.pas           ??? Tipos (re-exportados via Interfaces) [??? 374 linhas]
???   ????????? Parameters.Consts.pas          ??? Constantes e defaults [??? ~704 linhas]
???   ????????? Parameters.Exceptions.pas      ??? Exce????es customizadas [??? 567 linhas]
???   ????????? Parameters.IOUtils.pas         ??? TFile/TPath wrapper FPC + IfThen [??? 185 linhas]
???   ????????? Parameters.Messages.pas        ??? Callback GUI/TUI [??? 55 linhas]
???   ????????? Parameters.Version.pas         ??? SSOT vers??o + record TVersion [??? 209 linhas]
???   ????????? Parameters.DynamicLibrary.pas  ??? SSOT DLLs cliente (V1.0.7, ~600 linhas)
???   ????????? Parameters.FPC.inc             ??? Include de compatibilidade FPC 3.2+/3.3+
????????? Database/
???   ????????? Parameters.Database.pas    ??? TParametersDatabase [??? 4.912 linhas]
????????? IniFiles/
???   ????????? Parameters.Inifiles.pas    ??? TParametersInifiles [??? 1.476 linhas]
????????? JsonObject/
???   ????????? Parameters.JsonObject.pas  ??? TParametersJsonObject [??? 2.264 linhas]
????????? Attributes/ (Sistema de Attributes - v2.0+)
    ????????? Parameters.Attributes.pas              ??? Attributes principais [??? Implementado]
    ????????? Parameters.Attributes.Interfaces.pas   ??? Interfaces de Attributes [??? Implementado]
    ????????? Parameters.Attributes.Types.pas        ??? Tipos de Attributes [??? Implementado]
    ????????? Parameters.Attributes.Consts.pas       ??? Constantes de Attributes [??? Implementado]
    ????????? Parameters.Attributes.Exceptions.pas   ??? Exce????es de Attributes [??? Implementado]

Fluxo de Dados

Aplica????o
    ???
Parameters (IParameters)
    ???
    ???????????? IParametersDatabase (Banco de Dados)
    ???????????? IParametersInifiles (Arquivos INI)
    ???????????? IParametersJsonObject (JSON Objects)

Princípios de Design

• Encapsulamento: Apenas Parameters.pas e Parameters.Intefaces.pas são públicos
• Independência: Não depende de ProvidersORM.DataModule ou Common.Types
• Factory Pattern: Factory class TParameters cria instâncias
• Fluent Interface: Métodos encadeáveis para código mais legível

🔧 INSTALAÇÃO E CONFIGURAÇÃO

Requisitos

Para Delphi

• Delphi XE7+ (RAD Studio)
• Um dos engines: UniDAC, FireDAC ou Zeos
• Units do projeto no path de busca (ver dcc32.cfg / dcc64.cfg)

Para FPC/Lazarus

• FPC 3.3.1 para build completo (incluindo módulo Attributes); FPC 3.2.2+ para build sem Attributes
• Lazarus com LCL e pacote zcomponent (Zeos)
• Engine: Zeos (recomendado, open-source) ou UniDAC (licença)
• FireDAC não está disponível no FPC (desativado em ORM.Defines.inc)

Linux (via FPC)

• Suportado via FPC/Lazarus; requer LCL e zcomponent
• Access (.mdb/.accdb) e Registry apenas Windows; no Linux usar INI/JSON/Database para configuração

GUI e TUI

• GUI: Aplicação com formulários (ShowMessage/MessageDlg nos forms); mensagens em código compartilhado via Parameters.Messages (callback).
• TUI: Aplicação console ou uso como biblioteca; atribuir OnParametersMessage a WriteLn(StdErr, ...) ou log; confirmações (MessageDlg) podem ser substituídas por flags/argumentos na linha de comando.

Limitações

• Criação de .mdb/.accdb (Microsoft Access) apenas em Windows (ADOX/COM); no Linux usar SQLite, PostgreSQL ou MySQL.
• Registry do Windows apenas em Windows; no Linux configuração via INI/JSON/Database.
• Compilação por linha de comando: dcc32.cfg / dcc64.cfg (Delphi) e ParamentersCSL.fpc.win32.opts / .fpc.win64.opts (FPC) devem incluir todas as dependências (Zeos, DataSet.Serialize); ver Documentation/README_V1.0.md e .cursor/rules/local_arquivos.mdc.

Configuração Inicial

1. Adicione ao uses:

uses Parameters;

2. Configure o engine de banco de dados em ParamentersORM.Defines.inc:

{$DEFINE USE_UNIDAC}  // ou USE_FIREDAC ou USE_ZEOS

3. Configure constantes de conexão em ParamentersORM.Database.inc:

DEFAULT_PARAMETERS_HOST = 'localhost';
DEFAULT_PARAMETERS_PORT = 5432;
DEFAULT_PARAMETERS_DATABASE = 'mydb';
// ... outras constantes

📦 DOCUMENTAÇÃO POR UNIT

Parameters.pas

Tipo: Público (Ponto de Entrada)
Linhas: 1.271
Responsabilidade: Factory methods e implementação de IParameters

Factory Class: TParameters

Métodos Estáticos

class function New: IParameters; overload;

Cria nova instância de IParameters com configuração padrão (apenas Database).

Retorno: IParameters - Interface unificada configurada

Exemplo:

var Parameters: IParameters;
Parameters := TParameters.New;
Parameters.Database.Host('localhost').Connect;

class function New(AConfig: TParameterConfig): IParameters; overload;

Cria nova instância de IParameters com configuração de fontes especificada.

Parâmetros:

• AConfig: TParameterConfig - Set de opções: [pcfDataBase, pcfInifile, pcfJsonObject]

Retorno: IParameters - Interface unificada configurada

Exemplo:

var Parameters: IParameters;
// Database com fallback para INI
Parameters := TParameters.New([pcfDataBase, pcfInifile]);
Parameters.Database.Host('localhost').Connect;
Parameters.Inifiles.FilePath('config.ini');

class function NewDatabase: IParametersDatabase; overload;

Cria nova instância de IParametersDatabase (conexão interna automática).

Retorno: IParametersDatabase - Interface de acesso a banco de dados

Exemplo:

var DB: IParametersDatabase;
DB := TParameters.NewDatabase
  .Host('localhost')
  .Database('mydb')
  .Connect;

class function NewDatabase(AConnection: TObject; AQuery: TDataSet = nil; AExecQuery: TDataSet = nil): IParametersDatabase; overload;

Cria instância usando conexão e queries existentes.

Parâmetros:

• AConnection: TObject - Conexão existente (TUniConnection, TFDConnection ou TZConnection)
• AQuery: TDataSet (opcional) - Query para SELECT
• AExecQuery: TDataSet (opcional) - Query para INSERT/UPDATE/DELETE

Retorno: IParametersDatabase

Exemplo:

var MyConnection: TUniConnection;
var MyQuery: TUniQuery;
// ... inicializa MyConnection e MyQuery ...
DB := TParameters.NewDatabase(MyConnection, MyQuery);

class function NewInifiles: IParametersInifiles; overload;

Cria nova instância de IParametersInifiles com valores padrão.

Retorno: IParametersInifiles

Exemplo:

var Ini: IParametersInifiles;
Ini := TParameters.NewInifiles
  .FilePath('C:\Config\params.ini')
  .Section('Parameters');

class function NewInifiles(const AFilePath: string): IParametersInifiles; overload;

Cria instância já configurada com caminho do arquivo.

Parâmetros:

• AFilePath: string - Caminho completo do arquivo INI

Retorno: IParametersInifiles

Exemplo:

Ini := TParameters.NewInifiles('C:\Config\params.ini');

class function NewJsonObject: IParametersJsonObject; overload;

Cria nova instância com objeto JSON vazio.

Retorno: IParametersJsonObject

Exemplo:

var Json: IParametersJsonObject;
Json := TParameters.NewJsonObject
  .FilePath('C:\Config\params.json');

class function NewJsonObject(AJsonObject: TJSONObject): IParametersJsonObject; overload;

Cria instância usando objeto JSON existente.

Parâmetros:

• AJsonObject: TJSONObject - Objeto JSON existente

Retorno: IParametersJsonObject

Exemplo:

var MyJson: TJSONObject;
MyJson := TJSONObject.ParseJSONValue('{"ERP":{"host":"localhost"}}') as TJSONObject;
Json := TParameters.NewJsonObject(MyJson);

class function NewJsonObject(const AJsonString: string): IParametersJsonObject; overload;

Cria instância parseando uma string JSON.

Parâmetros:

• AJsonString: string - String contendo JSON válido

Retorno: IParametersJsonObject

Exemplo:

Json := TParameters.NewJsonObject('{"ERP":{"host":"localhost","port":5432}}');

class function NewJsonObjectFromFile(const AFilePath: string): IParametersJsonObject;

Cria instância carregando JSON de um arquivo.

Parâmetros:

• AFilePath: string - Caminho completo do arquivo JSON

Retorno: IParametersJsonObject

Exemplo:

Json := TParameters.NewJsonObjectFromFile('C:\Config\params.json');
List := Json.List; // JSON já está carregado

class function DetectEngine: TParameterDatabaseEngine;

Detecta automaticamente qual engine está disponível baseado nas diretivas de compilação.

Retorno: TParameterDatabaseEngine (pteUnidac, pteFireDAC, pteZeos ou pteNone)

Exemplo:

var Engine: TParameterDatabaseEngine;
Engine := TParameters.DetectEngine;
case Engine of
  pteUnidac: ShowMessage('UNIDAC detectado');
  pteFireDAC: ShowMessage('FireDAC detectado');
  pteZeos: ShowMessage('Zeos detectado');
end;

class function DetectEngineName: string;

Retorna o nome do engine detectado como string.

Retorno: string - Nome do engine ('UniDAC', 'FireDAC', 'Zeos' ou 'None')

Exemplo:

var EngineName: string;
EngineName := TParameters.DetectEngineName;
ShowMessage('Engine: ' + EngineName);

Implementação: TParametersImpl

Classe encapsulada na seção implementation que implementa IParameters. Não é acessível externamente.

Campos Privados:

• FDatabase: IParametersDatabase
• FInifiles: IParametersInifiles
• FJsonObject: IParametersJsonObject
• FActiveSource: TParameterSource
• FPriority: TParameterSourceArray
• FConfig: TParameterConfig
• FContratoID: Integer
• FProdutoID: Integer
• FLock: TCriticalSection

Parameters.Intefaces.pas

Tipo: Público (Interfaces e Tipos)
Linhas: 306
Responsabilidade: Define todas as interfaces públicas e re-exporta tipos

Interface: IParameters

Interface principal de convergência que gerencia múltiplas fontes de dados com fallback automático.

Gerenciamento de Fontes

function Source(ASource: TParameterSource): IParameters; overload;

Define a fonte ativa para operações de escrita.

Parâmetros:

• ASource: TParameterSource - Fonte a ser ativada (psDatabase, psInifiles, psJsonObject)

Retorno: IParameters (fluent interface)

Exemplo:

Parameters.Source(psDatabase); // Define Database como fonte ativa

function Source: TParameterSource; overload;

Retorna a fonte ativa atual.

Retorno: TParameterSource

Exemplo:

var CurrentSource: TParameterSource;
CurrentSource := Parameters.Source;

function AddSource(ASource: TParameterSource): IParameters;

Adiciona uma fonte à lista de fontes ativas.

Parâmetros:

• ASource: TParameterSource - Fonte a ser adicionada

Retorno: IParameters

Exemplo:

Parameters.AddSource(psInifiles); // Adiciona INI como fonte adicional

function RemoveSource(ASource: TParameterSource): IParameters;

Remove uma fonte da lista de fontes ativas.

Parâmetros:

• ASource: TParameterSource - Fonte a ser removida

Retorno: IParameters

Exemplo:

Parameters.RemoveSource(psDatabase); // Remove Database das fontes ativas

function HasSource(ASource: TParameterSource): Boolean;

Verifica se uma fonte está ativa.

Parâmetros:

• ASource: TParameterSource - Fonte a verificar

Retorno: Boolean

Exemplo:

if Parameters.HasSource(psDatabase) then
  ShowMessage('Database está ativo');

function Priority(ASources: TParameterSourceArray): IParameters;

Define a ordem de prioridade para fallback automático.

Parâmetros:

• ASources: TParameterSourceArray - Array com ordem de prioridade

Retorno: IParameters

Exemplo:

Parameters.Priority([psDatabase, psInifiles, psJsonObject]);
// Busca primeiro no Database, depois INI, depois JSON

Operações Unificadas (com Fallback)

function Getter(const AName: string): TParameter; overload;

Busca parâmetro em cascata (Database → INI → JSON) até encontrar.

IMPORTANTE: Respeita a hierarquia completa da constraint UNIQUE: ContratoID, ProdutoID, Title, Name. Se esses campos estiverem configurados, faz busca específica; caso contrário, faz busca ampla (compatibilidade com código legado).

Parâmetros:

• AName: string - Nome/chave do parâmetro

Retorno: TParameter ou nil se não encontrado

Exemplo com hierarquia completa:

var Param: TParameter;
Parameters
  .ContratoID(1)
  .ProdutoID(1)
  .Database.Title('ERP')
  .Getter('database_host', Param);
if Assigned(Param) then
  ShowMessage(Param.Value)
else
  ShowMessage('Não encontrado em nenhuma fonte');
Param.Free;

Exemplo sem hierarquia (busca ampla - compatibilidade):

var Param: TParameter;
Param := Parameters.Getter('database_host');
if Assigned(Param) then
  ShowMessage(Param.Value);
Param.Free;

Nota: O método Get() está deprecated. Use Getter().

function Getter(const AName: string; ASource: TParameterSource): TParameter; overload;

Busca parâmetro em fonte específica.

Parâmetros:

• AName: string - Nome/chave do parâmetro
• ASource: TParameterSource - Fonte específica para buscar

Retorno: TParameter ou nil

Exemplo:

Param := Parameters.Getter('database_host', psDatabase); // Busca apenas no Database

function List: TParameterList; overload;

Lista todos os parâmetros de todas as fontes ativas (merge, remove duplicatas).

Retorno: TParameterList

Exemplo:

var List: TParameterList;
List := Parameters.List;
try
  for var I := 0 to List.Count - 1 do
    ShowMessage(List[I].Name + ' = ' + List[I].Value);
finally
  List.Free;
end;

function List(out AList: TParameterList): IParameters; overload;

Versão com parâmetro out para fluent interface.

Parâmetros:

• out AList: TParameterList - Lista preenchida com parâmetros

Retorno: IParameters

Exemplo:

var List: TParameterList;
Parameters.List(List);
try
  // Usa List...
finally
  List.Free;
end;

function Insert(const AParameter: TParameter): IParameters; overload;

Insere parâmetro na fonte ativa (default: Database, fallback para primeira disponível).

Parâmetros:

• AParameter: TParameter - Parâmetro a ser inserido

Retorno: IParameters

Exemplo:

var Param: TParameter;
Param := TParameter.Create;
Param.Name := 'teste_key';
Param.Value := 'teste_value';
Param.ValueType := pvtString;
Parameters.Insert(Param);
Param.Free;

function Insert(const AParameter: TParameter; out ASuccess: Boolean): IParameters; overload;

Versão com retorno de sucesso.

Parâmetros:

• AParameter: TParameter - Parâmetro a ser inserido
• out ASuccess: Boolean - True se inserido com sucesso

Retorno: IParameters

Exemplo:

var Success: Boolean;
Parameters.Insert(Param, Success);
if Success then
  ShowMessage('Inserido com sucesso!');

function Update(const AParameter: TParameter): IParameters; overload;

Atualiza parâmetro na fonte onde ele existe.

Parâmetros:

• AParameter: TParameter - Parâmetro a ser atualizado

Retorno: IParameters

Exemplo (deprecated - usar Setter):

Param := Parameters.Getter('database_host');
if Assigned(Param) then
begin
  Param.Value := 'new_host';
  Parameters.Setter(Param); // Insere se não existir, atualiza se existir
end;
Param.Free;

function Update(const AParameter: TParameter; out ASuccess: Boolean): IParameters; overload;

Versão com retorno de sucesso.

Parâmetros:

• AParameter: TParameter - Parâmetro a ser atualizado
• out ASuccess: Boolean - True se atualizado com sucesso

Retorno: IParameters

function Delete(const AName: string): IParameters; overload;

Deleta parâmetro de todas as fontes onde existe.

Parâmetros:

• AName: string - Nome/chave do parâmetro

Retorno: IParameters

Exemplo:

Parameters.Delete('database_host'); // Deleta de Database, INI e JSON se existir

function Delete(const AName: string; out ASuccess: Boolean): IParameters; overload;

Versão com retorno de sucesso.

Parâmetros:

• AName: string - Nome/chave do parâmetro
• out ASuccess: Boolean - True se deletado de pelo menos uma fonte

Retorno: IParameters

function Exists(const AName: string): Boolean; overload;

Verifica se parâmetro existe em qualquer fonte (OR lógico).

Parâmetros:

• AName: string - Nome/chave do parâmetro

Retorno: Boolean - True se existe em qualquer fonte

Exemplo:

if Parameters.Exists('database_host') then
  ShowMessage('Parâmetro existe!');

function Exists(const AName: string; out AExists: Boolean): IParameters; overload;

Versão com parâmetro out para fluent interface.

Parâmetros:

• AName: string - Nome/chave do parâmetro
• out AExists: Boolean - True se existe

Retorno: IParameters

function Count: Integer; overload;

Conta parâmetros únicos de todas as fontes (remove duplicatas por Name).

Retorno: Integer - Número de parâmetros únicos

Exemplo:

var Total: Integer;
Total := Parameters.Count;
ShowMessage(Format('Total de parâmetros: %d', [Total]));

function Count(out ACount: Integer): IParameters; overload;

Versão com parâmetro out para fluent interface.

Parâmetros:

• out ACount: Integer - Contagem de parâmetros únicos

Retorno: IParameters

function Refresh: IParameters;

Recarrega dados de todas as fontes ativas.

Retorno: IParameters

Exemplo:

Parameters.Refresh; // Recarrega Database, INI e JSON

Configuração Unificada

function ContratoID(const AValue: Integer): IParameters; overload;

Aplica ContratoID em todas as fontes ativas.

Parâmetros:

• AValue: Integer - ID do contrato

Retorno: IParameters

Exemplo:

Parameters.ContratoID(1); // Aplica em Database, INI e JSON

function ContratoID: Integer; overload;

Retorna ContratoID atual.

Retorno: Integer

function ProdutoID(const AValue: Integer): IParameters; overload;

Aplica ProdutoID em todas as fontes ativas.

Parâmetros:

• AValue: Integer - ID do produto

Retorno: IParameters

function ProdutoID: Integer; overload;

Retorna ProdutoID atual.

Retorno: Integer

Acesso Direto a Fontes

function Database: IParametersDatabase;

Retorna interface Database para métodos exclusivos.

Retorno: IParametersDatabase

Exemplo:

Parameters.Database
  .Host('localhost')
  .Port(5432)
  .Connect; // Métodos exclusivos do Database

function Inifiles: IParametersInifiles;

Retorna interface Inifiles para métodos exclusivos.

Retorno: IParametersInifiles

Exemplo:

Parameters.Inifiles
  .FilePath('config.ini')
  .Section('Database'); // Métodos exclusivos do INI

function JsonObject: IParametersJsonObject;

Retorna interface JsonObject para métodos exclusivos.

Retorno: IParametersJsonObject

Exemplo:

Parameters.JsonObject
  .FilePath('config.json')
  .ObjectName('Database'); // Métodos exclusivos do JSON

Interface: IParametersDatabase

Interface para acesso a parâmetros em banco de dados.

Configuração (Fluent Interface)

function TableName(const AValue: string): IParametersDatabase; overload;

Define nome da tabela.

Parâmetros:

• AValue: string - Nome da tabela

Retorno: IParametersDatabase

Exemplo:

DB.TableName('config');

function TableName: string; overload;

Retorna nome da tabela atual.

Retorno: string

function Schema(const AValue: string): IParametersDatabase; overload;

Define schema do banco.

Parâmetros:

• AValue: string - Nome do schema

Retorno: IParametersDatabase

Exemplo:

DB.Schema('public');

function Schema: string; overload;

Retorna schema atual.

Retorno: string

function AutoCreateTable(const AValue: Boolean): IParametersDatabase; overload;

Define se deve criar tabela automaticamente se não existir.

Parâmetros:

• AValue: Boolean - True para criar automaticamente

Retorno: IParametersDatabase

function AutoCreateTable: Boolean; overload;

Retorna se auto-criação está ativa.

Retorno: Boolean

Configuração de Conexão

function Engine(const AValue: string): IParametersDatabase; overload;

Define engine por string ('UniDAC', 'FireDAC', 'Zeos').

Parâmetros:

• AValue: string - Nome do engine

Retorno: IParametersDatabase

function Engine(const AValue: TParameterDatabaseEngine): IParametersDatabase; overload;

Define engine por enum.

Parâmetros:

• AValue: TParameterDatabaseEngine - Enum do engine

Retorno: IParametersDatabase

Exemplo:

DB.Engine(pteUnidac);

function Engine: string; overload;

Retorna nome do engine atual.

Retorno: string

function DatabaseType(const AValue: string): IParametersDatabase; overload;

Define tipo de banco por string ('PostgreSQL', 'MySQL', etc.).

Parâmetros:

• AValue: string - Nome do tipo de banco

Retorno: IParametersDatabase

function DatabaseType(const AValue: TParameterDatabaseTypes): IParametersDatabase; overload;

Define tipo de banco por enum.

Parâmetros:

• AValue: TParameterDatabaseTypes - Enum do tipo de banco

Retorno: IParametersDatabase

Exemplo:

DB.DatabaseType(pdtPostgreSQL);

function DatabaseType: string; overload;

Retorna tipo de banco atual.

Retorno: string

function Host(const AValue: string): IParametersDatabase; overload;

Define host do servidor.

Parâmetros:

• AValue: string - Endereço do host

Retorno: IParametersDatabase

Exemplo:

DB.Host('localhost');

function Host: string; overload;

Retorna host atual.

Retorno: string

function Port(const AValue: Integer): IParametersDatabase; overload;

Define porta do servidor.

Parâmetros:

• AValue: Integer - Número da porta

Retorno: IParametersDatabase

Exemplo:

DB.Port(5432);

function Port: Integer; overload;

Retorna porta atual.

Retorno: Integer

function Username(const AValue: string): IParametersDatabase; overload;

Define usuário do banco.

Parâmetros:

• AValue: string - Nome do usuário

Retorno: IParametersDatabase

function Username: string; overload;

Retorna usuário atual.

Retorno: string

function Password(const AValue: string): IParametersDatabase; overload;

Define senha do banco.

Parâmetros:

• AValue: string - Senha

Retorno: IParametersDatabase

function Password: string; overload;

Retorna senha atual (⚠️ apenas para leitura, não armazena em texto plano).

Retorno: string

function Database(const AValue: string): IParametersDatabase; overload;

Define nome do banco de dados.

Parâmetros:

• AValue: string - Nome do banco

Retorno: IParametersDatabase

Exemplo:

DB.Database('mydb');

function Database: string; overload;

Retorna nome do banco atual.

Retorno: string

function ContratoID(const AValue: Integer): IParametersDatabase; overload;

Define filtro de ContratoID.

Parâmetros:

• AValue: Integer - ID do contrato

Retorno: IParametersDatabase

function ContratoID: Integer; overload;

Retorna ContratoID atual.

Retorno: Integer

function ProdutoID(const AValue: Integer): IParametersDatabase; overload;

Define filtro de ProdutoID.

Parâmetros:

• AValue: Integer - ID do produto

Retorno: IParametersDatabase

function ProdutoID: Integer; overload;

Retorna ProdutoID atual.

Retorno: Integer

CRUD

function List: TParameterList; overload;

Lista todos os parâmetros ativos da tabela.

Retorno: TParameterList

Exemplo:

var List: TParameterList;
List := DB.List;
try
  for var I := 0 to List.Count - 1 do
    ShowMessage(List[I].Name + ' = ' + List[I].Value);
finally
  List.Free;
end;

function List(out AList: TParameterList): IParametersDatabase; overload;

Versão com parâmetro out.

Parâmetros:

• out AList: TParameterList - Lista preenchida

Retorno: IParametersDatabase

function Getter(const AName: string): TParameter; overload;

Busca parâmetro por chave respeitando a hierarquia completa: ContratoID, ProdutoID, Title, Name.

IMPORTANTE: Se ContratoID, ProdutoID e Title estiverem configurados, faz busca específica usando a hierarquia completa. Caso contrário, faz busca ampla apenas por chave (compatibilidade com código legado).

Parâmetros:

• AName: string - Nome/chave do parâmetro

Retorno: TParameter ou nil

Exemplo com hierarquia completa:

var Param: TParameter;
DB.ContratoID(1).ProdutoID(1).Title('ERP').Getter('database_host', Param);
if Assigned(Param) then
  ShowMessage(Param.Value);
Param.Free;

Exemplo sem hierarquia (busca ampla - compatibilidade):

var Param: TParameter;
Param := DB.Getter('database_host');
if Assigned(Param) then
  ShowMessage(Param.Value);
Param.Free;

Nota: O método Get() está deprecated. Use Getter().

function Getter(const AName: string; out AParameter: TParameter): IParametersDatabase; overload;

Versão com parâmetro out.

Parâmetros:

• AName: string - Nome/chave
• out AParameter: TParameter - Parâmetro encontrado

Retorno: IParametersDatabase

function Insert(const AParameter: TParameter): IParametersDatabase; overload;

Insere novo parâmetro na tabela.

Parâmetros:

• AParameter: TParameter - Parâmetro a inserir

Retorno: IParametersDatabase

Exemplo:

var Param: TParameter;
Param := TParameter.Create;
Param.Name := 'teste_key';
Param.Value := 'teste_value';
Param.ValueType := pvtString;
Param.ContratoID := 1;
Param.ProdutoID := 1;
DB.Insert(Param);
Param.Free;

function Insert(const AParameter: TParameter; out ASuccess: Boolean): IParametersDatabase; overload;

Versão com retorno de sucesso.

Parâmetros:

• AParameter: TParameter - Parâmetro a inserir
• out ASuccess: Boolean - True se inserido

Retorno: IParametersDatabase

function Setter(const AParameter: TParameter): IParametersDatabase; overload;

Insere ou atualiza um parâmetro (INSERT se não existir, UPDATE se existir).

IMPORTANTE: Sempre respeita a hierarquia completa da constraint UNIQUE: ContratoID, ProdutoID, Title, Name. O parâmetro deve ter todos esses campos preenchidos.

Parâmetros:

• AParameter: TParameter - Parâmetro a ser inserido/atualizado (deve ter ContratoID, ProdutoID, Titulo e Name preenchidos)

Retorno: IParametersDatabase

Exemplo:

var Param: TParameter;
Param := TParameter.Create;
try
  Param.ContratoID := 1;
  Param.ProdutoID := 1;
  Param.Titulo := 'ERP';
  Param.Name := 'database_host';
  Param.Value := 'new_host';
  Param.ValueType := pvtString;
  DB.Setter(Param); // Insere se não existir, atualiza se existir
finally
  Param.Free;
end;

function Setter(const AParameter: TParameter; out ASuccess: Boolean): IParametersDatabase; overload;

Versão com retorno de sucesso.

Parâmetros:

• AParameter: TParameter - Parâmetro a ser inserido/atualizado
• out ASuccess: Boolean - True se operação foi bem-sucedida

Retorno: IParametersDatabase

Nota: O método Update() está deprecated. Use Setter().

function Delete(const AName: string): IParametersDatabase; overload;

Soft delete (marca como inativo).

Parâmetros:

• AName: string - Nome/chave do parâmetro

Retorno: IParametersDatabase

Exemplo:

DB.Delete('database_host'); // Marca como inativo

function Delete(const AName: string; out ASuccess: Boolean): IParametersDatabase; overload;

Versão com retorno de sucesso.

Parâmetros:

• AName: string - Nome/chave
• out ASuccess: Boolean - True se deletado

Retorno: IParametersDatabase

function Exists(const AName: string): Boolean; overload;

Verifica se parâmetro existe na tabela.

Parâmetros:

• AName: string - Nome/chave

Retorno: Boolean

Exemplo:

if DB.Exists('database_host') then
  ShowMessage('Parâmetro existe!');

function Exists(const AName: string; out AExists: Boolean): IParametersDatabase; overload;

Versão com parâmetro out.

Parâmetros:

• AName: string - Nome/chave
• out AExists: Boolean - True se existe

Retorno: IParametersDatabase

Utilitários

function Count: Integer; overload;

Conta parâmetros ativos na tabela.

Retorno: Integer

Exemplo:

var Total: Integer;
Total := DB.Count;
ShowMessage(Format('Total: %d parâmetros', [Total]));

function Count(out ACount: Integer): IParametersDatabase; overload;

Versão com parâmetro out.

Parâmetros:

• out ACount: Integer - Contagem

Retorno: IParametersDatabase

function IsConnected: Boolean; overload;

Verifica se está conectado ao banco.

Retorno: Boolean

Exemplo:

if DB.IsConnected then
  ShowMessage('Conectado!');

function IsConnected(out AConnected: Boolean): IParametersDatabase; overload;

Versão com parâmetro out.

Parâmetros:

• out AConnected: Boolean - True se conectado

Retorno: IParametersDatabase

function Connect: IParametersDatabase; overload;

Conecta ao banco de dados.

Retorno: IParametersDatabase

Exemplo:

DB.Connect; // Lança exceção se falhar

function Connect(out ASuccess: Boolean): IParametersDatabase; overload;

Versão com retorno de sucesso.

Parâmetros:

• out ASuccess: Boolean - True se conectado

Retorno: IParametersDatabase

Exemplo:

var Success: Boolean;
DB.Connect(Success);
if not Success then
  ShowMessage('Falha ao conectar');

function Disconnect: IParametersDatabase;

Desconecta do banco de dados.

Retorno: IParametersDatabase

Exemplo:

DB.Disconnect;

function Refresh: IParametersDatabase;

Recarrega dados da tabela.

Retorno: IParametersDatabase

Gerenciamento de Tabela

function TableExists: Boolean; overload;

Verifica se a tabela existe.

Retorno: Boolean

Exemplo:

if not DB.TableExists then
  DB.CreateTable;

function TableExists(out AExists: Boolean): IParametersDatabase; overload;

Versão com parâmetro out.

Parâmetros:

• out AExists: Boolean - True se existe

Retorno: IParametersDatabase

function CreateTable: IParametersDatabase; overload;

Cria a tabela com estrutura padrão.

Retorno: IParametersDatabase

Exemplo:

DB.CreateTable; // Cria tabela se não existir

function CreateTable(out ASuccess: Boolean): IParametersDatabase; overload;

Versão com retorno de sucesso.

Parâmetros:

• out ASuccess: Boolean - True se criada

Retorno: IParametersDatabase

function DropTable: IParametersDatabase; overload;

Remove a tabela do banco.

Retorno: IParametersDatabase

Exemplo:

DB.DropTable; // ⚠️ CUIDADO: Remove todos os dados!

function DropTable(out ASuccess: Boolean): IParametersDatabase; overload;

Versão com retorno de sucesso.

Parâmetros:

• out ASuccess: Boolean - True se removida

Retorno: IParametersDatabase

Listagem

function ListAvailableDatabases: TStringList; overload;

Lista bancos de dados disponíveis no servidor.

Retorno: TStringList - Lista de nomes de bancos

Exemplo:

var Databases: TStringList;
Databases := DB.ListAvailableDatabases;
try
  for var I := 0 to Databases.Count - 1 do
    ShowMessage(Databases[I]);
finally
  Databases.Free;
end;

function ListAvailableDatabases(out ADatabases: TStringList): IParametersDatabase; overload;

Versão com parâmetro out.

Parâmetros:

• out ADatabases: TStringList - Lista preenchida

Retorno: IParametersDatabase

function ListAvailableTables: TStringList; overload;

Lista tabelas disponíveis no banco/schema.

Retorno: TStringList - Lista de nomes de tabelas

Exemplo:

var Tables: TStringList;
Tables := DB.ListAvailableTables;
try
  for var I := 0 to Tables.Count - 1 do
    ShowMessage(Tables[I]);
finally
  Tables.Free;
end;

function ListAvailableTables(out ATables: TStringList): IParametersDatabase; overload;

Versão com parâmetro out.

Parâmetros:

• out ATables: TStringList - Lista preenchida

Retorno: IParametersDatabase

Configuração de Conexão (Independente)

function Connection(AConnection: TObject): IParametersDatabase; overload;

Define conexão externa existente.

Parâmetros:

• AConnection: TObject - Conexão (TUniConnection, TFDConnection ou TZConnection)

Retorno: IParametersDatabase

Exemplo:

var MyConnection: TUniConnection;
// ... inicializa MyConnection ...
DB.Connection(MyConnection);

function Query(AQuery: TDataSet): IParametersDatabase; overload;

Define query externa para operações SELECT.

Parâmetros:

• AQuery: TDataSet - Query (TUniQuery, TFDQuery ou TZQuery)

Retorno: IParametersDatabase

function ExecQuery(AExecQuery: TDataSet): IParametersDatabase; overload;

Define query externa para operações INSERT/UPDATE/DELETE.

Parâmetros:

• AExecQuery: TDataSet - Query para execução

Retorno: IParametersDatabase

Interface: IParametersInifiles

Interface para acesso a parâmetros em arquivos INI.

Configuração (Fluent Interface)

function FilePath(const AValue: string): IParametersInifiles; overload;

Define caminho do arquivo INI.

Parâmetros:

• AValue: string - Caminho completo do arquivo

Retorno: IParametersInifiles

Exemplo:

Ini.FilePath('C:\Config\params.ini');

function FilePath: string; overload;

Retorna caminho atual.

Retorno: string

function Section(const AValue: string): IParametersInifiles; overload;

Define seção (título) do INI.

Parâmetros:

• AValue: string - Nome da seção

Retorno: IParametersInifiles

Exemplo:

Ini.Section('Database');

function Section: string; overload;

Retorna seção atual.

Retorno: string

function AutoCreateFile(const AValue: Boolean): IParametersInifiles; overload;

Define se deve criar arquivo automaticamente.

Parâmetros:

• AValue: Boolean - True para criar automaticamente

Retorno: IParametersInifiles

function AutoCreateFile: Boolean; overload;

Retorna se auto-criação está ativa.

Retorno: Boolean

function ContratoID(const AValue: Integer): IParametersInifiles; overload;

Define filtro de ContratoID.

Parâmetros:

• AValue: Integer - ID do contrato

Retorno: IParametersInifiles

function ContratoID: Integer; overload;

Retorna ContratoID atual.

Retorno: Integer

function ProdutoID(const AValue: Integer): IParametersInifiles; overload;

Define filtro de ProdutoID.

Parâmetros:

• AValue: Integer - ID do produto

Retorno: IParametersInifiles

function ProdutoID: Integer; overload;

Retorna ProdutoID atual.

Retorno: Integer

CRUD

Todos os métodos CRUD seguem o mesmo padrão de IParametersDatabase:

• List() / List(out AList)
• Get(AName) / Get(AName, out AParameter)
• Insert(AParameter) / Insert(AParameter, out ASuccess)
• Update(AParameter) / Update(AParameter, out ASuccess)
• Delete(AName) / Delete(AName, out ASuccess)
• Exists(AName) / Exists(AName, out AExists)

Exemplo:

var Ini: IParametersInifiles;
Ini := TParameters.NewInifiles('C:\Config\params.ini')
  .ContratoID(1)
  .ProdutoID(1)
  .Title('ERP');
var Param: TParameter;
Ini.Getter('database_host', Param);
if Assigned(Param) then
  ShowMessage(Param.Value);
Param.Free;

Utilitários

function Count: Integer; overload;

Conta parâmetros no arquivo INI.

Retorno: Integer

function Count(out ACount: Integer): IParametersInifiles; overload;

Versão com parâmetro out.

function FileExists: Boolean; overload;

Verifica se o arquivo INI existe.

Retorno: Boolean

Exemplo:

if Ini.FileExists then
  ShowMessage('Arquivo existe!');

function FileExists(out AExists: Boolean): IParametersInifiles; overload;

Versão com parâmetro out.

function Refresh: IParametersInifiles;

Recarrega arquivo INI do disco.

Retorno: IParametersInifiles

Importação/Exportação

function ImportFromDatabase(ADatabase: IParametersDatabase): IParametersInifiles; overload;

Importa parâmetros do Database para o arquivo INI.

Parâmetros:

• ADatabase: IParametersDatabase - Interface Database de origem

Retorno: IParametersInifiles

Exemplo:

var DB: IParametersDatabase;
var Ini: IParametersInifiles;
DB := TParameters.NewDatabase.Connect;
Ini := TParameters.NewInifiles('config.ini');
Ini.ImportFromDatabase(DB); // Importa todos os parâmetros

function ImportFromDatabase(ADatabase: IParametersDatabase; out ASuccess: Boolean): IParametersInifiles; overload;

Versão com retorno de sucesso.

Parâmetros:

• ADatabase: IParametersDatabase - Interface Database
• out ASuccess: Boolean - True se importado com sucesso

Retorno: IParametersInifiles

function ExportToDatabase(ADatabase: IParametersDatabase): IParametersInifiles; overload;

Exporta parâmetros do arquivo INI para o Database.

Parâmetros:

• ADatabase: IParametersDatabase - Interface Database de destino

Retorno: IParametersInifiles

Exemplo:

Ini.ExportToDatabase(DB); // Exporta todos os parâmetros

function ExportToDatabase(ADatabase: IParametersDatabase; out ASuccess: Boolean): IParametersInifiles; overload;

Versão com retorno de sucesso.

Navegação

function EndInifiles: IInterface;

Método de navegação (retorna IInterface para compatibilidade).

Retorno: IInterface

Interface: IParametersJsonObject

Interface para acesso a parâmetros em objetos JSON.

Configuração (Fluent Interface)

function JsonObject(AJsonObject: TJSONObject): IParametersJsonObject; overload;

Define objeto JSON existente.

Parâmetros:

• AJsonObject: TJSONObject - Objeto JSON

Retorno: IParametersJsonObject

Exemplo:

var MyJson: TJSONObject;
MyJson := TJSONObject.ParseJSONValue('{"ERP":{"host":"localhost"}}') as TJSONObject;
Json.JsonObject(MyJson);

function JsonObject: TJSONObject; overload;

Retorna objeto JSON atual.

Retorno: TJSONObject

function ObjectName(const AValue: string): IParametersJsonObject; overload;

Define nome do objeto JSON (título).

Parâmetros:

• AValue: string - Nome do objeto

Retorno: IParametersJsonObject

Exemplo:

Json.ObjectName('ERP');

function ObjectName: string; overload;

Retorna nome do objeto atual.

Retorno: string

function FilePath(const AValue: string): IParametersJsonObject; overload;

Define caminho do arquivo JSON.

Parâmetros:

• AValue: string - Caminho completo do arquivo

Retorno: IParametersJsonObject

Exemplo:

Json.FilePath('C:\Config\params.json');

function FilePath: string; overload;

Retorna caminho atual.

Retorno: string

function AutoCreateFile(const AValue: Boolean): IParametersJsonObject; overload;

Define se deve criar arquivo automaticamente.

Parâmetros:

• AValue: Boolean - True para criar automaticamente

Retorno: IParametersJsonObject

function AutoCreateFile: Boolean; overload;

Retorna se auto-criação está ativa.

Retorno: Boolean

function ContratoID(const AValue: Integer): IParametersJsonObject; overload;

Define filtro de ContratoID.

Parâmetros:

• AValue: Integer - ID do contrato

Retorno: IParametersJsonObject

function ContratoID: Integer; overload;

Retorna ContratoID atual.

Retorno: Integer

function ProdutoID(const AValue: Integer): IParametersJsonObject; overload;

Define filtro de ProdutoID.

Parâmetros:

• AValue: Integer - ID do produto

Retorno: IParametersJsonObject

function ProdutoID: Integer; overload;

Retorna ProdutoID atual.

Retorno: Integer

CRUD

Todos os métodos CRUD seguem o mesmo padrão das outras interfaces.

Exemplo:

var Json: IParametersJsonObject;
Json := TParameters.NewJsonObjectFromFile('C:\Config\params.json')
  .ContratoID(1)
  .ProdutoID(1)
  .Title('ERP');
var Param: TParameter;
Json.Getter('database_host', Param);
if Assigned(Param) then
  ShowMessage(Param.Value);
Param.Free;

Utilitários

function Count: Integer; overload;

Conta parâmetros no objeto JSON.

Retorno: Integer

function Count(out ACount: Integer): IParametersJsonObject; overload;

Versão com parâmetro out.

function FileExists: Boolean; overload;

Verifica se o arquivo JSON existe.

Retorno: Boolean

function FileExists(out AExists: Boolean): IParametersJsonObject; overload;

Versão com parâmetro out.

function Refresh: IParametersJsonObject;

Recarrega arquivo JSON do disco.

Retorno: IParametersJsonObject

function ToJSON: TJSONObject; overload;

Retorna objeto JSON completo.

Retorno: TJSONObject

Exemplo:

var JsonObj: TJSONObject;
JsonObj := Json.ToJSON;
try
  ShowMessage(JsonObj.ToString);
finally
  JsonObj.Free;
end;

function ToJSONString: string; overload;

Retorna JSON como string formatada.

Retorno: string

Exemplo:

var JsonString: string;
JsonString := Json.ToJSONString;
ShowMessage(JsonString);

function SaveToFile(const AFilePath: string = ''): IParametersJsonObject; overload;

Salva JSON em arquivo.

Parâmetros:

• AFilePath: string (opcional) - Caminho do arquivo (usa FilePath se vazio)

Retorno: IParametersJsonObject

Exemplo:

Json.SaveToFile('C:\Config\params.json');

function SaveToFile(const AFilePath: string; out ASuccess: Boolean): IParametersJsonObject; overload;

Versão com retorno de sucesso.

Parâmetros:

• AFilePath: string - Caminho do arquivo
• out ASuccess: Boolean - True se salvo

Retorno: IParametersJsonObject

function LoadFromString(const AJsonString: string): IParametersJsonObject;

Carrega JSON de uma string.

Parâmetros:

• AJsonString: string - String contendo JSON válido

Retorno: IParametersJsonObject

Exemplo:

Json.LoadFromString('{"ERP":{"host":"localhost"}}');

function LoadFromFile(const AFilePath: string = ''): IParametersJsonObject; overload;

Carrega JSON de um arquivo.

Parâmetros:

• AFilePath: string (opcional) - Caminho do arquivo (usa FilePath se vazio)

Retorno: IParametersJsonObject

Exemplo:

Json.LoadFromFile('C:\Config\params.json');

function LoadFromFile(const AFilePath: string; out ASuccess: Boolean): IParametersJsonObject; overload;

Versão com retorno de sucesso.

Parâmetros:

• AFilePath: string - Caminho do arquivo
• out ASuccess: Boolean - True se carregado

Retorno: IParametersJsonObject

Importação/Exportação

function ImportFromDatabase(ADatabase: IParametersDatabase): IParametersJsonObject; overload;

Importa parâmetros do Database para JSON.

Parâmetros:

• ADatabase: IParametersDatabase - Interface Database de origem

Retorno: IParametersJsonObject

Exemplo:

Json.ImportFromDatabase(DB);

function ImportFromDatabase(ADatabase: IParametersDatabase; out ASuccess: Boolean): IParametersJsonObject; overload;

Versão com retorno de sucesso.

function ExportToDatabase(ADatabase: IParametersDatabase): IParametersJsonObject; overload;

Exporta parâmetros do JSON para Database.

Parâmetros:

• ADatabase: IParametersDatabase - Interface Database de destino

Retorno: IParametersJsonObject

function ExportToDatabase(ADatabase: IParametersDatabase; out ASuccess: Boolean): IParametersJsonObject; overload;

Versão com retorno de sucesso.

function ImportFromInifiles(AInifiles: IParametersInifiles): IParametersJsonObject; overload;

Importa parâmetros do INI para JSON.

Parâmetros:

• AInifiles: IParametersInifiles - Interface INI de origem

Retorno: IParametersJsonObject

Exemplo:

Json.ImportFromInifiles(Ini);

function ImportFromInifiles(AInifiles: IParametersInifiles; out ASuccess: Boolean): IParametersJsonObject; overload;

Versão com retorno de sucesso.

function ExportToInifiles(AInifiles: IParametersInifiles): IParametersJsonObject; overload;

Exporta parâmetros do JSON para INI.

Parâmetros:

• AInifiles: IParametersInifiles - Interface INI de destino

Retorno: IParametersJsonObject

function ExportToInifiles(AInifiles: IParametersInifiles; out ASuccess: Boolean): IParametersJsonObject; overload;

Versão com retorno de sucesso.

Navegação

function EndJsonObject: IInterface;

Método de navegação (retorna IInterface para compatibilidade).

Retorno: IInterface

Parameters.Types.pas

Tipo: Interno (re-exportado via Interfaces)
Linhas: 374
Responsabilidade: Define todos os tipos utilizados pelo sistema

Tipos Principais

TParameterConfigOption

Enum para opções de configuração:

• pcfNone - Nenhuma fonte
• pcfDataBase - Habilita Database
• pcfInifile - Habilita INI Files
• pcfJsonObject - Habilita JSON Objects

TParameterConfig

Set de opções de configuração:

TParameterConfig = set of TParameterConfigOption;

Exemplo:

var Config: TParameterConfig;
Config := [pcfDataBase, pcfInifile]; // Database com fallback para INI

TParameterDatabaseEngine

Enum para engines de banco de dados:

• pteNone - Nenhum engine
• pteUnidac - UniDAC
• pteFireDAC - FireDAC
• pteZeos - Zeos

TParameterDatabaseTypes

Enum para tipos de banco de dados:

• pdtNone - Nenhum
• pdtFireBird - FireBird
• pdtMySQL - MySQL
• pdtPostgreSQL - PostgreSQL
• pdtSQLite - SQLite
• pdtSQLServer - SQL Server
• pdtAccess - Microsoft Access

TParameterValueType

Enum para tipos de valor:

• pvtString - String/Texto
• pvtInteger - Inteiro
• pvtFloat - Float/Double
• pvtBoolean - Boolean
• pvtDateTime - Data/Hora
• pvtJSON - JSON Object

TParameterSource

Enum para fontes de dados:

• psDatabase - Banco de dados
• psInifiles - Arquivo INI
• psJsonObject - Objeto JSON

TParameterSourceArray

Array dinâmico de fontes:

TParameterSourceArray = array of TParameterSource;

TParameter

Classe que representa um parâmetro de configuração.

Propriedades:

• ID: Integer - Identificador único (Database)
• Name: string - Nome/chave do parâmetro
• Value: string - Valor do parâmetro
• ValueType: TParameterValueType - Tipo do valor
• Description: string - Descrição/comentário
• ContratoID: Integer - Filtro de contrato
• ProdutoID: Integer - Filtro de produto
• Ordem: Integer - Ordem de exibição
• Titulo: string - Título/seção/objeto
• Ativo: Boolean - Status ativo/inativo
• CreatedAt: TDateTime - Data de criação
• UpdatedAt: TDateTime - Data de atualização

Exemplo:

var Param: TParameter;
Param := TParameter.Create;
try
  Param.Name := 'database_host';
  Param.Value := 'localhost';
  Param.ValueType := pvtString;
  Param.Description := 'Host do banco de dados';
  Param.Titulo := 'ERP';
  Param.ContratoID := 1;
  Param.ProdutoID := 1;
  Param.Ordem := 1;
  Param.Ativo := True;
  
  Parameters.Insert(Param);
finally
  Param.Free;
end;

TParameterList

Lista gerenciada de parâmetros que herda de TList<TParameter>.

Métodos:

• ClearAll - Libera todos os objetos e limpa a lista

Exemplo:

var List: TParameterList;
List := Parameters.List;
try
  for var I := 0 to List.Count - 1 do
    ShowMessage(List[I].Name + ' = ' + List[I].Value);
finally
  List.Free; // Libera automaticamente todos os objetos TParameter
end;

Parameters.Consts.pas

Tipo: Interno (re-exportado via Interfaces)
Linhas: 497
Responsabilidade: Define todas as constantes utilizadas pelo sistema

Constantes Principais

Configurações Padrão

DEFAULT_PARAMETER_CONFIG: TParameterConfig = [pcfDataBase, pcfInifile];
DEFAULT_PARAMETER_CONFIG_DATABASE_ONLY: TParameterConfig = [pcfDataBase];
DEFAULT_PARAMETER_CONFIG_INIFILE_ONLY: TParameterConfig = [pcfInifile];
DEFAULT_PARAMETER_CONFIG_JSON_ONLY: TParameterConfig = [pcfJsonObject];
DEFAULT_PARAMETER_CONFIG_ALL: TParameterConfig = [pcfDataBase, pcfInifile, pcfJsonObject];

Arquivos

DEFAULT_PARAMETER_INI_FILENAME = 'parameters.ini';
DEFAULT_PARAMETER_INI_SECTION = 'Parameters';
DEFAULT_PARAMETER_JSON_FILENAME = 'D:\Dados\config.json';
DEFAULT_PARAMETER_JSON_OBJECT_NAME_ROOT = 'parameters';

Validação e Limites

MAX_PARAMETER_NAME_LENGTH = 255;
MAX_PARAMETER_VALUE_LENGTH = 65535; // 64KB
MAX_PARAMETER_DESCRIPTION_LENGTH = 1000;

Reordenação Automática

DEFAULT_PARAMETER_AUTO_REORDER_ON_INSERT = True;
DEFAULT_PARAMETER_AUTO_RENUMBER_ZERO_ORDER = True;
DEFAULT_PARAMETER_AUTO_REORDER_ON_UPDATE = True;

Mapeamentos

TDatabaseTypeNames: Array [TParameterDatabaseTypes] of string = (
  'None', 'Firebird', 'MySQL', 'PostgreSQL', 'SQLite', 'SQL Server', 'Access'
);

TEngineDatabase: Array [TParameterDatabaseEngine] of string = (
  'None', 'Unidac', 'FireDac', 'Zeos'
);

SQL Templates

Constantes SQL para criação de tabelas em diferentes bancos:

• SQL_CREATE_TABLE_POSTGRESQL
• SQL_CREATE_TABLE_MYSQL
• SQL_CREATE_TABLE_SQLSERVER
• SQL_CREATE_TABLE_SQLITE
• SQL_CREATE_TABLE_FIREBIRD
• SQL_CREATE_TABLE_ACCESS

Parameters.Exceptions.pas

Tipo: Interno (re-exportado via Interfaces)
Linhas: 567
Responsabilidade: Sistema completo de exceções e mensagens de erro

Hierarquia de Exceções

EParametersException (Base)
????????? EParametersConnectionException (Erros de Conex??o)
????????? EParametersSQLException (Erros de SQL)
????????? EParametersValidationException (Erros de Valida????o)
????????? EParametersNotFoundException (Par??metro N??o Encontrado)
????????? EParametersConfigurationException (Erros de Configura????o)
????????? EParametersFileException (Erros de Arquivo)
????????? EParametersInifilesException (Erros de INI)
????????? EParametersJsonObjectException (Erros de JSON)

Propriedades das Exceções

EParametersException = class(Exception)
  property ErrorCode: Integer;  // Código numérico do erro
  property Operation: string;  // Operação que gerou o erro
end;

Códigos de Erro (Organizados por Faixa)

• Conexão (1000-1099): 10 códigos
• SQL (1100-1199): 16 códigos
• Validação (1200-1299): 12 códigos
• Operação (1300-1399): 11 códigos
• Configuração (1400-1499): 9 códigos
• Arquivo (1500-1599): 13 códigos
• INI (1600-1699): 8 códigos
• JSON (1700-1799): 12 códigos
• Importação/Exportação (1800-1899): 9 códigos

Total: 90+ códigos de erro

Funções Auxiliares

function CreateConnectionException(...): EParametersConnectionException;

Cria exceção de conexão.

function CreateSQLException(...): EParametersSQLException;

Cria exceção de SQL.

function CreateValidationException(...): EParametersValidationException;

Cria exceção de validação.

function CreateNotFoundException(...): EParametersNotFoundException;

Cria exceção de não encontrado.

function CreateConfigurationException(...): EParametersConfigurationException;

Cria exceção de configuração.

function CreateFileException(...): EParametersFileException;

Cria exceção de arquivo.

function CreateInifilesException(...): EParametersInifilesException;

Cria exceção de INI.

function CreateJsonObjectException(...): EParametersJsonObjectException;

Cria exceção de JSON.

function ConvertToParametersException(...): EParametersException;

Converte exceção genérica para exceção do Parameters.

function IsParametersException(...): Boolean;

Verifica se uma exceção é do tipo Parameters.

function GetExceptionErrorCode(...): Integer;

Obtém código de erro de uma exceção.

function GetExceptionOperation(...): string;

Obtém operação de uma exceção.

Parameters.Database.pas

Tipo: Interno (Implementação)
Linhas: 4.912
Responsabilidade: Implementação completa de acesso a parâmetros em banco de dados

Classe: TParametersDatabase

Implementa IParametersDatabase com suporte a múltiplos engines e bancos de dados.

Características:

• ✅ Suporte multi-engine: UNIDAC, FireDAC, Zeos
• ✅ Suporte multi-database: PostgreSQL, MySQL, SQL Server, SQLite, FireBird, Access
• ✅ Conexão interna automática ou conexão externa
• ✅ Thread-safe com TCriticalSection - 14 métodos principais protegidos
• ✅ Lógica de ordem automática
• ✅ Criação automática de tabela
• ✅ Validação de estrutura de tabela

Thread-Safety:

• Campo FLock: TCriticalSection implementado
• 14 métodos principais protegidos: List, Get, Insert, Update, Delete, Exists, Count, Connect, Disconnect, Refresh, CreateTable, DropTable, Database, Connection
• Todos os métodos CRUD protegidos contra acesso concorrente
• Pronto para uso em ambientes multithread

Métodos principais já documentados na interface IParametersDatabase acima.

Parameters.Inifiles.pas

Tipo: Interno (Implementação)
Linhas: 1.476
Responsabilidade: Implementação completa de acesso a parâmetros em arquivos INI

Classe: TParametersInifiles

Implementa IParametersInifiles com preservação de comentários e formatação.

Características:

• ✅ Preservação de comentários e formatação
• ✅ Suporte a múltiplas seções
• ✅ Suporte a itens inativos (prefixo "#")
• ✅ Thread-safe com TCriticalSection
• ✅ Lógica de ordem automática
• ✅ Criação automática de arquivo

Métodos principais já documentados na interface IParametersInifiles acima.

Parameters.JsonObject.pas

Tipo: Interno (Implementação)
Linhas: 2.264
Responsabilidade: Implementação completa de acesso a parâmetros em objetos JSON

Classe: TParametersJsonObject

Implementa IParametersJsonObject com formatação JSON e detecção de encoding.

Características:

• ✅ Formatação JSON com indentação
• ✅ Detecção e conversão de encoding (UTF-8, UTF-16, ANSI)
• ✅ Suporte a múltiplos objetos
• ✅ Thread-safe com TCriticalSection
• ✅ Lógica de ordem automática
• ✅ Criação automática de arquivo

Métodos principais já documentados na interface IParametersJsonObject acima.

🎯 EXEMPLOS DE USO

Exemplo 0: Quick Start (mínimo)

uses Parameters;

var DB: IParametersDatabase;
var P: TParameter;
begin
  DB := TParameters.NewDatabase
    .Host('localhost')
    .Database('mydb')
    .TableName('config')
    .Connect;
  P := DB.Get('erp_host');
  if Assigned(P) then
  begin
    ShowMessage(P.Value);
    P.Free;
  end;
end;

Exemplo 1: Uso Básico com Database

uses Parameters;

var Parameters: IParametersDatabase;
var ParamList: TParameterList;
var Param: TParameter;

// Cria instância (conexão automática)
Parameters := TParameters.NewDatabase
  .TableName('config')
  .Schema('dbcsl')
  .ContratoID(1)
  .ProdutoID(1);

// Lista todos
ParamList := Parameters.List;
try
  for var I := 0 to ParamList.Count - 1 do
    ShowMessage(ParamList[I].Name + ' = ' + ParamList[I].Value);
finally
  ParamList.Free;
end;

// Busca um (com hierarquia completa)
Parameters
  .ContratoID(1)
  .ProdutoID(1)
  .Database.Title('ERP')
  .Getter('erp_host', Param);
try
  if Assigned(Param) then
    ShowMessage(Param.Value);
finally
  if Assigned(Param) then
    Param.Free;
end;

// Insere novo (ou atualiza se existir usando Setter)
Param := TParameter.Create;
try
  Param.ContratoID := 1;
  Param.ProdutoID := 1;
  Param.Titulo := 'ERP';
  Param.Name := 'teste_key';
  Param.Value := 'teste_value';
  Param.ValueType := pvtString;
  Parameters.Setter(Param); // Insere se não existir, atualiza se existir
finally
  Param.Free;
end;

Exemplo 2: Múltiplas Fontes com Fallback

uses Parameters;

var Parameters: IParameters;
var Param: TParameter;

// Cria instância com múltiplas fontes
Parameters := TParameters.New([pcfDataBase, pcfInifile, pcfJsonObject]);

// Configura Database
Parameters.Database
  .Host('localhost')
  .Port(5432)
  .Database('mydb')
  .Username('postgres')
  .Password('pass')
  .TableName('config')
  .Schema('public')
  .Connect;

// Configura INI (fallback)
Parameters.Inifiles
  .FilePath('C:\Config\params.ini')
  .Section('Parameters');

// Configura JSON (fallback)
Parameters.JsonObject
  .FilePath('C:\Config\params.json')
  .ObjectName('Parameters');

// Define ordem de prioridade
Parameters.Priority([psDatabase, psInifiles, psJsonObject]);

// Busca em cascata: Database → INI → JSON (com hierarquia completa)
Parameters
  .ContratoID(1)
  .ProdutoID(1)
  .Database.Title('ERP')
  .Inifiles.Title('ERP')
  .JsonObject.Title('ERP');
Param := Parameters.Getter('database_host');
try
  if Assigned(Param) then
    ShowMessage('Encontrado: ' + Param.Value)
  else
    ShowMessage('Não encontrado em nenhuma fonte');
finally
  if Assigned(Param) then
    Param.Free;
end;

Exemplo 3: Importação/Exportação

uses Parameters;

var DB: IParametersDatabase;
var Ini: IParametersInifiles;
var Json: IParametersJsonObject;
var Success: Boolean;

// Cria instâncias
DB := TParameters.NewDatabase
  .TableName('config')
  .Schema('public')
  .Connect;

Ini := TParameters.NewInifiles
  .FilePath('C:\Config\params.ini');

Json := TParameters.NewJsonObject
  .FilePath('C:\Config\params.json');

// Exporta Database → INI
Ini.ExportToDatabase(DB, Success);
if Success then
  ShowMessage('Exportado com sucesso!');

// Importa INI → JSON
Json.ImportFromInifiles(Ini, Success);
if Success then
  ShowMessage('Importado com sucesso!');

Exemplo 3b: Export INI ou JSON → Database (upsert)

Ao exportar para o Database, cada parâmetro é enviado com Setter: se já existir registro com a mesma chave (contrato_id, produto_id, titulo, chave), é feito UPDATE; senão INSERT. Não gera mais erro de chave duplicada.

uses Parameters;

var Ini: IParametersInifiles;
var DB: IParametersDatabase;
var Ok: Boolean;
begin
  Ini := TParameters.NewInifiles('C:\Config\params.ini');
  DB := TParameters.NewDatabase
    .Host('localhost')
    .Database('mydb')
    .TableName('config')
    .Schema('public')
    .Connect;

  // Exporta INI → Database (cada item: Setter = INSERT ou UPDATE)
  Ini.ExportToDatabase(DB, Ok);
  if Ok then
    ShowMessage('Exportado com sucesso (upsert).');
end;

Exemplo 4: Apenas arquivo INI

uses Parameters;

var Ini: IParametersInifiles;
var P: TParameter;
var L: TParameterList;
begin
  Ini := TParameters.NewInifiles('C:\Config\params.ini')
    .Section('ERP');

  P := Ini.Get('host');
  if Assigned(P) then
  begin
    ShowMessage(P.Value);
    P.Free;
  end;

  L := Ini.List;
  try
    for var I := 0 to L.Count - 1 do
      Memo1.Lines.Add(L[I].Name + '=' + L[I].Value);
  finally
    L.Free;
  end;
end;

Exemplo 5: Apenas JSON

uses Parameters;

var Json: IParametersJsonObject;
var P: TParameter;
begin
  Json := TParameters.NewJsonObjectFromFile('C:\Config\params.json')
    .ObjectName('ERP');

  P := Json.Get('api_url');
  if Assigned(P) then
  begin
    ShowMessage(P.Value);
    P.Free;
  end;

  // Salvar alterações em arquivo
  Json.SaveToFile('C:\Config\params.json');
end;

Exemplo 6: Setter (inserir ou atualizar um parâmetro)

uses Parameters;

var DB: IParametersDatabase;
var Param: TParameter;
begin
  DB := TParameters.NewDatabase
    .TableName('config')
    .Schema('public')
    .ContratoID(1)
    .ProdutoID(1)
    .Connect;

  Param := TParameter.Create;
  try
    Param.ContratoID := 1;
    Param.ProdutoID := 1;
    Param.Titulo := 'ERP';
    Param.Name := 'timeout_segundos';
    Param.Value := '30';
    Param.ValueType := pvtInteger;
    Param.Description := 'Timeout em segundos';
    DB.Setter(Param);  // INSERT se não existir, UPDATE se existir (upsert)
  finally
    Param.Free;
  end;
end;

Exemplo 7: Todos os parâmetros em um TJSONObject

É possível obter todos os parâmetros em uma variável TJSONObject, a partir de qualquer fonte (Database, INI ou JSON). O resultado usa o formato padrão: objeto Contrato (Contrato_ID, Produto_ID) e um objeto por título (ex.: ERP) com cada chave = { valor, descricao, ativo, ordem }. O chamador deve liberar o resultado (Result.Free).

uses Parameters;

var DB: IParametersDatabase;
var J: TJSONObject;
var S: string;
begin
  DB := TParameters.NewDatabase
    .Host('localhost')
    .Database('mydb')
    .TableName('config')
    .Connect;

  // Todos os parâmetros da fonte Database em um TJSONObject
  J := DB.ToJSON;
  try
    S := J.ToString;  // ou use J.Format(2) no Delphi para string formatada
    Memo1.Lines.Text := S;
  finally
    J.Free;
  end;
end;

A partir de INI ou JSON:

// INI
Ini := TParameters.NewInifiles('C:\Config\params.ini');
J := Ini.ToJSON;
try
  // usar J...
finally
  J.Free;
end;

// JSON (retorna novo objeto com cópia dos dados; caller libera)
Json := TParameters.NewJsonObjectFromFile('C:\Config\params.json');
J := Json.ToJSON;
try
  // usar J...
finally
  J.Free;
end;

// IParameters (merge de todas as fontes ativas)
Params := TParameters.New([pcfDataBase, pcfInifile]);
Params.Database.Host('localhost').Connect;
Params.Inifiles.FilePath('config.ini');
J := Params.ToJSON;
try
  // usar J...
finally
  J.Free;
end;

Exemplo 8: Tratamento de Erros

uses Parameters, Parameters.Intefaces;

var Params: IParametersDatabase;
begin
  try
    Params := TParameters.NewDatabase
      .Host('localhost')
      .Database('mydb')
      .Connect;
      
    ShowMessage('Conectado com sucesso!');
  except
    on E: EParametersConnectionException do
    begin
      ShowMessage(Format('ERRO DE CONEXÃO: %s'#13#10'Código: %d'#13#10'Operação: %s',
        [E.Message, E.ErrorCode, E.Operation]));
    end;
    on E: EParametersException do
    begin
      ShowMessage(Format('ERRO: %s'#13#10'Código: %d', [E.Message, E.ErrorCode]));
    end;
    on E: Exception do
    begin
      ShowMessage('Erro inesperado: ' + E.Message);
    end;
  end;
end;

🛡️ TRATAMENTO DE ERROS

O módulo Parameters possui um sistema completo de tratamento de erros com:

• ✅ 8 tipos de exceções específicas
• ✅ 90+ códigos de erro organizados por faixa
• ✅ Mensagens padronizadas e formatáveis
• ✅ Propriedades ErrorCode e Operation para rastreabilidade

Exemplo de Tratamento Completo

try
  Parameters := TParameters.NewDatabase.Connect;
except
  on E: EParametersConnectionException do
    // Tratamento específico de conexão
  on E: EParametersSQLException do
    // Tratamento específico de SQL
  on E: EParametersValidationException do
    // Tratamento específico de validação
  on E: EParametersException do
    // Tratamento genérico do Parameters
  on E: Exception do
    // Tratamento de exceções genéricas
end;

❓ FAQ

Como usar apenas Database?

var DB: IParametersDatabase;
DB := TParameters.NewDatabase
  .Host('localhost')
  .Database('mydb')
  .Connect;

Como usar Database com fallback para INI?

var Parameters: IParameters;
Parameters := TParameters.New([pcfDataBase, pcfInifile]);
Parameters.Database.Host('localhost').Connect;
Parameters.Inifiles.FilePath('config.ini');
// Get() busca primeiro no Database, depois no INI

Como importar dados do Database para JSON?

var DB: IParametersDatabase;
var Json: IParametersJsonObject;
DB := TParameters.NewDatabase.Connect;
Json := TParameters.NewJsonObject;
Json.ImportFromDatabase(DB);
Json.SaveToFile('export.json');

Como tratar erros de conexão?

try
  DB.Connect;
except
  on E: EParametersConnectionException do
    ShowMessage('Erro: ' + E.Message + #13#10'Código: ' + IntToStr(E.ErrorCode));
end;

Como usar no FPC/Lazarus?

O código é idêntico ao Delphi. Apenas certifique-se de:

1. Instalar Zeos Library (recomendado para FPC)
2. Configurar diretivas em ParamentersORM.Defines.inc (já configurado automaticamente)
3. Usar arquivo .lpr ou .lpi no Lazarus

// Exemplo no FPC/Lazarus (idêntico ao Delphi)
var Parameters: IParameters;
Parameters := TParameters.NewDatabase
  .Host('localhost')
  .Database('mydb')
  .Connect;

Nota: FireDAC não está disponível no FPC. Use Zeos, SQLdb (engine nativo FCL) ou UniDAC.

Posso ter chaves com o mesmo nome em títulos diferentes?

Sim! A partir da versão 1.0.1, é possível ter chaves com o mesmo nome em títulos diferentes. A validação considera ContratoID + ProdutoID + Título + Nome como chave única (hierarquia completa da constraint UNIQUE).

IMPORTANTE: Todos os métodos CRUD (Getter, Setter, Delete, Exists) respeitam essa hierarquia completa. Use Getter() e Setter() em vez de Get() e Update() (deprecated).

// Exemplo: Mesma chave em títulos diferentes
var Param1, Param2: TParameter;
Param1 := TParameter.Create;
Param1.Name := 'host';
Param1.Titulo := 'ERP';
Param1.Value := 'erp.example.com';

Param2 := TParameter.Create;
Param2.Name := 'host';  // Mesmo nome!
Param2.Titulo := 'CRM'; // Título diferente
Param2.Value := 'crm.example.com';

// Ambos podem ser inseridos com sucesso
Parameters.Insert(Param1, Success1);
Parameters.Insert(Param2, Success2);

O que acontece quando deleto a última chave de um título?

A partir da versão 1.0.1, a seção (INI) ou objeto (JSON) é removida automaticamente quando você deleta a última chave. Isso mantém os arquivos limpos e organizados.

// Se você deletar a última chave de um título:
Parameters.Delete('ultima_chave');

// A seção [Titulo] no INI será removida automaticamente
// O objeto "Titulo" no JSON será removido automaticamente
// Nota: Seções/objetos especiais como [Contrato] são preservados

📊 ESTATÍSTICAS DO PROJETO

🦎 COMPATIBILIDADE FPC/LAZARUS

O módulo Parameters foi totalmente adaptado para funcionar com Free Pascal Compiler (FPC) e Lazarus IDE, mantendo compatibilidade total com Delphi.

✅ Status de Compatibilidade

• ✅ 100% Adaptado para FPC/Lazarus
• ✅ Multi-plataforma: Windows, Linux, macOS
• ✅ Compatibilidade retroativa com Delphi mantida
• ✅ Thread-safe em ambas as plataformas

🔧 Características FPC/Lazarus

Engines de Banco de Dados Suportados

Plataformas Suportadas

Engine SQLdb (Lazarus)

Com FPC/Lazarus é possível usar o SQLdb (pacote nativo da FCL) em vez do Zeos: TSQLConnection, TSQLTransaction, TSQLQuery. Bancos suportados: SQLite, PostgreSQL, MySQL, SQL Server, Firebird. Access não é suportado pelo SQLdb.

• Requisito: Pacote sqldblaz (SQLdb) no Lazarus (normalmente já incluso) ou path para as units em fcl-db (ex.: D:\fpc\fpc\units\$(TargetCPU)-$(TargetOS)\fcl-db no .lpi).
• Como ativar: Em ORM.Defines.inc, descomentar {$DEFINE USE_SQLDB} e comentar {$DEFINE USE_ZEOS}. Apenas um dos dois pode estar ativo por build.
• FromConfig: Leitura de Config.db (SQLite) com TSQLite3Connection + TSQLQuery; mesma tabela e chaves (host, port, username, password, database, schema, database_type, database_dll). Ver Documentation/ROTEIROS_CONSOLIDADO.md.

📋 Requisitos para FPC/Lazarus

1. Free Pascal Compiler (FPC) 3.2.2 ou superior
2. Lazarus IDE 4.4+ (recomendado) - Versão detectada: 4.4
3. Zeos Library (recomendado) ou SQLdb (FCL) ou UniDAC
4. Diretivas de compilação: USE_ZEOS ou USE_SQLDB (FPC); FPC

🚀 Configuração Rápida

1. Instalar Zeos Library

# Via Online Package Manager no Lazarus
Package ??? Online Package Manager ??? Buscar "Zeos" ??? Instalar

2. Abrir Projeto no Lazarus

# Abrir arquivo .lpi ou .lpr
File ??? Open ??? ParamentersCSL.lpi

3. Configurar Diretivas

O arquivo src/ParamentersORM.Defines.inc já está configurado automaticamente para FPC:

{$IFDEF FPC}
  {$DEFINE USE_ZEOS}  // Ativado automaticamente
  {$UNDEF USE_FIREDAC} // Desativado (não disponível)
{$ENDIF}

📝 Exemplo de Uso no FPC/Lazarus

program ParamentersCSL;

{$IFDEF FPC}
  {$MODE DELPHI}
  {$IFDEF WINDOWS}
    {$APPTYPE GUI}
  {$ENDIF}
{$ENDIF}

uses
{$IFDEF FPC}
  Interfaces, Forms, LResources,
{$ELSE}
  Vcl.Forms,
{$ENDIF}
  Parameters;

var
  Parameters: IParameters;
begin
  Application.Initialize;
  
  // Uso idêntico ao Delphi
  Parameters := TParameters.NewDatabase
    .Host('localhost')
    .Port(5432)
    .Database('mydb')
    .Username('postgres')
    .Password('pass')
    .TableName('config')
    .Schema('public')
    .Connect;
    
  // Resto do código...
end.

🔄 Mapeamento de Units

⚠️ Limitações no FPC/Lazarus

Funcionalidades Apenas Windows

1. Access Database (.mdb)
   • Requer ADOX (ActiveX Data Objects Extensions)
   • Código protegido com {$IFDEF WINDOWS}
2. Registry
   • Windows Registry API
   • Condicionado com {$IFDEF WINDOWS}
3. SetEnvironmentVariable
   • Windows API
   • Condicionado com {$IFDEF WINDOWS}

Units Não Disponíveis

• System.IOUtils → Usa SysUtils no FPC
• System.Win.* → Usa unidades específicas do Windows no FPC

📁 Estrutura de Diretórios (FPC/Lazarus)

Estrutura de Compilação do Projeto

Compiled\
????????? EXE\
???   ????????? Debug\
???   ???   ????????? win32\          # $(BuildMode)\$(TargetOS)
???   ???   ????????? win64\
???   ????????? Release\
???       ????????? win32\
???       ????????? win64\
????????? DCU\
    ????????? Debug\
    ???   ????????? win32\
    ???   ????????? win64\
    ????????? Release\
        ????????? win32\
        ????????? win64\

Estrutura de Instalação do FPC/Lazarus (Detectada)

D:\fpc\
????????? fpc\                      # Free Pascal Compiler 3.2.2
???   ????????? bin\
???   ???   ????????? x86_64-win64\     # Bin??rios 64-bit
???   ???       ????????? fpc.exe       # Compilador principal
???   ???       ????????? ...
???   ????????? units\                # Units compiladas
???   ???   ????????? i386-win32\       # Units 32-bit
???   ???   ????????? x86_64-win64\     # Units 64-bit
???   ???   ????????? x86_64-linux\     # Units Linux (cross-compilation)
???   ????????? ...
????????? fpcsrc\                   # C??digo-fonte do FPC
????????? lazarus\                  # IDE Lazarus
???   ????????? lazarus.exe           # Execut??vel principal
???   ????????? ...
????????? config_lazarus\          # Configura????es do Lazarus
???   ????????? onlinepackagemanager\ # Pacotes OPM
????????? ccr\                      # Componentes e bibliotecas
????????? cross\                    # Ferramentas de cross-compilation
????????? projects\                # Projetos de exemplo

Caminhos Principais:

• Lazarus IDE: D:\fpc\lazarus\lazarus.exe
• FPC Compiler: D:\fpc\fpc\bin\x86_64-win64\fpc.exe
• Versão FPC: 3.2.2

🔧 Variáveis do Projeto

📚 Documentação Específica FPC/Lazarus

• 📄 Documentation/README_V1.0.md - Hub de documentação (inclui compatibilidade FPC/Lazarus)
• 📄 Documentation/ROTEIROS_CONSOLIDADO.md - Roteiros práticos consolidados (inclui SQLdb)
• 📄 Documentation/Analise/README.md - Índice técnico por módulo/unit

🧪 Testes de Compatibilidade

• ✅ Compilação no FPC 3.2.2
• ✅ Compilação no Lazarus 4.4 (detectado)
• ✅ Testes de unidades condicionais
• ✅ Testes de thread-safety
• ✅ Testes de importação/exportação

🏰 CASTLE ENGINE (OPCIONAL)

O Castle Game Engine é um framework de desenvolvimento de jogos 3D para Pascal/Object Pascal, compatível com Free Pascal e Delphi. Ele foi configurado no ambiente de desenvolvimento para permitir a criação de projetos de jogos separados.

✅ Status de Configuração

• ✅ Castle Engine instalado: D:\castle-engine
• ✅ Versão: 7.0-alpha.3.snapshot
• ✅ Variável de ambiente: CASTLE_ENGINE_PATH configurada
• ✅ Build-tool: Adicionado ao PATH
• ✅ Configurações VSCode/Cursor: Aplicadas
• ✅ Tasks de build: Configuradas

📋 O que é o Castle Engine?

O Castle Game Engine fornece:

• ✅ Renderização 3D (OpenGL, Vulkan)
• ✅ Física (usando Physics Integration)
• ✅ Áudio (OpenAL)
• ✅ Input (teclado, mouse, joystick, touch)
• ✅ Multi-plataforma (Windows, Linux, macOS, Android, iOS)
• ✅ Editor visual integrado

🔧 Configuração

A configuração completa está documentada em:

• 📄 .vscode/CASTLE_ENGINE_SETUP.md - Guia completo de configuração

🚀 Uso Rápido

Verificar Instalação

# Verificar versão
castle-engine --version

# Verificar variável de ambiente
echo $env:CASTLE_ENGINE_PATH

Compilar um Projeto Castle Engine

# Compilar em modo debug
castle-engine compile --mode=debug

# Compilar em modo release
castle-engine compile --mode=release

# Compilar para plataforma específica
castle-engine compile --os=win64
castle-engine compile --os=linux
castle-engine compile --os=android

Via Build Tasks no Cursor/VSCode

• Ctrl+Shift+B → Selecionar task:
  • Castle Engine: Verificar Versão
  • Castle Engine: Compilar (Debug)
  • Castle Engine: Compilar (Release)
  • Castle Engine: Limpar Projeto

🎮 Integração com Parameters

O Castle Engine pode usar o módulo Parameters para gerenciar configurações de jogos:

uses
  Parameters,  // Módulo Parameters
  CastleWindow;

var
  Window: TCastleWindowBase;
  Params: IParameters;
begin
  // Carregar parâmetros do jogo
  Params := TParameters.NewInifiles
    .FilePath('game_config.ini')
    .Section('Game');
  
  // Usar parâmetros
  Window.Width := StrToInt(Params.Getter('window_width').Value);
  Window.Height := StrToInt(Params.Getter('window_height').Value);
  
  Window.Open;
  Application.Run;
end.

⚠️ Nota Importante

O Castle Engine é opcional e não é necessário para o projeto ParametersORM atual. Ele foi configurado caso você queira criar projetos de jogos separados usando o mesmo ambiente de desenvolvimento.

Para habilitar o Castle Engine no projeto:

1. Configure CASTLE_ENGINE_PATH (já configurado)
2. Defina "castleEngine.enabled": true no .vscode/settings.json (se necessário)
3. Recarregue o Cursor: Ctrl+Shift+P → "Reload Window"

📚 DOCUMENTAÇÃO ADICIONAL

Documentação HTML Interativa

• Documentation/html/index.html - Documentação interativa completa com navegação dinâmica
  • Visão Geral com exemplos práticos
  • Roteiro de Uso (Interno e Externo)
  • Documentação completa de todas as interfaces
  • Exemplos de uso para todas as units internas
  • Sistema de busca e filtros

Documentação organizada em Documentation/

Hubs principais

• Documentation/README_V1.0.md - Hub (índice geral)
• Documentation/Arquitetura/ParamentersORM_Overview.md - Visão geral
• Documentation/Arquitetura/ParamentersORM_Arquitetura.md - Arquitetura
• Documentation/Analise/README.md - Índice de análise por módulo/unit
• Documentation/Versionamento/CHANGELOG.md - Changelog da documentação
• Documentation/Regras de Negocio/README.md - Índice de regras de negócio
• Documentation/Roadmap/ROADMAP_DOCUMENTACAO.md - Roadmap de documentação
• Documentation/Esboco_Telas/README.md - Esboços de telas (views)

Documentos técnicos consolidados (atalhos úteis)

• Documentation/ROTEIROS_CONSOLIDADO.md
• Documentation/LOGICA_DATABASE.md

🔗 REPOSITÓRIO GIT

GitHub

Repositório: [https://github.com/cslsolucoes/ParamentersORM.git](https://github.com/cslsolucoes/ParamentersORM.git)

Organização: cslsolucoes

Projeto: ParamentersORM

Clonar o Repositório

git clone https://github.com/cslsolucoes/ParamentersORM.git
cd ParamentersORM

Contribuindo

Contribuições são bem-vindas! Por favor:

1. Faça um fork do repositório
2. Crie uma branch para sua feature (git checkout -b feature/MinhaFeature)
3. Commit suas mudanças (git commit -m 'Adiciona MinhaFeature')
4. Push para a branch (git push origin feature/MinhaFeature)
5. Abra um Pull Request

Licença

Este projeto está licenciado sob a GPL-3.0 License - veja o arquivo LICENSE para detalhes.

Autor: Claiton de Souza Linhares
Data de Criação: 01/01/2026
Última Atualização: 10/02/2026
Versão: 1.0.4
Compatibilidade: ✅ Delphi 10.3+ | ✅ FPC 3.2.2+ / Lazarus 4.4+
Castle Engine: ✅ Configurado (Opcional)
Documentação: ✅ HTML Interativa Completa

Comparação com a versão anterior (e:\CSL\Paramenters)

O projeto ParamentersORM (este repositório) difere da pasta Paramenters principalmente na estrutura de pastas: aqui as units ficam diretamente em src/ (Commons, Database, IniFiles, JsonObject, Attributes, View), sem a subpasta src/Paramenters/. Defines usam ORM.Defines.inc; export INI/JSON→Database usa sempre Setter (upsert); SQL da tabela config está em conformidade com o config.sql de referência. Detalhes em CHANGELOG.md.

🔄 MUDANÇAS NA VERSÃO 1.0.2

Nomenclatura de Métodos

• ✅ Get() → Getter() (método Get() mantido como deprecated)
• ✅ Update() → Setter() (método Update() mantido como deprecated)

Hierarquia Completa de Identificação

• ✅ Todos os métodos CRUD respeitam a hierarquia: ContratoID, ProdutoID, Title, Name
• ✅ Constraint UNIQUE: (contrato_id, produto_id, titulo, chave)
• ✅ Getter(): Busca específica quando hierarquia configurada, busca ampla quando não configurada (compatibilidade)
• ✅ Setter(): Sempre requer hierarquia completa no TParameter recebido (INSERT se não existir, UPDATE se existir)