Configuración
Todo esto que hemos comentado se llevará a cabo a partir de una configuración la cual reside en
múltiples partes del proyecto, y las mismas tendrán diferente prioridad a la hora de ser trabajadas,
pudiendo opacar parámetros o valores sobre otros. Esto está diseñado así para flexibilizar la
alteración de la configuración y que la configuración original persista.
Parámetros de configuración
La configuración se dividirá en parámetros los cuales responden como un diccionario donde se les
pone un nombre como llave y luego con valor o conjunto de valores dependiendo del caso. Dichos
parámetros los vamos a ir trabajando a continuación.
default_value
El valor por defecto hace alusión a un valor el cual no ha sido facilitado por nadie y que el propio
programa no es capaz de sacar, por lo que se le establece este valor por defecto. Es usado sobretodo
cara la configuración, entre otros aspectos, para valores que no se encontraron y no se les dio un
valor por defecto.
Dicho valor puede ser cualquier cosa y se aconseja que se implemente por un
administrador o desarrollador, en caso de no ser ninguno de ellos se aconseja no cambiar.
Su valor por defecto es null.
nulls
Este valor es de tipo Booleano y verifica si se admite, por defecto, respuestas nulas a la hora de
intentar acceder a un parámetro de la configuración. El permitir o no permitir valores nulos como
valor a una llamada de la configuración puede conllevar a variar el resultado. El no permitir nulos
no implica que no pueda responder un valor nulo puesto que es para gestionar el orden de priodidad
cara una posible respuesta.
Para información acerca de los niveles de la configuración ir a Niveles
de prioridad.
Pongamos un ejemplo, supongamos que tenemos un parámetro de configuración que no existe, y tenemos
la configuración por defecto, y lo llamamos. Si le ponemos un valor por defecto éste retornará dicho
valor por defecto, en caso contrario, retornará null aún a pesar de no tenerlo permitido, por no
haber otra opción de valor, cogiendo el valor por defecto establecido con el parámetro anterior.
-
Language
php
-
Lines
7
-
Characters
319
// Este ejemplo retornará "por_defecto".
echo "Con valor por defect: " . $wmarkdown->settings("no_existo", null, "por_defecto", false) . "<br />\n";
// Mientras que éste otro retornará null.
echo "Sin valor por defect: " . $wmarkdown->settings("no_existo", null, null, false) . "<br />\n";
wmarkdown_root
Nos indica la ruta absoluta a nuestro proyecto WMarkDown.
root
Nos indica la ruta absoluta a nuestro proyecto donde queremos implementar el WMarkDown.
documentation_path
Nos indica la ruta relativa desde la dirección establecida en el parámetro "root" de la
configuración donde se encuentran los ficheros de documentación WMarkDown.
html_files
Indica la ruta relativa desde la dirección establecida en el parámetro "root" donde se encontrará la
pequeña base de datos JSON que almacena el Path de los ficheros HTML generados a partir de la
documentación. Dicho fichero será usado por el WMarkDown para identificar los ficheros HTML creados,
los cuales serán eliminados para su actualización cada vez que se ejecute el WMarkDown para generar
los HTML de la documentación.
public_path
Indica la ruta relativa desde la dirección establecida en el parámetro "root" del directorio público
del proyecto donde establecer los archivos HTML que dan forma a los ficheros WMarkDown.
html_base
Indica la ruta relativa desde la dirección establecida en el parámetro "root" donde se encuentra el
archivo HTML que se usará de base para generar todos los documentos HTML de la documentación.
default_modules
Este parámetro implementa los diferentes módulos que se quieran aplicar al WMarkDown y los ordena a
partir de un diccionario. Su valor por defecto es el siguiente:
-
Language
json
-
Lines
8
-
Characters
319
{
"lists" : "\\WMarkDown\\Modules\\Lists",
"headers" : "\\WMarkDown\\Modules\\Headers",
"code_blocks" : "\\WMarkDown\\Modules\\CodeBlocks",
"paragraphs" : "\\WMarkDown\\Modules\\Paragraphs",
"font_formats" : "\\WMarkDown\\Modules\\FontFormats",
"checks" : "\\WMarkDown\\Modules\\Checks"
}
Cambiar el orden de estos elementos puede conllevar a que se solapen por el patrón de búsqueda con
el que se gestionan, como por ejemplo los párrafos, que buscan todo conjunto de líneas juntas para
unificarlas en un único párrafo, pueden solapar cabeceras, listas, etc.
hash_alphabet
Alfabeto a usar para generar los Hashes Random para generar identificadores automáticos no visibles
directamente sobre los usuarios finales. Este parámetro simplemente almacena caracteres con los que
trabajar para generar dichas cadenas aleatorias. El valor puede ser un String o un Array de
caracteres.
Hay que tener en cuenta que al ser usado para determinar identificadores únicos entre diferentes
entornos y lenguajes, los resultados nunca podrán iniciarse como un caracter numérico y por lo
tanto, obliga a que exista por lo menos un caracter no numérico dentro de la cadena.
Se le puso la cadena de Base58 de Bitcoin con la idea de que los caracteres sean identificables a
simple vista, eliminando los caracteres que puedan dar lugar a confusión como la O mayúscula contra
el 0.
IMPORTANTE: Es importante destacar que ha de haber por lo menos dos caracteres diferentes, y
que repetir caracteres dentro de una misma cadena simplemente les dará a los caracteres repetidos
mayor probabilidad contra los no repetidos, así como a más repeticiones más probabilidad de que
salgan en las cadenas finales. El hacer uso de cadenas vacías o con un solo caracteres implicará la
creación de bucles infinitos por el hecho de no conseguir una cadena única. También cabe destacar
que solo permitirá caracteres comprendidos en el alfabeto inglés de la A a la Z tanto mayúsculas
como minúsculas, distinguiendolos como caracteres diferentes; dígitos y guiones bajos, el resto de
caracteres serán descartados de su uso.
Ejemplos de implementación pueden ser los siguientes:
-
Language
php
-
Lines
24
-
Characters
938
// Aquí lo dejaríamos por defecto.
$wmarkdown = new WMarkDown();
// Aquí implementamos una cadena de caracteres reducida basada en una palabra.
$wmarkdown = new WMarkDown([
"hash_alphabet" => "Hola_a_todos"
]);
// Aquí cambiamos la cadena de Base58 por defecto a una Base64.
$wmarkdown = new WMarkDown([
"hash_alphabet" => "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
]);
// Aquí cambiamos la cadena de Base58 por defecto a una Base64 pero como Array.
$wmarkdown = new WMarkDown([
"hash_alphabet" => [
"A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R",
"S", "T", "U", "V", "W", "X", "Y", "Z", "a", "b", "c", "d", "e", "f", "g", "h", "i", "j",
"k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "0", "1",
"2", "3", "4", "5", "6", "7", "8", "9", "+", "/"
]
]);
Todas las opciones anteriores son válidas para funcionar. Ahora veamos ejemplos de resultados según
metamos unas cadenas u otras.
-
Language
php
-
Lines
47
-
Characters
1655
$wmarkdown = new WMarkDown();
$wmarkdown_b = new WMarkDown([
"hash_alphabet" => "Haha"
]);
$wmarkdown_c = new WMarkDown([
"hash_alphabet" => "¡Hola a todos!"
]);
$wmarkdown_d = new WMarkDown([
"hash_alphabet" => [
"A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R",
"S", "T", "U", "V", "W", "X", "Y", "Z", "a", "b", "c", "d", "e", "f", "g", "h", "i", "j",
"k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "0", "1",
"2", "3", "4", "5", "6", "7", "8", "9", "+", "/"
]
]);
$hashes = [];
while(count($hashes) < 10)
$hashes[] = implode(", ", [
$wmarkdown->get_hash(),
$wmarkdown_b->get_hash(),
$wmarkdown_c->get_hash(),
$wmarkdown_d->get_hash()
]);
print_r($hashes);
/*
Un ejemplo de resultado podría ser:
Array
(
[0] => Z6VqHQSjVai, HhHHaaHHhHH, saHloHoloot, H9CkFZsRRWi
[1] => aXGoD1FKsDf, aaHahahHaah, aoasoodooll, Ju3AT2FMolq
[2] => oiUAFV1yxts, ahaaaaaaaHa, taHtadaHsHs, kGYZhPE8jRj
[3] => xBiyMXuTcZ4, aahaHHHaaaH, soHoasdtolt, LniSyRb2Gib
[4] => cv5wY5rVRAH, hHhhaahhHaa, ddstoaolHod, bNDoLasg8WZ
[5] => ZnHW61uyJJQ, aHHHhaaHaah, atHltdltoto, OhFmtywPlge
[6] => bi5TNw5vc4p, HaHaHaHhaaa, HtloaaHtaHt, ZieE4Jj6gx6
[7] => vNCPVpwm1YM, HHaaHaaaHHH, aodtsttHoda, NSrEx8mBZ8X
[8] => zYd5FJXkYK5, aaaaaaHahHa, dadoodootda, O4uZBdZB5U4
[9] => rz4k1ydc9YR, aaaahaahaHa, oodaldatsao, eIFFpkdpmM4
)
*/
Es importante mencionar que a menos caracteres distintos, mayor es la probabilidad de que se repitan
los Hashes Random y por tanto, mayor consumo relativo, además de correr el riesgo de entrar en un
bucle infinito por haber consumido todas las posibilidades aleatorias según le haga falta al
WMarkDown.
Su valor por defecto es la cadena Base58 de Bitcoin, la cual es
123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
hash_length
Este parámetro indica la longitud de cada Hash Random que se vaya a crear, siendo mínimo 1 y máximo
los que se deseen. Hay que tener en cuenta que a menos caracteres más probabilidad de repetición,
además de mayor facilidad para acabar con todas las posibilidades dadas, y es importante tener en
cuenta dicho valor, sobretodo cuando trabajemos un número pequeño de caracteres para la creación de
los Hash Random. Un ejemplo de éste puede ser el siguiente:
-
Language
php
-
Lines
40
-
Characters
1244
$wmarkdown = new WMarkDown();
$wmarkdown_b = new WMarkDown([
"hash_length" => 3
]);
$wmarkdown_c = new WMarkDown([
"hash_length" => 20
]);
$wmarkdown_d = new WMarkDown([
"hash_length" => 7
]);
$hashes = [];
while(count($hashes) < 10)
$hashes[] = implode(", ", [
$wmarkdown->get_hash(),
$wmarkdown_b->get_hash(),
$wmarkdown_c->get_hash(),
$wmarkdown_d->get_hash()
]);
print_r($hashes);
/*
Un ejemplo de resultado puede ser el siguiente:
Array
(
[0] => aQEVtJ8Zmee, Ddd, w369wRfC7gcaik7c5SEP, u3thce2
[1] => DPMWqquJvYm, m2h, CDFMWW2VoHdsK776p4Hq, p5NqBFt
[2] => VSmhZo8eFbs, jwz, rfTw2p8U5tUZGPDK6vVC, f4oybwX
[3] => itKA4e4Zo5a, mqg, AMLDJQW8CdHp7XwXWNnj, G2cQtuY
[4] => dMHcTSD8VH2, Uo9, X8ZLvrKdVUHr1ZDJnyCA, JJgW288
[5] => hQBa83ER9yH, ZFN, EVwD2drQiy8akniWpuba, dYgaH5c
[6] => rqj9T3d3zXB, C9L, AuRPTjfp3usxLtAm3Q3N, Djy2RYm
[7] => siYZXPYEkHT, sCT, TiBjCAKGwNrP6vMqXdA6, MV62dUa
[8] => Ze3HBZFruaG, Lvk, YVMcpxFjZVcvrMz6JPwD, N2pwQFk
[9] => paoSrYYacZx, FB3, VVje5rZgQQTfxsuTFTa7, Zy4YVaT
)
*/
Su valor por defecto es 11.
special_code_blocks
Este parámetro determina en un Array los bloques de código especiales, es decir, aquellos que pueden
ser usados sobre un entorno cliente para resolver o crear cosas, como puede ser una extensión JS
como por ejemplo MermaidJS para la creación de diagramas. Estos bloques se ignorarán para su
tratamiento profundo como el Syntax Highlighting entre otros procesos que puedan llevar.
Su valor por defecto es "mermaid".
default_title
Título por defecto para archivos que no contienen ninguna cabecera de referencia para ser nombrados.
El valor por defecto es "Unknown", por el hecho de desconocer el contenido del mismo.
title
El título de una página Web que se presenta en la pestaña o barra de título por lo general viene el
nombre del sitio o concepto a mirar, acompañado en muchas ocasiones del contenido que se quiere
mostrar. En este caso se especifica el nombre del sitio, que por defecto es WMarkDown pero debe ser
cambiado por el nombre del proyecto donde se integre éste.
Fichero original
El archivo de configuración original se encuentra en el directorio JSON que se encuentra en el
directorio raíz del proyecto, y viene siendo un fichero llamado
WMarkDown.settings.json. Aquí se encontrará toda la configuración por defecto de la
aplicación. Si falta alguno de los parámetros de configuración la aplicación puede dar errores.
Por defecto, dicho fichero es tal que así:
-
Language
json
-
Lines
23
-
Characters
898
{
"default_value" : null,
"nulls" : true,
"wmarkdown_root" : "/mnt/d/Projects/WMarkDown",
"root" : "/mnt/d/Projects/WMarkDown",
"documentation_path" : "/WMD",
"html_files" : "/JSON/html.files.json",
"public_path" : "/Public",
"html_base" : "/HTML/WMarkDown.base.html",
"default_modules" : {
"lists" : "\\WMarkDown\\Modules\\Lists",
"headers" : "\\WMarkDown\\Modules\\Headers",
"code_blocks" : "\\WMarkDown\\Modules\\CodeBlocks",
"paragraphs" : "\\WMarkDown\\Modules\\Paragraphs",
"font_formats" : "\\WMarkDown\\Modules\\FontFormats",
"checks" : "\\WMarkDown\\Modules\\Checks"
},
"hash_alphabet" : "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz",
"hash_length" : 11,
"special_code_blocks" : ["mermaid"],
"default_title" : "Unknown",
"title" : "WMarkDown"
}
Niveles de prioridad
- Configuración dada en el input
- Creando un archivo JSON.
- Archivo JSON original.
WMarkDown