Star List



  This program was designed to list the contents of image files and  Commodore
archive files onto the screen or into a text file. Star List  is  an  external
utility of The Star Commander but is also distributed separately.



  1. Usage

  STARLIST <filename> [-|/<options>] [<listname> [<formatname>]]

  <filename>:
  Enter the path, the name and the extension of files to be  listed.  You  can
use wildcards to list multiple files and you can use long filenames, too.

  <listname>:
  Type the path, the name and the extension of the list file here. If the file
already exists, the list will be appended to its contents. Note that you  have
to use a short file name. If you omit this parameter then the list  is  dumped
onto the screen.

  <formatname>:
  Specify the path, the name and the extension of the file that  contains  the
format specification. When omitted, the contents of image  and  archive  files
are listed in a format similar to the Commodore disk directory list, using the
lowercase/uppercase character set. If you specify a format file, a  list  file
must also be specified - the output may not go onto the screen.

  <options>:
    P: Breaks the list up to pages with pauses between so that  you  can  read
       what is on the screen. This option does nothing  when  listing  into  a
       text file.
    L: Displays Commodore filenames with the lowercase/uppercase character set
       (default).
    S: Lists files in directory structures recursively.
    U: Displays Commodore filenames with the uppercase/graphics character set.
    V: Turns verbose mode on which means that  the  label  of  disk  and  tape
       images and the load address of files  inside  images  and  uncompressed
       archives will also be displayed in the list.



  2. Format specification

  The format specification file, similarly to  the  format  parameter  of  the
"printf" instruction in the C language, may contain normal characters, special
characters and field specifiers. Additionally, you can use conditional blocks.
Carriage returns and line feeds are completely ignored throughout the file  so
you may wrap your lines anywhere.

  Special characters stand for and are replaced by a  normal  character.  They
  have the following syntax:

  \<specchar>

    Note that you have to type '\\' to display the '\' character.

  <specchar>:
     $xx: The character having the hexadecimal ASCII code 'xx'.
     B: Backspace.
     N: Line feed.
     R: Carriage return.
     S: Space.
     T: Tab.

  Field specifiers are replaced by a string taken from the data related to the
  current container file - image or archive file - or  the  current  Commodore
  file inside it. When scanning field specifiers, invalid  characters  -  ones
  not listed below - are skipped without any error messages. Field  specifiers
  have the following syntax:

  %[<width>][<flags>]<type>

    Note that you have to type '%%' to display the '%' character.

  <width>:
    With these, you can first cut the strings into the width needed  and  then
    pad it with spaces. Don't use numbers, indicated by "n", higher  than  63.
    Use width specifiers in the order they're grouped below - which is not the
    same as the order they're applied - and don't use any from the same  group
    twice, otherwise the result is unpredictable.  Width  specifiers  are  the
    following:

      n, +n: The string is padded with spaces from the left to "n"  characters
             if it's shorter than that.
         -n: The string is padded with spaces from the right to "n" characters
             if it's shorter than that.

         /n: The string is cut to its first "n" characters if it's longer than
             that.
        /-n: The string is cut to its last "n" characters if it's longer  than
             that.
        /+n: The first "n-1" characters are cut off the string, only the  part
             starting with the "n"th character is kept.

  <flags>:
    *: Displays the "sum" of the specified type: for 'f'/'F',  the  number  of
       containers; for 'n'/'N', the number of files in the current  container;
       for 's', the total size of files in blocks in  the  current  container;
       for 'S', the total size of file in bytes in the current container.  Has
       no effect on other types.
    G: Uses the GEOS form of types 'i', 'I', 'l', 'L',  'n'/'N'  and  't'/'T'.
       Has no effect on other types.
    H: Converts "invalid" PETSCII characters - ones that have no  exact  ASCII
       equivalent or are usually not allowed in file names  -  to  hexadecimal
       codes in the form of "%xy". Makes sense for types 'i',  'I',  'l',  'L'
       and 'n'/'N' and has no effect on other types.
    Q: Encloses the string into quotation marks, before padding it and cutting
       it to maximum width.
    U: Uses the uppercase/graphics  character  set,  instead  of  the  default
       lowercase/uppercase character set for types 'i', 'I', 'l', 'L', 'n'/'N'
       and 't'/'T'. Has no effect on other types.

  <type>:
    Unlike other parts of the format specifier, most types are case-sensitive.
    The lowercase version, usually, stands for the default or short form;  the
    uppercase version for the long form. Types related to containers  are  the
    following:

       b: Number of free blocks in disk images. 0 for other container formats.
       B: Number of free blocks in disk images,  including  the  ones  on  the
          directory track(s). 0 for other container formats.
    d, D: Drive letter, including the trailing colon.
       e: Short file extension, including leading dot.
       E: Long file extension, including leading dot.
       f: Short file name, excluding extension.
       F: Long file name, excluding extension.
       i: Short, two-character  ID  code  of  disk  images.  Empty  for  other
          container formats.
       I: Long, five-character  ID  code  of  disk  images.  Empty  for  other
          container formats.
       l: Container label, excluding the ID code for disk images.
       L: Container label, including the ID code for disk images.
       p: Short absolute path, excluding driver letter but  including  leading
          and trailing backslash.
       P: Long absolute path, excluding driver letter  but  including  leading
          and trailing backslash.
       r: Short absolute path, excluding driver letter, leading  and  trailing
          backslash.
       R: Long absolute path, excluding driver letter,  leading  and  trailing
          backslash.

    Types related to Commodore files inside the containers are the following:

       a: Load address of file, in hexadecimal, with a leading '$' sign. Empty
          for phantom files and files inside compressed - LHA, LHA  SFX,  ARC,
          ARC SDA and ZipCode - archives.
       A: First track and sector of file, in the form 'tt;ss', in disk images.
          Empty for other container formats.
       c: Closed/splat flag. Empty for closed, '*' for splat.
       C: Closed/splat flag. 0 for closed, 1 for splat.
    n, N: File name.
       s: File size, in blocks.
       S: File size,  in  bytes.  Displays  the  maximum  possible  value  for
          container formats that store the file size in blocks.
    t, T: File type.
       w: Write-protection flag. Empty for unprotected, '<' for protected.
       W: Write-protection flag. 0 for unprotected, 1 for protected.

  Data inside conditional blocks is used for formatting and the resulting text
  is output only if a condition is met. You may nest conditional  blocks  into
  each other, thus creating an "and" relation. For an "or" relation, you  have
  to create two blocks, with different conditions but the same  contents.  The
  syntax of conditional blocks is the following:

  %?<condition>...%?!

    Note that the symbol '%?!' ends the innermost conditional block.

  <condition>:
    ^: Outputs block only when  processing  the  first  file  of  the  current
       container.
    $: Outputs block only  when  processing  the  last  file  of  the  current
       container.
    H: Outputs block - and only that  block,  no  data  outside  it  -  before
       processing the first container, for a header.  You  shouldn't  use  any
       field specifier in this block because no data has been read yet.
    F: Outputs block - and only that block, no data outside it - after  having
       processed the last container, for a footer. You shouldn't use any field
       specifier, except for '%*f', in this block because all data has already
       been discarded.

  Examples:

  1. Display an output identical to the Commodore disk directory  list,  using
     the lowercase/uppercase character set:

