### Como usar a ferramenta

Os pacotes debian estão disponíveis na informação de release.
Compilados contra Ubuntu 22.04.

Porém também tem disponibilizado pacotes pgdg para outras versões de PostgreSQL.

Caso precise compilar por algum motivo, as instruções de compilação/build estão no arquivo README
de cada pasta:
  * php/README --> para compilar o módulo em PHP
  * python/README --> para criar o egg e/ou instalar, com pybuild
  * postgresql/README --> para instalar na versão PostgreSQL do seu computador

Depois de instalado:

PostgreSQL 10+:
	CREATE EXTENSION metaphoneptbr;
	select metaphone_ptbr('qualquer');

PHP:
	<?php echo metaphoneptbr('qualquer'); ?>

Python 3:
	from metaphoneptbr import phonetic
	print(phonetic('qualquer'))

A ferramenta é útil para criar um conjunto de palavras associadas uma identidade fonética.
Esse mecanismo busca não a exatidão, mas a aproximação de um resultado fuzzy, no qual um conjunto
é representado, podendo-se refinar as sugestões de buscas por nomes de pessoas ou logradouros.


### 1. INTRODUÇÃO 

Metaphone for Brazilian Portuguese

O metafone é um algoritmo de transformação de texto baseado em regras 
fonéticas (http://en.wikipedia.com/wiki/Metaphone)

As regras foram baseadas em um trabalho conjunto publicado peal Prefeitura 
Municipal de Várzea Paulista (http://www2.varzeapaulista.sp.gov.br/metaphone),
durante o projeto REDECA, voltado à infância e adolescência.

Este port é uma variação para o português, ao menos o brasileiro.

### 2. O ALGORITMO

Assim como o Metaphone original e o Double Metaphone, o objetivo é criar uma 
palavra foneticamente representativa a partir da original utilizando as 
regras para o português brasileiro. Dessa forma, a busca é facilitada por 
transformar cerca de 10 a 50 palavras em uma única representação. O custo de 
uma pesquisa em um banco de dados tradicional para as variantes cai 
drasticamente, de forma que um segundo algoritmo de proximidade (levenshtein, 
similar text) para um ordenamento eficaz se torna viável pela menor 
quantidade de registros a serem analisados.

Basicamente, transforma uma palavra em uma forma fonética, a fim de que 
palavras foneticamente semelhantes possam ser encontradas, resolvendo a maior 
parte dos casos de busca de nomes de pessoas, ruas, além de permitir busca por
palavras foneticamente semelhantes em um dicionário. 

Pode-se dizer que o algoritmo simplifica a quantidade de símbolos das palavras,
mantendo apenas o essencial para identificar seu núcleo. No caso do português 
(e de várias outras línguas também), as consoantes são as letras que carregam a
identificação de uma palavra. Logo, considera-se trocar a palavra por símbolos 
que representam aquela sonoridade.

O algoritmo não é complexo computacionalmente. Seu valor está no estudo das 
regras fonéticas e o contexto das letras para determinação do som mais 
apropriado, algumas vezes analisando até duas letras à frente ou para trás. A
sua implementação foi construída visando simplicidade e agilidade.

Para simplificar a representação do algoritmo, tomemos as seguintes notações:

```
SIMBOLO - NOTACAO
------------------------------------------
^       - Representa o começo da palavra 
$       - Representa o fim da palavra
[]      - igual em regex: qualquer um dentro dos colchetes
v       - (minúsculo) representa uma vogal qualquer
c       - (minúsculo) representa uma consoante qualquer
.	- Qualquer letra
0	- (nulo) Representa que o símbolo foi ignorado e não mapeado.
letras em maiúsculo - representam uma vogal ou consoante real em particular
```

```
LETRAS 	-> REPRESENTAÇÃO FONÉTICA (COMENTARIOS)
------------------------------------------
^v	    -> v (ou seja, copia a vogal)
B   	-> B
C[AOU]  -> K
Cc  	-> K
C[EI]  	-> S
CHR	    -> K
CH	    -> X (regra mais genérica aplica-se por último)
C$	    -> K
Ç	    -> S
D   	-> D
F	    -> F
G[AOU]	-> G
G[EI]	-> J
GH[EI]	-> J
GHc	    -> G
^Hv	    -> v
H	    -> 0 (Outros casos de aparição de H devem ser ignorados)
J	    -> J
K	    -> K
LH	    -> 1 (não tem representacao no metaphone original)
Lv	    -> L
M	    -> M
N$	    -> M
NH	    -> 3 (não tem representação no metaphone original)
P	    -> P
PH	    -> F
Q	    -> K
^R	    -> 2 (não tem representação no metaphone original)
R$	    -> 2 (não tem representação no metaphone original)
RR	    -> 2
vRv	    -> R
.Rc	    -> R
cRv	    -> R
SS	    -> S
SH	    -> X
SC[EI]	-> S
SC[AUO]	-> SK (sim - duas letras porque tem sons distintos quando acompanhadas de U ou O).
SCH	    -> X
Sc	    -> S
S	    -> S (caso as outras regras não se apliquem, esta entra em vigor)
T	    -> T
TH	    -> T
V	    -> V
W[LRv]	-> V
Wc	    -> 0	(Exceto L e R, da regra acima)
X$	    -> X (o mais adequado seria KS, mas há de se considerar alguns nomes separados por espaços, tornando assim X uma representação mais interessante, embora não perfeitamente acurada)
^EXv	-> Z 
.EX[EI]	-> X 
.EX[AOU]-> X 
EX[EI]	-> X 
EX[AOU]	-> KS
EX[PTC]	-> S
EX.	    -> KS
[vCKGLRX][AIOU]X	-> X
[DFMNPQSTVZ][AIOU]X	-> KS
X	    -> X (caso nenhuma caso acima case com a palavra, aplica-se esta regra)
Y	    -> I (é tratado como vogal para todos os efeitos)
Z$	    -> S
Z	    -> Z
```

Acima encontra-se uma versão simplificada do algoritmo utilizado para transformação fonética.


A escolha em uma implementação à parte do código original se dá por duas razões principais:
1. O Metaphone original usa regras fonéticas americanas. O estrangeirismo na língua inglesa
   é resolvido com uma segunda string fornecida pelo Double Metaphone para resolver alguns
   empecilhos da primeira  versão. De  qualquer forma, o metaphone original não funciona de 
   forma satisfatória para o português.

2. Implementar uma terceira string variante a partir do código metaphone seria uma tarefa
   hercúlea e provavelmente seriam inseridos erros no código original, pela dificuldade em
   expandi-lo de forma apropriada. O código contém adaptações (em especial o Double Metaphone)
   que buscam abranger todas as palavras do mundo em uma representação fonética única. 
   Contudo a maneira utilizada para tal é inviável, porque as letras e os sons são contextuais
   à língua utilizada.

O algoritmo mantém  algumas convenções usadas no metaphone original e acrescenta outras, para sons
que não existem ou são considerados no inglês (o LH, NH).

A maior dificuldade do algoritmo atual é trabalhar com nomes estrangeiros, que praticamente fogem
das regras comuns de pronunciação, exigindo um trato quase à parte para alguns nomes, como  Harry.
Felizmente, esses tipos de nomes não são muito comuns, mas há outras formas de estrangeirismo mais 
complicadas de se tratar e que sempre vão precisar de um cuidado mais apurado ou uma convenção simbólica,
a fim de representá-los, mesmo que não 'soem' como o esperado na representação fonética, mas que possam 
ser enquadrados ao lado de nomes semelhantes em grafia para a busca se tornar efetiva.


 * * *

3. O FUTURO

Dado as principais dificuldades fonéticas práticas, encontramos três frentes de trabalho:
	a) Conversão fonética fiel à norma. Aqui as regras gramaticais são aplicadas e não
	são tratadas as exceções (como acontece com os nomes), exceto aquelas previstas 
	pela língua.
 
	b) Conversão fonética semi-fiel. Acrescenta algumas exceções práticas do cotidiano,
	buscando alcançar um equilíbrio entre a grafia e a fonética dos nomes que fogem à regra.
	Essa é a implementação atual.

	c) Conversão fonética coloquial. Visando nomes e exceções às regras, inclui todas as regras
	fonéticas comuns, mas as exceções tem mais força que as regras. A possível consequência a
	este uso é a simplificação da identidade fonética da palavra, a fim de capturar maior número
	de semelhantes. Difícil de definir as regras por serem subjetivas.

As conseqüências para essas frentes são a produção de diferentes metafones para as palavras, em grau
de fidelidade. Ou seja, para o primeiro caso, a chave fonética seria a mais completa e também a mais
restritiva, pois diminuiria o número de casos semelhantes. Para o último, seria a mais simples, mantendo
apenas a sonoridade mais marcante da palavra e teria um número de casos semelhantes muito mais alto.


 * * *