
                                   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. 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>:

  - L: Displays Commodore filenames with the lowercase/uppercase character set
    (default).

  - 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.

  - 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 specify "\\" 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
file inside it. When scanning field specifiers, invalid  characters - ones not
listed below - are ignored  silently.  Field  specifiers  have  the  following
syntax:

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

  Note that you have to specify "%%" or "\$25" to display the "%" character.

  <width>:

  With these, you can first cut the strings into the width needed and then pad
them with spaces. Don't use numbers, indicated by  N,  higher  than  255.  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 undefined. The first group of width specifiers is  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.

  The second group of width specifiers is the following:

  - /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 Nth 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 those 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. For disk images, the  ID  code  is  excluded  and  all
    trailing Shift-spaces removed.

  - L: Container label.  For  disk  images,  the  five-character  ID  code  is
    included, separated with a comma.

  - 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,  as  if  no
     format specification file were 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,  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 may use it as long as you  wish  and  you  may
give it to any individual, provided that  it's  in  the  original,  unmodified
archive. It is highly recommended that you download distribution packages from
the homepage or other official distribution sites. If you get a  package  from
somewhere else then make sure that the  package  has  the  author's  authentic
verification stamped on it.

  The source of this program is distributed under a license that is similar to
the GNU Public License but is more restrictive,  for  the  protection  of  the
users and the author. You may  distribute  only  those  modified  versions  or
derived softwares that satisfy all  restrictions  in  the  license.  When  you
distribute this program, modified versions of it or softwares derived from it,
you may not ask for money above the  normal  fee  of  the  distribution  media
itself. Furthermore, you may not publish this program or its source on  floppy
disks, CD-ROM's, FTP sites, WWW pages or any other distribution media, include
it in a software compilation or bundle it  with  other  software  or  hardware
without prior permission of the author.

  Note that public distribution of  the  beta  releases  of  this  program  is
prohibited. The only place where you can find them is the homepage.

  This program is provided "as is", without a warranty of any  kind.  You  are
using it at your own risk. The author is not liable for  any  damage  or  data
loss caused by the software.



  5. The author

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

  Joe Forster/STA
  11th January, 2010
