Introduction to BYG Shell

Byg Shell v2

This is an introduction to the BYG Shell shell extension as it is at the moment, this will probably serve as the basis to a manual later on.

This cartridge extension aims to give you the ability to :

• Execute external (as "on disk") commands with parameters from the standard BASIC C64 invite, without messing with your BASIC programs
• Run as much as possible along the JiffyDOS or JaffyDOS kernal extensions so you can benefit from DOS wedge and fast disk I/O, including on SD2IEC
• Add new external commands
• Play nicely along BASIC, and as much as possible avoid hitting the BASIC RAM space

Setup

The following files are needed in order to use the BYG shell :

• bygshell.crt : standard 8Kb .CRT cartridge file, to use with your favorite cartridge (Kung Fu Flash, Easy Flash, Ultimate 1541...) or emulator. Alternatively you can even burn your own cartridge with the bygshell.bin file
• bin files for external commands : copy those to a dedicated disk location or use the provided .D64 disk image
• help files (ending with the .hlp extension) : copy to the same location as the bin files

Operating environment

When you start the machine with the BYG Shell cartridge loaded, the machine environment and configuration are not changed (BASIC and Kernal versions, charset, colours). The shell only announces itself and you are greeted with the standard BASIC prompt.

From here, you can use all the classic BASIC commands and if you have those any JiffyDOS / JaffyDOS command (file and directory commands, DOS wedge, filebrowser).

The BYG Shell commands are starting with the star character : * You can type a shell command anywhere, either in the BASIC prompt or even in a BASIC program. When you run a shell command, the shell looks for the command first in its internal commands list, and if not found it tries to load the command from disk : if nothing has been configured, the lookup is done on the current disk device. If no current disk device is defined, it tries device 8. If either a bin files device number and / or a bin files path have been configured then the shell will only lookup for external commands on the bin files device / path location. This allows you to setup a directory for example on a SD2IEC drive containing all the external commands. The bin files device and path is also used to lookup external help files. You can view and set those using the *env internal command. At startud those are not defined.

Keyboard shortcuts

A set of shortcuts is available to facilitate screen navigation and typing. They are accessed using a master key invocation combination followed by a key press.

CTRL-K is mapped as the master key for the shortcuts. When you press CTRL-K the cursor changes color to green indicating that the system is waiting for the end of the key sequence

Existing shortcuts :

CTRL-K A   : go to the start of current logical screen line
CTRL-K E   : go to the end of the current logical screen line
CTRL-K C   : copy to clipboard from cursor position to start of logical line
CTRL-K D   : copy whole current line to clipboard
CTRL-K V   : paste from clipboard
CTRL-K DEL : delete from cursor position to end of line
CTRL-K HOME: delete all lines except current physical one
CTRL-K ^   : swap screens (up arrow), allows maintaining a text scratchpad

The text scratchpad (screen swapping) and the clipboard are only retaining text content, not color content. Those contents are cleared when the machine is resetted.

You can view the current clipboard content using the *env command.

The shortcuts are deactivated for the moment within the EDIT command for avoiding interference with the EDIT shortcuts.

Environment and BASIC

BASIC has been extended to handle 8 and 16 bits hexadecimal numbers using the $ prefix. You can poke $d020,$0e or sys $e2+$fc*$0100 if you want now.

Two BASIC variables are used to return values after execution of commands :

SH% : integer value SH$ : string value

You can view the following information using the *env command :

• clip : clipboard content
• cmd : last ran external command, still in memory
• sh$ : sh$ variable value
• sh% : sh% variable value
• Dev : current device
• BIN Dev : bin files device number
• BIN Path : bin files path prefix

Internal commands

The following internal commands are available :

*env : view and set environment variables

*env alone show the variables
*env -d <device> sets the binary files device number, you can add -q for quiet mode
*env -p <path> sets the binary path prefix, you can also add -q for quiet mode

    If needed, you can add "$" at the end of the path value to indicate that a ":" character is needed before the
    command filename, depending on the storage device you're using.

*help : list internal commands and accesses external help files

*help shows the available internal commands
*help <topic> shows external help files on commands or topics. You can try *help commands or *help keys

    The external help files are ASCII files that are converted for viewing by the help command.
    They use a colouring scheme according to the first character of each line :

    ```
    # Title
    : Main info
    * Subtitle
    - Sub content
    = Notes
    ```

*m : memory dump / alter command

The m command can be used to hexdump and modify memory content. You can use the following parameters : in hexadecimal, without prefix

Example : *m 0400 0428

You can rewrite the individual hex values in the output to modify memory or directly enter some data :

Example : *m 0400 41 42 43

External commands

External commands can be used from the BASIC prompt or withing BASIC programs. They usually don't interfere with the BASIC program environment with the exception of more memory heavy commands line koala or edit.

You can get an idea of the commands available using *help commands

What is an external command

An external command is a binary file loaded at $c000 with the following format that provides a specific function.

    // External command preamble
    * = $c000

    // start address of command
    .word start_address

    // command name for command cache checking
    .text "command name"

    // command code
start_address:
    // your code ...

You can explore the existing commands source or the hw.asm command source to build your own commands.

Parameters processing

An external command can have the following kind of parameters :

• String parameter : string value or quoted string using double quotes
• Option letter : an option letter or combination of options prefixed with the "-" character
• Option letter with value : an option letter with an integer value like : -n=42
• Filename pattern : a filename pattern using the "*" joker character
• BASIC string variable : a basic string variable like s$

Examples: menu one two "two words" cat keys.hlp -ap -h wc -l .asm head tes -n=3 *checksum file$

List of commands

The following external commands are available at the moment :

CAT

