350 lines
14 KiB
Markdown
350 lines
14 KiB
Markdown
|
[[post_data {
|
||
|
|
"author" : "KyMAN",
|
||
|
|
"since" : 20210502,
|
||
|
|
"version" : 20210505
|
||
|
|
}]]
|
||
|
|
# 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-1 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.
|
||
|
|
|
||
|
|
```php
|
||
|
|
|
||
|
|
// 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:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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:
|
||
|
|
|
||
|
|
```php
|
||
|
|
|
||
|
|
// 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.
|
||
|
|
|
||
|
|
```php
|
||
|
|
|
||
|
|
$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:
|
||
|
|
|
||
|
|
```php
|
||
|
|
|
||
|
|
$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
|
||
|
|
*[[ignore 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í:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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.
|
||
|
|
|
||
|
|
[[html_data {
|
||
|
|
"title" : "WMarkDown - Configuración",
|
||
|
|
"url" : "https://wmarkdown.k3y.pw/es/doc/settings.html",
|
||
|
|
"author" : "Tarsier, KyMAN",
|
||
|
|
"since" : 20210502,
|
||
|
|
"version" : 20210505,
|
||
|
|
"key_words" : "Whalers,MarkDown,MediaWiki,WMarkDown,configuración,parámetros",
|
||
|
|
"description" : "Documentación y guía para gestionar la configuración de un WMarkDown.",
|
||
|
|
"project" : "WMarkDown",
|
||
|
|
"logo" : "https://wmarkdown.k3y.pw/images/wmarkdown.png",
|
||
|
|
"language" : "es"
|
||
|
|
}]]
|