%?^\r\nListing %D%P%F%E\r\n
\r\n
0 "%-16gl" %gI\r\n%?!
%-5s%-18gqn%1c%gt%w\r\n
%?$%b blocks free.\r\n%?!

  2. Display an output almost identical to the  unformatted  output,  when  no
     format specification file was given on the command line:

%?^\r\nListing: %D%P%F%E ("%gL")\r\n
Blocks         Name          Type\r\n
------  ------------------  -----\r\n%?!
%6s  %-18gqn  %1c%gt%w\r\n
%?$------  ------------------  -----\r\n
%6*s          %4*n files\r\n%?!

  3. A simple way of including directory lists in HTML text,  using  Netscape-
     style hexadecimal codes for invalid characters and appending  the  number
     of files having been listed:

%?h<HTML>\r\n
<TITLE>Directory list</TITLE>\r\n
<BODY>\r\n%?!
%?^Directory list of %D%P%F%E<P>\r\n%?!
<A HREF="file:%D%P%F%E">%ghn</A><BR>\r\n
%?$<P>\r\n%?!
%?fListed %*f files.\r\n
</BODY>\r\n
</HTML>\r\n%?!

  4. A simple way of creating a CSV file with a header  that  you  can  easily
     import into a database:

%?hidrive,ipath,iname,iext,fname,fblk,ftype,fsplat,fprot\r\n%?!
%/1D,"%/R","%F","%/+2E","%gn",%s,%/1ut,%C,%W\r\n

  5. Another format that can be imported into a database of the same structure
     as the previous example, only  there's  no  header  and  the  fields  are
     separated with Tabs instead of commas:

%/1D\t%/R\t%F\t%/+2E\t%gn\t%s\t%/1ut\t%C\t%W\r\n



  3. Error messages

  Invalid option
    The option is unknown.
  No known file formats found
    There are no known file formats among the specified files.
  Error reading format specification file
    The format specification file could not be opened or  data  could  not  be
    read from it for some reason.
  FILENAME.EXT not found
    The file does not exist.
  Cannot create FILENAME.EXT
    The file could not be created for some reason.
  FILENAME.EXT is not a valid <file type>
    The image file or archive file is corrupted.



  4. Copyright and legal issues

  This program is freeware. You can use it as long as you  wish  and  you  can
spread it as you like provided that it is in the original unmodified  archive.
Don't distribute single files only the whole package and don't ask  for  money
above the normal fee of the distribution media itself. This program may not be
included in any compilation or  sold  on  disk  or  CD-ROM  without  my  prior
permission.



  5. The author

  If you're interested in some similarly useful utilities you can contact me at
the E-mail address "sta@c64.org" or visit my homepage at "http://sta.c64.org".



  31st March, 2002                              Joe Forster/STA