CAT prints the content of a single file or a list of files to screen CAT can perform an hexdump of files, with or without starting addresses Output is done asuming the input files are ASCII encoded when not in HEX mode You can exit CAT in paginate mode with Q, X or run/stop

*cat <file> [<file> ...]

print file(s) contents to screen
    options : 
    N = numbers all lines
    E = print $ at EOL
    B = numbers all non empty lines
    P = paginates output
    H = hexdump
    S = read C64 binary start address for hexdump
    A = convert input from ASCII to PETSCII

CHECKSUM

CHECKSUM performs a CRC16 on files, returns last one in SH%

*checksum <file> [<file> ...] [-q]

Calculates a CRC16 on files
    options :
    Q = don't print output

WC

WC counts lines, words and bytes of files

*wc <file> [<file> ...]

count lines / words / bytes of files
    options :
    L = count lines
    W = count words
    C = count bytes
    Q = don't print filename

LSBLK

LSBLK identifies and lists connected disk devices, it returns number of drives in SH% and devices list in SH$

*lsblk

Scan attached devices for disk drives
    options :
    Q = quiet mode
    H = help

JOIN

JOIN appends binary or text files to an output file.

*join

Append files to output
    options :
    A = append instead of create output file
    Q = quiet mode
    H = help

SEARCH

SEARCH performs pattern matching on files, and prints matching lines of files

*search <pattern> <file> [<file> ...]

search for pattern in files
    options :
    N = print line number
    L = print only line number
    V = lines not matching
    C = count lines matching

Note:
    patterns rely only on * character at the moment,
    you should also use * on start / end when needed

TOUCH

TOUCH creates empty files, by default the filetype is SEQ You can bypass filetype using the P option or by adding ,P to you filenames An error is thrown if a file already exists

*touch <file> [<file> ...]

create new empty file
    options :
    P = create PRG file instead of default SEQ
    S = size of fille to create (fill with # by default)
    B = byte value to use for filling
    T = create text compatible file (adds LF)    

DIFF

DIFF compares two files, and writes the differences The total number of different lines found so far is returned in SH% to BASIC You can run DIFF in quiet mode with the Q option

*diff <file1> <file2>]

compare files
    options :
    F = stop after first difference
    P = paginate output
    N = stop after N differences
    Q = quiet mode, only return value in SH%

HEAD

HEAD shows the first lines of files

*head <file> [<file> ...]

print first lines of files
    options :
    N = change max lines number
    Q = no filename
    V = always print filename
    P = paginate output
    A = convert input from ASCII to PETSCII

CHARS

CHARS displays a character set map by default You can display a colour palette with the C option

*chars
    display the character map
    options :
    H = show help
    C = map of colors

KOALA

KOALA loads and display a koalapaint image and wait for a key press The image is moved to the last VIC II bank for display

*koala <image>
    load and view Koala format image (.KLA file)
    options :
    K = wait for keypress

EDIT

EDIT is a small text editor allowing ASCII files editing If launched with a non-existing filename, EDIT will use the filename provided and create a new file when saving, if no name is provided, default filename is "tmp" Default filetype for file creation is SEQ, you can force filetype to PRG with ,P suffix on your filename EDIT will replace existing files when saving Memory management is limited at the moment, each update consumes memory

*edit [<file>]
    small text file editor, see edit.hlp
    default filename for new files is tmp

    -- File management --

    run/stop : quit without saving
    ctrl-x : quit and save
    ctrl-s : save file

    -- Editor --

    ctrl-a   : start of line
    ctrl-e   : end of line
    ctrl-w   : next word
    ctrl-k t : top of document
    ctrl-k e : end of document
    ctrl-k + : set mark
    ctrl-k - : goto mark

MENU

MENU allows the user to choice between different items presented in a non destructive list on screen The list can be displayed on the right (default) or left top side of screen The items come from the MENU parameters including files from current directory when pattern matching character is used (ex: MENU *.koa) When run/stop or q/x are pressed, sh%=0, sh$= non affected You can surround items containing spaces with double quotes. When using quoted values an expansion of the string is done using the % character, as follows :

• %% => %
• %' => "
• %$ => value of BASIC SH$ variable

Expansion still contains bugs

*menu <item>...
    menu popup, chosen item number in sh% and item content in sh$
    you can mix directory patterns in the items list
    when run/stop or q/x are pressed, sh%=0, sh$= non affected

    options:
    L = menu on left side (right side by default)

XFORM

xForm processes delimited files line by line, using a small set of commands applied to each line. (config file not implemented yet)

Commands available:

• SEP or : define separator to split each line
• SEL a,b,c... or * : select columns (or all with *) for processing / output
• WRITE : write selected columns with separator and new line
• WRITEC : same as write but without new line
• NL : write new line
• ECHO : write
• UPPER : converts selected columns to uppercase
• LOWER : converts selected columns to lowercase
• HEAD : process only lines
• SKIP : skip first lines of file
• LINEID : write line number
• FILTER : filter, keep lines where content is in column

*xform <file> <command>...| -f <config>
    xform performs commands listed on each line of the input file

    options:
    F = take commands from config file

CONV

Conv command provides file format conversion. Conversions are currently limited to what is available in the BIOS.

*conv <file>... -<input format> -<output format> [> <output file>]
    conv converts file formats

    options:
    A = ASCII
    P = PETSCII
    S = Screen codes
    U = Upper
    L = Lower

Example:

*conv test.txt -a -p > test_petscii
*conv test2.txt -a -u

SID

SID loads PSID file, show info and play songs. By default the first song is selected, you can change songs including while playing with -p= and stop play IRQ with -s You can use redirection to capture SID info.

*sid <file> [options]

Play SID file or show info on file
    options :
    P = Play SID file, you can give song number
    S = Stop playing
    I = Show info on SID file