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