harbour-core/harbour/doc/en/dir.txt

/*
 * $Id$
 */

/*
 * The following parts are Copyright of the individual authors.
 * www - http://harbour-project.org
 *
 * Copyright 1999 Chen Kedem <niki@actcom.co.il>
 *    Documentation for: __DIR(), DIR, ADIR()
 *
 * See COPYING for licensing terms.
 *
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      __Dir()*
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Display listings of files
 *  $SYNTAX$
 *      __Dir( [<cFileMask>] ) --> NIL
 *  $ARGUMENTS$
 *      <cFileMask> File mask to include in the function return. It could
 *      contain path and standard wildcard characters as supported by your
 *      OS (like * and ?). If <cFileMask> contains no path, then SET DEFAULT
 *      path is used to display files in the mask.
 *  $RETURNS$
 *      __Dir() always returns NIL.
 *  $DESCRIPTION$
 *      If no <cFileMask> is given, __Dir() displays information about all
 *      *.dbf in the SET DEFAULT path. This information contains: file name,
 *      number of records, last update date and the size of each file.
 *
 *      If <cFileMask> is given, __Dir() list all files that match the mask
 *      with the following details: Name, Extension, Size, Date.
 *
 *      DIR command is preprocessed into __Dir() function during compile
 *      time.
 *
 *      __Dir() is a compatibility function, it is superseded by DIRECTORY()
 *      which return all the information in a multidimensional array.
 *  $EXAMPLES$
 *      __Dir()      // information for all DBF files in current directory
 *
 *      __Dir( "*.dbf" )         // list all DBF file in current directory
 *
 *      // list all PRG files in Harbour Run-Time library
 *      // for DOS compatible operating systems
 *      __Dir( "C:\harbour\source\rtl\*.prg" )
 *
 *      // list all files in the public section on a Unix like machine
 *      __Dir( "/pub" )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All(LFN)
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ADIR(),DIRECTORY(),SET DEFAULT,DIR
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Command
 *  $NAME$
 *      DIR
 *  $CATEGORY$
 *      Command
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Display listings of files
 *  $SYNTAX$
 *      DIR [<cFileMask>]
 *  $ARGUMENTS$
 *      <cFileMask> File mask to include in the function return. It could
 *      contain path and standard wildcard characters as supported by your
 *      OS (like * and ?). If <cFileMask> contains no path, then SET DEFAULT
 *      path is used to display files in the mask.
 *  $DESCRIPTION$
 *      If no <cFileMask> is given, __Dir() display information about all
 *      *.dbf in the SET DEFAULT path, this information contain: file name,
 *      number of records, last update date and the size of each file.
 *
 *      If <cFileMask> is given, __Dir() list all files that match the mask
 *      with the following details: Name, Extension, Size, Date.
 *
 *      DIR command is preprocessed into __Dir() function during compile
 *      time.
 *
 *      __Dir() is a compatibility function, it is superseded by DIRECTORY()
 *      which returns all the information in a multidimensional array.
 *  $EXAMPLES$
 *      DIR          // information for all DBF files in current directory
 *
 *      dir   "*.dbf"          // list all DBF file in current directory
 *
 *      // list all PRG files in Harbour Run-Time library
 *      // for DOS compatible operating systems
 *        Dir  "C:\harbour\source\rtl\*.prg"
 *
 *      // list all files in the public section on a Unix like machine
 *        Dir  "/pub"
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All(LFN)
 *  $SEEALSO$
 *      ADIR(),DIRECTORY(),SET DEFAULT,__DIR()*
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      ADIR()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Fill pre-defined arrays with file/directory information
 *  $SYNTAX$
 *      ADIR( [<cFileMask>], [<aName>], [<aSize>], [<aDate>],
 *            [<aTime>], [<aAttr>] ) --> nDirEnries
 *  $ARGUMENTS$
 *      <cFileMask> File mask to include in the function return. It could
 *      contain path and standard wildcard characters as supported by your
 *      OS (like * and ?). If you omit <cFileMask> or if <cFileMask> contains
 *      no path, then the path from SET DEFAULT is used.
 *
 *      <aName> Array to fill with file name of files that meet <cFileMask>.
 *      Each element is a Character string and include the file name and
 *      extension without the path. The name is the long file name as
 *      reported by the OS and not necessarily the 8.3 uppercase name.
 *
 *      <aSize> Array to fill with file size of files that meet <cFileMask>.
 *      Each element is a Numeric integer for the file size in Bytes.
 *      Directories are always zero in size.
 *
 *      <aDate> Array to fill with file last modification date of files that
 *      meet <cFileMask>. Each element is of type Date.
 *
 *      <aTime> Array to fill with file last modification time of files that
 *      meet <cFileMask>. Each element is a Character string in the format
 *      HH:mm:ss.
 *
 *      <aAttr> Array to fill with attribute of files that meet <cFileMask>.
 *      Each element is a Character string, see DIRECTORY() for information
 *      about attribute values. If you pass array to <aAttr>, the function
 *      is going to return files with normal, hidden, system and directory
 *      attributes. If <aAttr> is not specified or with type other than
 *      Array, only files with normal attribute would return.
 *  $RETURNS$
 *      ADIR() return the number of file entries that meet <cFileMask>
 *  $DESCRIPTION$
 *      ADIR() return the number of files and/or directories that match
 *      a specified skeleton, it also fill a series of given arrays with
 *      the name, size, date, time and attribute of those files. The passed
 *      arrays should pre-initialized to the proper size, see example below.
 *      In order to include hidden, system or directories <aAttr> must be
 *      specified.
 *
 *      ADIR() is a compatibility function, it is superseded by DIRECTORY()
 *      which returns all the information in a multidimensional array.
 *  $EXAMPLES$
 *      LOCAL aName, aSize, aDate, aTime, aAttr, nLen, i
 *      nLen := ADIR( "*.jpg" )     // Number of JPG files in this directory
 *      IF nLen > 0
 *         aName := Array( nLen )   // make room to store the information
 *         aSize := Array( nLen )
 *         aDate := Array( nLen )
 *         aTime := Array( nLen )
 *         aAttr := Array( nLen )
 *         ADIR( "*.prg", aName, aSize, aDate, aTime, aAttr )
 *         FOR i = 1 TO nLen
 *             ? aName[i], aSize[i], aDate[i], aTime[i], aAttr[i]
 *         NEXT
 *      ELSE
 *         ? "This directory is clean from smut"
 *      ENDIF
 *  $STATUS$
 *     R
 *  $COMPLIANCE$
 *      <aName> is going to be filled with long file name and not necessarily
 *      the 8.3 uppercase name.
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ARRAY(),DIRECTORY(),SET DEFAULT
 *  $END$
 */