/*
 * $Id: dir.txt 9312 2008-09-05 00:08:34Z vszakats $
 */

/*
 * Las siguientes partes son derechos adquiridos de sus autores individuales.
 * www - http://www.harbour-project.org
 *
 * Copyright 2000 Alejandro de Grate <alex_degarate@hotmail.com>
 * Documentacin en Espaol de: __DIR(), DIR, ADIR()
 *
 * Copyright 1999 Chen Kedem <niki@actcom.co.il>
 *    Documentacin en Ingls de: __DIR(), DIR, ADIR()
 *
 * Vea doc/license.txt por los trminos de la licencia.
 *
 */

/*  $DOC$
 *  $FUNCNAME$
 *      __Dir()*
 *  $CATEGORY$
 *      Manejo de Archivos
 *  $ONELINER$
 *      Muestra por pantalla el listado de archivos.
 *  $SYNTAX$
 *      __Dir( [<cFileMask>] ) --> NIL
 *  $ARGUMENTS$
 *      <cFileMask> Mscara de archivos para incluir en el retorno de la
 *      funcin. Esta podra contener subdirectorios (path) y caracteres
 *      estndar usados como comodines, segun sean soportados por el sistema
 *      operativo (como * y ?). Si <cFileMask> no contiene la ruta al archivo
 *      entonces SET DEFAULT es usado para mostrar archivos en la mscara.
 *  $RETURNS$
 *      __Dir() siempre retorna NIL.
 *  $DESCRIPTION$
 *      Si ninguna <cFileMask> es dada, __Dir() muestra informacin acerca de
 *      todos los *.dbf en la ruta SET DEFAULT. Esta informacin contiene:
 *      - Nombre del archivo
 *      - Numero de registros
 *      - Fecha de la ultima actualizacin
 *      - Tamao de cada archivo.
 *
 *      Si <cFileMask> es dada, __Dir() lista todos los archivos que
 *      coinciden con la mscara en los siguientes detalles: Nombre,
 *      Extensin, Tamao, Fecha.
 *
 *      El comando DIR es pre-procesado en la funcin __Dir() durante el
 *      tiempo de compilacin.
 *
 *      __Dir() es una funcin de compatibilidad, esta fu superada por
 *      DIRECTORY(), la cual devuelve toda la informacin en un arreglo
 *      multidimensional.
 *  $EXAMPLES$
 *      <fixed>
 *      __Dir()   // Informacin de todos los DBF en el directorio actual
 *
 *      __Dir( "*.dbf" )       // Lista todos los DBF en el directorio actual
 *
 *      // Lista todos los PRG de la librera de ejecucin (RTL) de Harbour
 *      // para sistemas operativos compatibles con DOS
 *      __Dir( "C:\harbour\source\rtl\*.prg" )
 *
 *      // Lista todos los archivos de la seccin pblica sobre una mquina
 *      // tipo Unix
 *      __Dir( "/pub" )
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Informacin de DBF: CA-Cl*pper muestra nombres de archivos en el
 *      formato 8.3, Harbour muestra los primeros 15 caracteres si un nombre
 *      largo de archivo esta disponible.
 *
 *      Listado de archivos: para formatear los nombres mostrados usamos algo
 *      as como:
 *      PADR( Nombre, 8 ) + " " + PADR( Ext, 3 )
 *      CA-Cl*pper usa nombres de archivo 8.3, con Harbour probablemente se
 *      podra cortar los nombres largos de archivo para llenar este molde.
 *  $FILES$
 *      La librera es rtl
 *  $SEEALSO$
 *      ADIR()*,DIRECTORY(),SET DEFAULT,DIR
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      DIR
 *  $CATEGORY$
 *      Comando
 *  $ONELINER$
 *      Muestra el listado de archivos
 *  $SYNTAX$
 *      DIR [<cFileMask>]
 *  $ARGUMENTS$
 *      <cFileMask> Mscara de archivos para incluir en el retorno de la
 *      funcin. Esta podra contener subdirectorios (path) y caracteres
 *      estndar usados como comdines, segun sean soportados por el sistema
 *      operativo (como * y ?). Si <cFileMask> no contiene la ruta al archivo
 *      entonces SET DEFAULT es usado para mostrar archivos en la mscara.
 *  $DESCRIPTION$
 *      Si ninguna <cFileMask> es dada, __Dir() muestra informacin acerca de
 *      todos los *.dbf en la ruta SET DEFAULT. esta informacin contiene:
 *      - Nombre del archivo
 *      - Nmero de registros
 *      - Fecha de la ultima actualizacin
 *      - Tamao de cada archivo.
 *
 *      Si <cFileMask> es dada,__Dir() lista todos los archivos que coinciden
 *      con la mscara en los siguientes detalles: Nombre, Extensin, Tamao,
 *      Fecha.
 *
 *      El comando DIR es pre-procesado en la funcin __Dir() durante el
 *      tiempo de compilacin.
 *
 *      __Dir() es una funcin de compatibilidad, esta fu superada por
 *      DIRECTORY(), la cual devuelve toda la informacin en un arreglo
 *      multidimensional.
 *  $EXAMPLES$
 *      <fixed>
 *      __Dir()   // Informacin de todos los DBF en el directorio actual
 *
 *      __Dir( "*.dbf" )      // Lista todos los DBF en el directorio actual
 *
 *      // Lista todos los PRG de la librera de ejecucin (RTL) de Harbour
 *      // para sistemas operativos compatibles con DOS
 *      __Dir( "C:\harbour\source\rtl\*.prg" )
 *
 *      // Lista todos los archivos de la seccin pblica sobre una mquina
 *      // tipo Unix
 *      __Dir( "/pub" )
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Informacin de DBF: CA-Cl*pper muestra nombres de archivos en el
 *      formato 8.3, Harbour muestra los primeros 15 caracteres si un nombre
 *      largo de archivo est disponible.
 *
 *      Listado de archivos: para formatear los nombres mostrados usamos algo
 *      as como:
 *      PADR( Nombre, 8 ) + " " + PADR( Ext, 3 )
 *      CA-Cl*pper usa nombres de archivo 8.3, con Harbour probablemente se
 *      podra cortar los nombres largos de archivo para llenar este molde.
 *  $SEEALSO$
 *      ADIR()*,DIRECTORY(),SET DEFAULT,__DIR()*
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ADIR()*
 *  $CATEGORY$
 *      ARRAY
 *  $ONELINER$
 *      Llena arrays pre-definidos con informacin de archivo / directorio
 *  $SYNTAX$
 *      ADIR( [<cFileMask>], [<aNombre>], [<aTamano>], [<aFecha>],
 *            [<aHora>], [<aAtrib>] ) -> nEntradasDirectorio
 *  $ARGUMENTS$
 *      <cFileMask> Mscara de archivos para incluir en el retorno de la
 *      funcin. Esta podria contener subdirectorios (path) y caracteres
 *      estandar usados como comodines, segun sean soportados por el sistema
 *      operativo (como * y ?). Si <cFileMask> no contiene la ruta al archivo
 *      entonces SET DEFAULT es usado para mostrar archivos en la mscara.
 *
 *      <aNombre> Array para llenar con el Nombre de los archivos que cumplen
 *      con <cFileMask>. Cada elemento es una cadena de caracteres que
 *      incluye el Nombre y Extensin del archivo sin la ruta de acceso.
 *      Nombre es el nombre largo de archivo como es reportado por el sistema
 *      operativo y no necesariamente en el formato maysculas 8.3 del D.O.S.
 *
 *      <aTamano> Array  para llenar con el Tamao de los archivos que
 *      cumplen con <cFileMask>. Cada elemento es un nmero entero con el
 *      tamao del archivo en bytes.
 *      Los Directorios siempre tienen un tamao cero.
 *
 *      <aFecha> Array para llenar con la Fecha de la ultima modificacin del
 *      archivo que cumplen con <cFileMask>. Cada elemento es del tipo "Date"
 *
 *      <aHora> Array para llenar con la Hora de la ultima modificacin del
 *      archivo que cumplen con <cFileMask>. Cada elemento es una cadena de
 *      caracteres en el formato:      HH:MM:SS.
 *
 *      <aAtrib> Array para llenar con los atributos de los archivos que
 *      cumplen con <cFileMask>. Cada elemento es una cadena de caracteres,
 *      Vea DIRECTORY() por informacin sobre los valores de los atributos.
 *      Si Ud. pasa un array a <aAtrib>, la funcin va a devolver archivos
 *      con los atributos Normal, Oculto (H), sistema (S) y directorio (D)
 *      Si <aAtrib> no es especificado o es distinto de un array solo
 *      archivos con atributo normal porian ser devueltos.
 *
 *      Nota: Al momento de escribir esta documentacin todavia no haba
 *            informacin sobre el comportamiento de esta funcin con los
 *            atributos que poseen las maquinas tipo Unix.
 *  $RETURNS$
 *      ADIR() retorna el nmero de entradas de archivo que cumplen con la
 *      condicin establecida en la mscara <cFileMask>.
 *  $DESCRIPTION$
 *      ADIR() retorna el nmero de archivos y/o directorios que cumplen con
 *      un formato especificado, este tambien llena una serie de arrays con
 *      Nombre, Tamao, Fecha, Hora y Atributo de estos archivos.
 *      El array pasado debe ser pre-inicializado al tamao apropiado, vea el
 *      ejemplo ms abajo.
 *      Con motivo de incluir los atributos Oculto (H), sistema (S) o de
 *      directorio (D) <aAtrib> debe ser especificado.
 *
 *      ADIR() es una funcin de compatibilidad, esta fue superada por
 *      DIRECTORY(), la cual devuelve toda la informacin en un arreglo
 *      multidimensional.
 *  $EXAMPLES$
 *      <fixed>
 *      LOCAL aNombre, aTamano, aFecha, aHora, aAtrib, nLen, i
 *      nLen := ADIR( "*.jpg" )   // Nro de archivos JPG files en directorio
 *
 *      IF nLen > 0
 *         aNombre := Array( nLen )  // hace lugar para guardar la informac.
 *         aTamano := Array( nLen )
 *         aFecha  := Array( nLen )
 *         aHora   := Array( nLen )
 *         aAtrib  := Array( nLen )
 *
 *         FOR i = 1 TO nLen
 *             ? aNombre[i], aTamano[i], aFecha[i], aHora[i], aAtrib[i]
 *         NEXT
 *      ELSE
 *         ? "Este directorio no tiene ni pelusa"
 *      ENDIF
 *      </fixed>
 *  $STATUS$
 *     R
 *  $COMPLIANCE$
 *      <aNombre> esta yendo a ser llenado con nombres largos de archivo y
 *      no necesariamente con el formato maysculas 8.3 del D.O.S.
 *  $FILES$
 *      La librera es rtl
 *  $SEEALSO$
 *      ARRAY(),DIRECTORY(),SET DEFAULT
 *  $END$
 */


