Resaltador de código fuente

Esta es una utilidad para usar dentro del marco de herramientas que ya presenté anteriormente. Se trata de un resaltador de código con PHP. Funciona en localhost y puede resaltar código HTML, PHP, JS y CSS. Tiene la posibilidad de obtener código resaltado, con numeración de líneas y también permite comprimir el código resaltado. Es evidente que resaltar código hace que el tamaño final sea mayor, pues hay que cambiar los caracteres <, > por <, > respectivamente. Además el estilo hay que incluirlo en algún elemento como <span>. Pero la opción de código resaltado y comprimido puede incluso hacer que el resultado final sea de menor tamaño que el original. Además se puede enviar en una variable JavaScript y descomprimirlo en el navegador. Así ahorramos ancho de banda y la descompresión en el navegador es bastante rápida.

La necesidad de crear mi propio resaltador de código se fundamenta en que este sitio wextensible.com está orientado a exponer lo que voy aprendiendo sobre desarrollo web. Y presentar el código fuente es parte de este objetivo. Todos los que nos dedicamos al desarrollo web hemos usado alguna vez el "Ver código fuente" del navegador para aprender cómo está hecha una página. O al menos intentarlo pues no siempre lo conseguimos ya que un sitio en producción no tiene porque preocuparse de este aspecto. Y más últimamente que todos los sitios ya están incluyendo código minificado o minimizado (ver la página del buscador de Google por ejemplo).

Yo también he procedido a minimizar o minificar los documentos de este sitio en las semanas pasadas. También estos días expongo una herramienta para minimizar código. Pero para seguir cumpliendo el objetivo de ofrecer el código fuente he construido previamente este resaltador de código. Esta herramienta crea un recurso paralelo para cada documento HTML, PHP, CSS y JS conteniendo el código resaltado y comprimido. He incorporado un botón de Código en la barra superior para acceder al código del documento.

Descarga de la herramienta de resaltar código

Se ha de instalar primero el marco de herramientas y comprobar que funciona según lo esperado. Si es así puede ahora descargar el conjunto de carpetas tools-web.zip (61 KB) de este resaltador de código y descomprimirlas sobre la ya existente tools-web del marco de herramientas. Se debe permitir sobreescribir los archivos pues sólo se agregarán nuevos archivos no modificando ninguno de los anteriores. Tras esto habremos agregado lo siguiente en la carpeta tools-web:

• En la carpeta includes se agregan los siguientes módulos:
  • resaltador-codigo.php: Módulo para resaltar código.
  • xml-core.php: Un parseador de HTML que también he construido hace tiempo y que es necesario parcialmente para el resaltador. También será de utilidad en futuras herramientas que incorpore.
  • xml.php: Extensiones al parseador anterior con algunas funciones equivalentes a las que gestionan el DOM.
• En la carpeta piezas se agrega la carpeta resaltar-codigo que contiene los recursos de la herramienta que estamos tratando. Contiene estos archivos:
  • index.php: Interfaz HTML para gestionar la herramienta.
  • conf.txt: Configuración de la herramienta
  • resaltado.txt, lineas.txt y comprimido.txt: Archivos de texto donde guardar los resultados del proceso (el código resaltado, el resaltado con numeración de líneas y el resaltado comprimido).
• En la carpeta res se agregan los siguientes archivos y carpetas:
  • resaltador.js: JavaScript que descomprime el código.
  • resaltador.php: PHP que recibe una URL por GET y sirve el recurso paralelo del código resaltado y comprimido.
  • resaltador.css: CSS con las clases de estilo para el código resaltado.
  • ref: Una carpeta de referencias de los recursos parelelos con codigo resaltado y comprimido.
  • prueba.html y prueba.css: Documentos para probar la herramienta.

Funcionamiento de la herramienta de resaltar código

Esta herramienta usa el módulo xml-core.php. Se trata de un parseador con el que me apoyo para realizar múltiples cosas en mi marco de herramientas. Sin embargo en la herramienta actual sólo se usa la función extraer_atributos() contenida en ese módulo. Esta función permite valores sin comillas o atributos booleanos. Pero en ningún caso se verifica si el HTML está bien formado. Es importante tenerlo en cuenta pues el resaltado puede no ser correcto cuando los atributos HTML están mal formados.

