___  _   _  _ __ | |_  ___  
 / __|| | | || '__|| __|/ _ \ 
| (__ | |_| || |   | |_| (_) |
 \___| \__,_||_|    \__|\___/ 
       


Version: 9


I. Introducción

Curto es una traducción completa de UF Forth al español.
Actualmente el trabajo de tracucción está en progreso por lo 
que el código fuente aún no contiene caracteres especiales 
del idioma y la traducción de los comentarios aún no se ha 
completado.

Este es un sistema Forth tradicional para la computadora 
virtual "uxn/varvara"[1]. "Curto" está escrito en Tal[2] y 
Forth y provee una interface de texto interactiva y un editor 
de pantalla. El sistema no es enebrado, compila a código UXN 
nativo, pero actualmente solo un mínimo de optimizaciones son 
realizadas. El mapeo entre código fuente Forth e instrucciones 
de la VM es relativamente directo por lo que la pérformance 
debería ser mas que suficiente para todas salvo las más 
críticas de las situaciones. Las celdas son de 16 bits, el 
sistema completo ocupa alrededor de 25k de memoria, siendo 
necesarios otros 4k para memoria de pantalla y buffers.


II. Compilando curto

Para compilar los archivos .rom, es necesario primero ensamblar 
el kernel y luego utilizarlo para generar archivos .rom 
adicionales con más funcionalidad:

    $ uxnasm kernel.tal kernel.rom
    ...
    $ uxncli kernel.rom <curto.f

Eato producirá los siguientes archivos:

    kernel.rom

	El kernel, que contiene la funcionalidad mínima para 
definir nuevas palabras.

    curto0.rom

	El kernel y las palabras esenciales.

    curto.rom

	La funcionalidad de "curto0.rom" junto a palabras para 
acceder puertos de dispositivo de "varvara" de manera más 
conveniente y algunas herramientas básicas (como `volcar`).

    curtox.rom

	El sistema Forth gráfico completo, incluído el editor 
de bloques.


III. Usando curto

Correr "curto0.rom" y "curto.rom" con "uxncli" como una 
aplicaciónde terminal normal. "curtox.rom" debe ser ejecutada 
con "uxnemu":

    uxnemu curtox.rom <argumentos ...>

Los argumentos de línea de comandos adicionales o entrada de 
consola serán redirigidos al prompt de entrada gráfica y 
pueden ser usados para realizar inicialización, etc.

En la interface gráfica las siguientes combinaciones de teclas 
tienen un significado especial ("^" significa tecla Control, 
"Sh" tecla Shift y "Alt" tecla Alt):

    Soporte español

    Alt-a   á
    Alt-e   é
    Alt-i   í
    Alt-o   ó
    Alt-u   ú
    Alt-n   ñ
    Alt-?   ¿
    Alt-!   ¡
   ^Alt-u   ü

    Atajos de teclado
	
    ^a      Salta al principio de la linea
    ^e      Salta al final de la linea
    ^c      Termina curto (salvo que un bloque modificado se 
encuentre abierto en el editor)
    ^d      Borra siguiente caracter
    ^k      Corta hasta el final de la linea o región marcada 
(y escribe a archivo ".snarf")
    ^u      Corta hasta el inicio de la linea o región marcada 
(y escribe a archivo ".snarf")
    ^x      Copia linea o región marcada a archivo ".snarf"
    ^v, ^y  Pega contenidos del archivo ".snarf"
    ^f      Salta a siguiente ocurrencia de palabra bajo el 
cursor
    ^s      Guarda cambios en el bloque en edición
    ^l      Limpia la pantalla (salvo en editor)
    ^g      Lee dígitos y salta al bloque indicado al pulsar 
ENTER (aborta con ESC)          
    ^r      Lee dígitos y copia bloque actual a nuevo al 
pulsar ENTER
    ^m      Lee dígitos y mueve el bloque actual a nuevo al 
pulsar ENTER (borra bloque de origen)
    ^ENTER  Alterna marcador de región

    Sh-Arriba   	   Recupera la última línea entrada o 
salta a bloque anterior
    Sh-Abajo 		   Salta al bloque siguiente
    Sh-Izquierda/Derecha   Salta entre bloque de código y 
documentación

Las teclas de flecha mantienen el significado habitual. 
Presionar ENTER ejecuta la linea actual (marcada por el 
cursor). Presionar ^ENTER alterna el modo de selección 
(marca), todas las lineas entre el principio de la marca y la 
linea actual son copiadas y escreitas a un archivo llamado 
".snarf" en el directorio actual una vez que se presiona ENTER 
o ^x.

Presionar el primer botón del ratón reposiciona el cursor. 
Presionar el tercer botón ejecutará la palabra debajo del 
puntero.
Mover la rueda de desplazamiento salta a bloque anterior o 
risuiente, cuando editando un bloque sin modificar.

Acceso al sistema de archivos es provisto por archivos de 
"bloque", cada bloque es nombrado por un número natural y 
contiene 2496 bytes (39 lineas de 64 columnas). Para editar un 
bloque entrar:

    <número de bloque> editar

La tecla ESC alterna entre modo de edición y prompt (salvo que 
el bloque actual contenga modificaciones sin guardar). La 
última linea contiene contadores indicando fila, columna, 
número de bloque actuales, largo de último texto copiaro, la 
cantidad de espacio restante en diccionario y un marcador 
indicando si el bloque actual contiene modificaciones sin 
guardar. Los bloques pueden ser cargados usando `cargar` y 
`atraves`. Nótese que la carga de bloques es realizada 
cambiando temporalmente la palabra para leer entrada de usuario 
(`consulta`) y tiene efecto cuando la linea actual ha sido 
procesada por completo. Esto implica que las palabras de carga 
no pueden ser invocadas recursivamente.

También es posible editar un bloque haciendo click con el 
tercer botón del ratón sobre una cadena de la forma "#nnnn" 
dónde "nnnn" es un entero decimal.

Si un archivo de 6 bytes llamado ".theme" es encontrado en el 
directorio actual, este será usado para establecer los colores 
del sistema durante el inicio. Los colores son utilizados de la 
siguiente mantera: #0 fondo, #1 texto, #2 última linea y #3 
selección.

El estado actual del sistema puede ser convenientemente 
almacenado como un archivo .rom en disco entrando:

    guardar <nombre de archivo>

La rom guardada posee exáctamente el mismo estado (pero con 
las pilas vacías) que cuando fué creada. Durante el inicio, 
la palabra diferida `arrancar` es invocada, puede ser 
redefinida para remplazarla por código de inicio propio.

También te alentamos a consultar el código fuente en 
"curto.f".

IV. Compatibilidad con otros Forths

Consulta el archivo "GLOSARIO" por una lista de palabras 
soportadas y los archivos extensamente comentados "kernel.tal" 
y "curto.f" para más información. El dialecto implementado en 
curto es mayormente compatible con el estandard Forth 2012[3] 
(traducido al español). Algunas notables diferencias son:


- El sistema es sensible a mayúsculas (`Abc` y `abc` nombran 
dos palabras diferentes)

- `hacer` y `?hacer` tratan el rango de índice como cantidades 
sin signo.

- La conversión numérica en `<# ... #>` trabaja 
exclusivamente con números de una celda.

- La aritmética de palabras dobles actualmente no está 
implementada.

- Las palabras que producen resultados buleanos no siempre 
generan -1 (`verdadero`) sino algún otro valor distinto de 
cero.

- No son soportadas multiples construcciones `mientras` en un  
bucle `empezar` ... `repetir`. 

El diccionario puede ser inspeccionado con las palabras 
`palabras`, `orden` y `.vocs`. Para decompilar palabras tanto 
de sistema como definidas por usuario puede utilizarse `ver`.


V. El ensamblador integrado

Es posible definir palabras que contengan una forma 
simplificada de Uxntal usando las palabras `codigo` y 
`fin-codigo`. Dentro de dicha definición, las siguientes 
palabras poseen un significado especial:

    BRK INC ...             ensambla instrucción op uxn
    " k r                   agrega bit de modificación a la 
instrucción previa
    $           ( u -- )    rellenar según número de bytes en 
pila
    #           ( c -- )    ensambla byte literal
    #"          ( x -- )    ensambla corto literal
    &           ( u -- )    define etiqueta
    ,           ( u -- )    referencia etiqueta previamente 
definida como distancia relativa de ramificación
    `    ( | <palabra> -- ) compila llamada inmediata a palabra 
curto
    !    ( | <palabra> -- ) compila salto inmediato a palabra 
curto
    ?    ( | <palabra> -- ) compila salto inmediato condicional 
a palabra curto

Currently only 16 labels can be defined. You can insert absolute
references to other Forth words using the sequence `' <word> #"`
or by using the syntax
Actualmente solo se puede definir 16 etiquetas. Se puede 
insertar referencias absolutas a otras palabras curto mediante 
la secuencia `' <palabra> #"` o utilizando la sintaxis

    ` <palabra`

para codificar una llamada inmediata (JSI) a una palabra curto.

Nótese que se requiere que la pila sea alineada a cortos y que 
las palabras código deben realizar el equivalente a "JMP2r" 
para retornar a la palabra que las llamó.

Un ejemplo:

    codigo contarbit8 ( x^ -- n^ )
        0 # SWP ( n x )
        1 &
        DUP 0 # EQU ( n x x=0 )
        2 , JCN ( n x )
        1 # SFT ( n x>>1 )
        SWP INC SWP ( n+1 x>>1 )
        1 , JMP
        2 &
        POP ( n )
        JMP " r
    fin-codigo


VI. Mapa de Memoria

   FFFF +--------------------------------+
        |       Buffer de pantalla   	 |
   F600 +--------------------------------+
        |     Buffer de carga de bloque	 |
   ec40 +--------------------------------+
        |                            	 |
        |        Espacio libre       	 |
        |                            	 |
        +--------------------------------+ < `aqui`
        | Palabras definidas por usuario |
        +--------------------------------+
        |          Kernel            	 |
   0100 +--------------------------------+
        |          Sin usar          	 |
   0000 +--------------------------------+

Curto permite hasta cuatro vocabularios activos al mismo 
tiempo. Se puede ver las palabras disponibles actualmente 
ejecutando `palabras` e inspeccionar la pila de vocabularios 
con `.vocs`. Los vocabularios predefinidos son `curto` (por 
defecto), `compilador` (palabras disponibles durante la 
compilación de palabras de dos puntos), `ensamblador`, 
`decompilador` y `editor`.


VIII. Problemas de implementación de la VM uxn

Curto ha sido testeado en SDL uxn[4] y uxn11[5].

En la interface gráfica los vectores de los dispositivos 
controlador, consola y ratón son modificados para recibir 
eventos de entrada. Durante la evaluación de código los 
vectores son temporalmente limpiados y un BRK o paro de 
máquina abortarán con error y retornarán al prompt curto. Si 
se desea modificar cualquiera de estos vectores de forma 
permanente, asegurarse de que el código no retorna al prompt 
interactivo o usar `esperar`, que invoca la palabra diferida 
`tick`, que puede ser modificada para realizar procesamiento 
personalizado (la implementación por defecto sólo hace 
parpadear el cursor).

El sistema gráfico establece el tamaño de pantalla a la 
resolución por defecto 512x320 que debe ser soportada por la 
implementación uxn subyacente.

Un número de palabras han sido definidas para acceder los 
dispositivos "varvara", consultar el GLOSARIO para más 
detalles:

Sistema:
    colores reiniciar limpiar profundidad vectore

Consola:
    cin  cout  tipearc  vectorc

Pantalla:
    tamanopantalla@  tamanopantalla!  posicion  pixel  auto  
datossprite
    sprite  vectorp

Audio:
    muestra tocar adsr volumen salida vectora

Controlador:
    teclaj botonj vectorj

Ratón:
    raton despr estador vectorr

Archivo:
    nombrearchivo escribirarchivo anexararchivo leerarchivo 
borrararchivo

Reloj:
    ano mes dia hora minuto segundo ddls dda eshdv

Nótese que las palabras de archivo solo utilizan el primer 
dispositivo de archivo (a0).

La entrada de consola en la interface gráfica es redirigida a 
la pantalla, osea que el límite de largo de linea aplica. Las 
lineas de entrada que exceden el ancho de la pantalla son 
cortadas silenciosamente y el texto que precede a la parte que 
excede ignorado.

Debido a limitaciones de la interface de archivo de "varvara" 
los archivos cargados mediante `incluir` (o `incluido`) no 
deben exceder el espacio disponible de diccionario dividido dos 
ya que el archivo debe ser cargado completamente en memoria 
antes de que pueda ser interpretado. Además, la inclusión de 
archivos no puede ser anidada.


IX. Licencia

UF Forth fué escrito por Felix L. Winkelmann y ha sido 
liberado al dominio público.
Curto fué traducido por maleza y se distribuye respetando 
estos términos.


X. Información de contacto


    maleza AT tilde DOT team
    o @maleza@meveilles.town en mastodon

El repositorio original de UF puede ser encontrado en [6], si 
desea seguir su desarrollo desde cerca.


XI. References

[1] https://100r.co/site/uxn.html
[2] https://wiki.xxiivv.com/site/uxntal.html
[3] https://forth-standard.org/
[4] https://git.sr.ht/~rabbits/uxn
[5] https://git.sr.ht/~rabbits/uxn11
[6] https://gitlab.com/b2495/uf