Path: Computer > Idle > ndir

ndir

ndir: Nerdy DIRectory command

ndir is a tool (written in the Idle Scripting Language) to process and display the contents of directories (or trees of directories). Following is the preliminary documentation for ndir. There is also a zip file with the full source code, the compiled version of the program and the documentation available (the documentation on the website may be a bit more up-to date).

The current version of ndir is 1.10. It is freeware released under the MIT licence and comes as-is, without any warranties. If you happen to find a bug or if you'd like to suggest a new feature please drop me a note.

There is also a beta of version 2.0 available.

**WARNING**: ndir is a command-line tool. Command lines can be difficult to write and even more difficult to debug; some people think command-line tools are cryptic beyond comprehension. If you are not comfortable with that sort of thing, a GUI utility, such as Explorer, may well be better suited.

Documentation

ndir is a directory lister on steroids: it supports complex search conditions which go far beyond wildcards. What's more, the output of the program (the list of files and directories found) can be tailored with the help of templates and colour schemes. There's also a simple interactive mode and the ability to directly execute commands on the found files/directories.

Help is available: you can get a general help screen or help specific to the -cond and the -#d and -#i switches. The first deals with conditions limiting the directory searches; the latter two with templates and interactive mode.

ndir -h                    ... prints a general help screen
ndir -cond=help            ... prints help for the -cond= switch
ndir -#d=help              ... prints help for the -#d= switch
ndir -h -#i                ... prints help for the -#i= switch
ndir -H                    ... prints general help and all other help screens

This is the full output the -H switch gives you:

c:\ >ndir -H
ndir [@FILE] [-h -H] [Switches] [Pattern Pattern...]
Lists files and directories

@FILE:       read switches and/or patterns from file FILE, with exactly one
             switch or pattern per line (empty lines are allowed; lines
             starting with '#' are ignored and can be used for comments).
             Switches given explicitly on the command line override values
             in FILE. Only one @FILE argument should be given.

  -h         print this help screen
  -H         print complete help (this screen, template help, conditions,
             date/time formats and interactive mode)

Switches for modifying the search:
  -d         process directories only (same as -mode=d)
  -f         process files only (same as -mode=f)
  -i         invert result of pattern matching (on a per-pattern basis)
  -j         ignore junctions while recursively processing subdirectories
  -r         the pattern(s) given are regular expression(s)
  -s         recurse into subdirectories
  -t         test and print parsed -cond=EXPR expression and exit
  -u         recurse into subdirectories and show summaries only
  -U         recurse into subdirectories and show top level summary only
  -v         print version information and exit
  -l=X[;Y]   start processing at directory level X and optionally stop at
             level Y (using -l= implies -s)
  -mode=MODE 'f' to process files only, 'd' to process directories only
             (default is 'df' to process both)
  -cond=EXPR expression to select entries by date or time stamps, attributes,
             size etc. If the template string contains spaces or other special
             characters the whole switch has to be enclosed in double quotes.
             -cond=help will print a short help screen for this option.