Hay dos posibilidades de ejecución: resaltar el código de un archivo o de un contenido de texto. En el primer caso la herramienta detecta el tipo por la extensión del archivo (.html, .php, .js, .css). No está previsto ninguna otra extensión. Si lo que se va a resaltar es el contenido de texto se nos presentará un desplegable para indicar de qué tipo es. Si el texto es un trozo de código PHP debe siempre encerrarlo entre <?php y ?>.

La configuración del factor de recursos PCRE de PHP permite ampliar la cantidad de memoria destinada a las expresiones regulares. Por defecto viene con 100.000 para pcre.backtrack_limit y pcre.recusion_limit. Para documentos pequeños no es necesario que tenga un valor mayor de la unidad. Pero con documentos con muchos nodos (o elementos HTML), el motor de expresiones regulares de PHP puede quedarse sin memoria. Yo lo tengo por defecto en 15, lo que da un total de 1.500.000, valor con el que he podido realizar el resaltado de todos los documentos de este sitio sin problemas. Vuelvo a recordar que esta herramienta está destinada a un localhost, por lo que el uso de recursos no tiene porqué ser un factor crítico.

El proceso produce los siguientes resultados:

1. Texto resaltado que se presenta en la pestaña de resultados y que también se guarda en un archivo si se activó esta opción.
2. Código fuente del texto resaltado anterior con el objeto de que pueda copiarlo y trasladarlo a su destino sin tener que guardarlo en un archivo con la opción señalada antes.
3. Texto resaltado en líneas que también se presenta y se guarda si se activó esa opción.
4. Texto resaltado y comprimido
5. Texto resaltado y comprimido insertado en la expresión de JavaScript var contenidoResaltado = '...';.
6. Estos dos últimos textos tienen también un botón para descomprimir ese texto resaltado y comprimido en la misma herramienta y comprobar que funciona.

Veámos con un ejemplo sencillo lo que hace este resaltador de código. Supongamos que tenemos que resaltar esto:

<br />

El texto resaltado quedaría como esto:

<span class="c">&lt;br /&gt;</span>

que representado en esta página sería así:

<br />

El color viene especificado por class="c" según el estilo especificado en el archivo vinculado resaltador.css en esta misma página. Vemos que el texto original ocupa 6 bytes mientras que el resaltado tiene un tamaño de 35 bytes. Es irremediable que se incremente el tamaño pues estamos agregando nuevos elementos para dotar de estilo y además cambiamos los caracteres <,> por sus entidades <, >. Esto es un contratiempo que podemos evitar comprimiendo el código resaltado. Este ejemplo quedaría entonces así:

1@^|~?`$*,span_<c@br /^>

Se trata de una cadena donde todo lo que hay hasta el primer guion bajo "_" es el descriptor de compresión. A partir de ahí empieza el código comprimido. Es decir, el texto comprimido es <c@br /^>. El descriptor declara una serie de caracteres que codifican el contenido. Separado por una coma encontramos el tag que se usará para el resaltado, span en este ejemplo. Los caracteres de la primera parte del descriptor se eligen de entre un grupo de aquellos que menos aparezcan en cada texto. Luego se escapan con entidades de caracter para que no interfieran y se procede a comprimir. Así tenemos que <c...> se corresponde con <span class="c">...</span>.

Con documentos de gran tamaño se consigue una reducción no muy significativa pero que al menos no incrementa el tamaño original. Por ejemplo, el documento de este sitio ejemplos de aplicación del formulario emergente tiene un tamaño original de 69189 bytes. El resaltado se eleva hasta 125415 bytes con un incremento de 81.26 %. Pero comprimido ocupa 67326 bytes con una reducción de -2.69 % sobre el original.

Este código resaltado y comprimido hay que descomprimirlo con JavaScript. Entonces lo mejor es disponerlo en alguna estructura que JavaScript pueda leer. He decidido incluirlo en una variable:

Así podemos enviarlo en un documento al navegador del usuario y descomprimirlo allí usando resaltador.js, un script para ese cometido. Usamos las comillas simples para encerrar la cadena, pues así no tenemos que escapar las dobles que pudiera haber en el texto. Se escapan las simples que en todo caso se usan menos. Usando resaltador.js, que también está vinculado en esta página, descomprimimos dentro de un elemento <pre> quedando como sigue:

Se consigue ubicando ahí un elemento <pre id="ejemplo-codigo"></pre> donde el script del resaltador.js descomprimirá el código resaltado. Esta acción se ejecuta con la carga de la página. En la cabecera de esta página tenemos este código (ya a su vez presentado con esta herramienta de código resaltado):

Al script resaltador.js le ponemos async="true" pues no vamos a necesitar que se ejecute hasta que la página esté cargada. Entonces con el window.onload usamos la función descomprimirResaltado() para ejecutar la acción.

Es obvio que para trozos pequeños de código es preferible usar el código resaltado sin comprimir, pues así evitamos la ejecución de JavaScript ejecutando la descompresión. Pero si una página tiene mucho código resaltado hay que considerar la posibilidad de comprimirlo, pues aligeramos la transferencia del documento al navegador.

Opciones de la herramienta de código resaltado

Por último comentaré algunas cosas acerca de las opciones del resaltador de código que al mismo tiempo dan una panorámica de las posibilidades de esta herramienta. En primer lugar podemos seleccionar un tag para insertar el estilo. Es lógico usar un "span" pero sería también posible usar un elemento con un nombre más corto como "i". Aunque habría que modificarle el estilo itálica que tiene por defecto. De todas formas a efectos del comprimido es indiferente el tamaño del tag.

Podemos definir una serie de caracteres para el descriptor sobre los que la herramienta seleccionará automáticamente los que necesite. He dispuesto "!$*+`?@^|~" (sin las comillas que encierran esta cadena) con el guion bajo "_" como fin de descriptor . Todos deben ser ASCII-127 para aligerar el tamaño. Pero en la herramienta puede declarar otro conjunto, pues ella se encarga de escapar los existentes en el texto para poder usarlos como caracteres descriptores. No sería muy eficiente usar caracteres que aparezcan con frecuencia, pues la entidad de caracter se forma con &#n; donde n es el decimal del orden ASCII y por tanto ocupa más el escape que el propio caracter. No debe usarse "%" pues, aunque posible, también es usado por el marco de herramientas para otros propósitos. Ni por supuesto "&" pues es el que escapa en HTML.

Es posible declarar estilos diferenciados para los apartados del código. La tabla siguiente resume y agrupa esos apartados mostrando un ejemplo de cada tipo.

[1] <p>Texto</p>
[2] <hr />

<div>ABC</div>
<input value="ABC" />

ñ

<!-- comentario -->
<!DOCTYPE html>

@charset "utf-8";
/* comentario */                    
blockquote { color: blue; }

<?php
/* comentario */
$mivar = true;
function hacer($que){
   echo "ABC";
}
?>
<script>
    //comentario
    alert("hola");
    var patron = /.*/mg;
    var bool = true;
</script>

No hay límite para declarar clases. Los nombres de clases deberían ser lo más cortos posibles. He usado letras "a, b, c, ..." pero hay que tener en cuenta que estos nombres de clases pueden interferir con otros del documento. En ese caso habría que cambiar esos nombres, pero incrementa mucho el tamaño. Nunca uso nombre de clases tan poco significativos como class="a", pero aquí es una cuestión de no incrementar el tamaño final del código resaltado.

Se pueden formar vínculos a recursos externos, como por ejemplo a los <link href o <script src. Permite declarar una lista de configuración que en combinación con un documento PHP nos abrirá el código resaltado de ese recurso externo. Se ofrece para eso el script resaltador.php que es igual que el que tengo instalado en este sitio para gestionar la presentación del código fuente. Los recursos paralelos se almacenan en la carpeta ref de la herramienta. Se trata de un JavaScript conteniendo sólo la variable var contenidoResaltado = '...'; con el contenido resaltado y comprimido. Se usa como nombre del archivo JavaScript el del documento cuyo código se resalta, cambiando las barras por "_-". Por lo tanto ningún documento que se vaya a resaltar debe llevar esta combinación de caracteres en su nombre de archivo. No voy a entrar en más detalles sobre el resaltador.php, aunque es importante decir que la ruta se recibe con GET y hay que hacer un control de seguridad mínimo.