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.
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.
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:
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%?!
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%?!
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%?!
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
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
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.
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.
If you're interested in some similarly useful utilities then contact me at the E-mail address sta.ANTI@SPAM.c64.org or visit my homepage at http://sta.c64.org.
Joe Forster/STA
11th January, 2010
(This page best viewed with any browser)