Switches for modifying the output (all display switches start with -#):
  -#a=AH;AN  set default colour attributes for header and normal lines; both
             values are decimal or hexadecimal numbers between 0/0x00 and
             255/0xff. The AN value is optional, if given it has to be
             separated from the AH value by a semicolon. (Default is 0x3b for
             header and the current console colour for normal lines.)
  -#b        generate a bare-bones listing, with full pathnames
             and no headers (same as specifying '-#f -#h -#t -#d=$f')
  -#c        send a copy of all output to the Windows clipboard
  -#e=K;F;D  define one or more external commands for interactive mode. K is
             the keycode (either a single ASCII character like a or p or a
             virtual keycode); F and D are the commands to execute if the
             currently selected item is a file or a directory, respectively.
  -#f        suppress display of header
  -#h        suppress display of footer
  -#i        enter interactive mode. Interactive mode ignores some switches,
             like -u/-U. It assumes that the display format (see -#d=) ends
             with the filename as long names are mid-truncated to make sure
             they fit on a single line. In interactive mode ndir tries to read
             ndir.xcmd from its start-up directory. This file can contain
             external command definitions (see the -#e= switch). If both -h and
             -#i are specified a help screen about interactive mode is printed.
  -#l        create a single big list, not a per-directory listing
  -#n        switch to case-insensitive sort (default is case-sensitive)
  -#r        reverse sort order ('-#o=size -#r' sorts descending by filesize)
  -#s        print size values etc. in long format
  -#t        suppress display of totals
  -#d=TMPL   display template used to format matching files/directories. If
             the template string contains spaces or other special characters
             the whole switch has to be enclosed in double quotes. If no
             explicit template is given file and directory names are printed
             with a default format ('$w $s $t$i$n$e').
             -#d=help will print a short help screen for this option.
  -#df=DFMT  format used to print dates (use $y $m $d for year month day;
             default is locale-dependent).
  -#tf=TFMT  format used to print times (use $H $M $S for hour(24) minute
             second; default is '$H:$M').
             -#tf=help will print a help screen with all format specifiers
             for -#tf as well as -#df.
  -#k=CMD    CMD is a template similar to a display template (see the -#d=
             switch for details). However, the resulting strings are not
             printed but collected and, after asking for confirmation, executed
             as a batch file. If CMD doesn't specify a filename macro,"$f" is
             appended to CMD.
             This switch should be used wisely: 'ndir -s "-#k=del /f /q"'
             happily will delete all files in a directory tree.
             If CMD is prefixed by a '!' then execution is forced: no files are
             listed and no confirmation is asked. If CMD is prefixed by a '?'
             then a separate confirmation is asked for every file.
  -#o=KEY    sort by 'date', 'size', 'name', 'ext'ension or full 'path'name;
             (default is first directories, sorted by name; then files, sorted
             by extension, then by name)
  -#x=EX;A   define one or more colouring conditions. EX is a conditional
             expression (see the -cond= switch), followed by the numerical
             colour attribute to use for output if the condition is true.
             (The included utility colors.idle/exe can be used to get
             colour attribute values.)

Pattern:     pathname(s), wildcard pattern(s) or regular expression(s)

Examples:
  ndir -f -#o=size c:\windows
  This lists all files in c:\windows, sorted by size (ascending).

  ndir -s -d -#o=date -#l c:\windows
  Prints a single list of all (sub-)directories in c:\windows, sorted by
  date stamp (of last write).

  ndir -i c:\windows\system32\*.dll
  Prints a list of entries in c:\windows\system32\ which are not .dll files.

-cond=EXPR   boolean expression to select entries by date, time, size,
             attributes etc.
-cond=@FILE  reads EXPR from file FILE

  EXPR is a boolean expression that decides whether a file or directory is
  included. The syntax supports the boolean operators <not> <and> <or> as well
  as the usual comparison operators (== != < > etc). Expressions may contain
  further subexpressions in parentheses.
  These predefined variables and functions are available in expressions:
    level    current (sub-)directory level (1 is the start level); numerical
    file     complete matched name of the entry (file or directory); string
    drive    drive part of the entry (including colon); string
    path     path part; string
    name     name part; string
    ext      extension part (including dot); string
    today    initialised with today's date (in the form YYYYMMDD); numerical
    date     date stamp (last write) of the entry (YYYYMMDD); numerical
    time     time stamp (last write) (HHMM, 24 hour-based); numerical
    tims     time stamp (last write) (HHMMSS, 24 hour-based); numerical
    adate    date stamp (last access) of the entry (YYYYMMDD); numerical
    atime    time stamp (last access) (HHMM, 24 hour-based); numerical
    atims    time stamp (last access) (HHMMSS, 24 hour-based); numerical
    cdate    date stamp (creation) of the entry (YYYYMMDD); numerical
    ctime    time stamp (creation) (HHMM, 24 hour-based); numerical
    ctims    time stamp (creation) (HHMMSS, 24 hour-based); numerical
    size     filesize (0 for directories); numerical
    attr     the entry's attributes ('acvdehinorpzst'); string
    A        true if the entry's archive bit is set; boolean
    C        true if compressed bit is set; boolean
    D        true if the entry is a directory; boolean
    E        true if encrypted bit is set; boolean
    H        true if hidden bit is set; boolean
    I        true if the entry is content-indexed; boolean
    R        true if read-only bit is set; boolean
    P        true if the entry is a reparse point or a symlink; boolean
    S        true if system bit is set; boolean
    range()  function to check a numerical range. It is called with three
             parameters: range(var,lo,hi), eg 'range(size,1024,1024*10)'
             will select files between 1kb and 10kb in size.
             Ranges can also be expressed by the syntax 'field in (lo,hi)';
             eg 'size in (1024,1024*10)'.
    match()  function to match a regular expression. It is called with two
             parameters: match(var,regex), eg 'match(name,'\\.(exe|dll)$')'
    rdate()  function to convert relative dates into date stamps: 'rdate(0)'
             can be used for today, 'rdate(-1)' for yesterday etc.

  -cond= switches containing spaces or characters with special meaning for the
   shell/command line (like > or <) have to be enclosed in double quotes.

Examples:
  ndir "-cond=date==20061231 or time>=1359" *
  This lists all files and directories with a datestamp of 2006/12/31 or a
  timestamp of 13:59 and later. (The -cond= switch has to be put in double
  quotes because it contains spaces.)

  ndir -s "-cond=(C and size>512) or (A and date==today)" *
  This recursively list all files that are either compressed and larger
  than 512 bytes or have the archive bit set and a date stamp of today.

-#d=TMPL     output template for matching files/directories
-#d=@FILE    reads TMPL from file FILE

  TMPL is a template string for printing the selected files/directories.
  Templates support the following placeholders:
    $d       is replaced with the drive part (including colon)
    $p       is replaced with the path part
    $n       is replaced with the name part
    $e       is replaced with the extension part (including dot)
    $f       is replaced with the complete name (ie $d$p$n$e)
    $a       is replaced with the last access time and date
    $c       is replaced with the creation time and date
    $w       is replaced with the last write time and date
    $i       is replaced with the directory flag (this is '\' for a directory
             and ' ' for a file)
    $l       is replaced with the numerical directory level
    $s       is replaced with the filesize
    $t       is replaced with the file attributes

    These macros are case-sensitive: $P, $F etc. won't work. A numerical value
    between the $ and the template character gives the width of the field;
    if the value is negative, the output is left-flushed.

    Template switches containing spaces or characters with special meaning for
    the shell/command line (like > or <) have to be enclosed in double quotes.

Example:     ndir "-#d=<$w> $s $t$i$-20n$e" *

The format templates for date and time strings (see -#df= and -#tf= switches)
support many placeholders (these macros should not be mixed-up with the macros
available for display templates (see -#d=)).

    $a       abbreviated weekday name
    $A       full weekday name
    $b       abbreviated month name
    $B       full month name
    $c       date and time representation appropriate for locale
    $d       day of month (01-31)
    $H       hour in 24-hour format (00-23)
    $I       hour in 12-hour format (01-12)
    $j       day of year (001-366)
    $m       month (01-12)
    $M       minute (00-59)
    $p       current locale's A.M./P.M. indicator for 12-hour clock
    $S       second (00-59)
    $U       week of year, with Sunday as first day of week (00-53)
    $w       weekday (0-6; Sunday is 0)
    $W       week of year, with Monday as first day of week (00-53)
    $x       date representation for current locale
    $X       time representation for current locale
    $y       year without century (00-99)
    $Y       year with century
    $z       abbreviated time-zone name; no characters if time zone is unknown
    $Z       time-zone name; no characters if time zone is unknown

In interactive mode, a list of all selected files is displayed. It is possible
to navigate this list with the <UP>, <DOWN>, <PAGE UP>, <PAGE DOWN>, <HOME> and
<END> keys. Additionally, pressing <DEL> twice deletes the currently selected
file (if not readonly) or directory (if empty).

Further keys and associated actions can be defined via the -#e=K;F;D switch.
K is the keycode (either a single ASCII character like a or p or a virtual
keycode); F and D are the external commands to execute if the currently
selected item is a file or a directory, respectively. If F is defined but not
D,then D is assumed to be F. The virtual keycodes are as follows (their meaning
should be obvious):
BS, TAB, ENTER, CAPS, ESC, SPACE, PGUP, PGDN, END, HOME, LEFT, UP, RIGHT, DOWN,
INS, DEL, F1 to F12

Commands can contain the macros $f, $p, $n, $e... also used for templates (you
may want to enclose these macros in double quotes). If no macro is used in a
command string, "$f" is appended to the string. After all macros in a command
strings have been expanded, the resulting string is executed by the currently
defined COMSPEC command processor.

If ndir is started in interactive mode, it tries to read a file with external
definitions called ndir.xcmd from its directory. See the included example for
more information.

Exit code

ndir returns an exit code to the operating system. This is either the number of files processed (which is 0 or greater than 0) or -1 if one of the help screens was requested or if an error occured.


$updated from: ndir.htxt Sat 18 Jan 2014 13:14:24 thomasl (By Thomas Lauer)$