Languages

Language Services

Internally, the command line interface (CLI) and language servers (which use the LSP) both depend on the a2kit::lang module. The CLI is designed for general use, while the LSP specifically targets editor clients.

Editor Support

The language servers each reside in their own executable. They can be used with any editor or IDE that supports the LSP. In some cases, a language client may choose to bundle the server. In others, the client may require that the server be installed in some standard location. One possible standard location is the user's cargo installation. When a user runs cargo install a2kit all of the servers are installed in the user's .cargo directory, and if they have done things in the usual way, their path should be preconfigured for them.

Screenshot of the Neovim client in action

Configuration Options

You may want to configure language analysis for use in either the CLI or LSP context. For the CLI, you have to prepare a JSON string using available keys. The JSON is case sensitive. For the LSP, the procedure varies depending on the editor or IDE involved.

There is a root key that may be required in the LSP context:

• Merlin = merlin6502
• Applesoft = applesoft
• Integer BASIC = integerbasic

CLI	LSP	Language	Key Path	Values	Notes
✓	✓	Merlin	/version	Merlin 8, Merlin 16, Merlin 16+, Merlin 32	select assembler
✓	✓	Merlin	/flag/caseSensitive	ignore, info, warn, error	flag lower case mnemonics
✓	✓	Merlin	/flag/unclosedFolds	ignore, info, warn, error	flag folds that are never closed
✓	✓	Merlin	/flag/unusedMacros	ignore, info, warn, error	flag macros that are never referenced
✓	✓	Merlin	/flag/unusedMacrosInContext	ignore, info, warn, error	flag macros defined in an include that are not referenced in the given context
✓	✓	Merlin	/flag/unusedLabels	ignore, info, warn, error	flag labels that are never referenced
✓	✓	Merlin	/flag/unusedLabelsInContext	ignore, info, warn, error	flag labels defined in an include that are not referenced in the given context
✓	✓	Merlin	/flag/missingEntries	ignore, info, warn, error	flag EXT labels for which no ENT is found
✓	✓	Merlin	/flag/dupMacLocs	ignore, info, warn, error	flag duplicate macro locals
✓	✓	Merlin	/linker/detect	float	threshold for treatment as link commands
	✓	Merlin	/completions/lowerCase	true, false	use lower case in completions
	✓	Merlin	/completions/ibas	true, false	offer Integer BASIC addresses in completions
	✓	Merlin	/completions/abas	true, false	offer Applesoft addresses in completions
✓	✓	Applesoft	/flag/caseSensitive	ignore, info, warn, error	flag lower case
✓	✓	Applesoft	/flag/terminalString	ignore, info, warn, error	flag missing unquotes
✓	✓	Applesoft	/flag/collisions	ignore, info, warn, error	flag colliding variable names
✓	✓	Applesoft	/flag/undeclaredArrays	ignore, info, warn, error	flag missing DIM statements
✓	✓	Applesoft	/flag/undefinedVariables	ignore, info, warn, error	flag variables that are never assigned
✓	✓	Applesoft	/flag/badReferences	ignore, info, warn, error	flag branches to non-existant lines
✓	✓	Applesoft	/flag/extendedCall	ignore, info, warn, error	flag extended CALL syntax
	✓	Applesoft	/completions/lowerCase	true, false	use lower case in completions
	✓	Applesoft	/completions/negativeAddresses	true, false	use negative addresses in completions
✓	✓	Integer	/flag/caseSensitive	ignore, info, warn, error	flag lower case
✓	✓	Integer	/flag/undeclaredArrays	ignore, info, warn, error	flag missing DIM statements
✓	✓	Integer	/flag/undefinedVariables	ignore, info, warn, error	flag variables that are never assigned
✓	✓	Integer	/flag/badReferences	ignore, info, warn, error	flag branches to non-existant lines
✓	✓	Integer	/flag/immediateMode	ignore, info, warn, error	flag immediate mode commands
	✓	Integer	/completions/lowerCase	true, false	use lower case in completions

Analysis

You can perform a language analysis using the verify subcommand:

a2kit get -f program.bas | a2kit verify -t atxt

To enter lines of code in the console, omit the input source:

a2kit verify -t atxt -s

The -s flag causes the syntax tree to be displayed. For more complex analysis you can specify a workspace path and configuration options:

a2kit get -f module.s | a2kit verify -t mtxt -w path/to/sources -c '{"version":"Merlin 16+"}'

The configuration options are given as a JSON string, see table below. The way the JSON is quoted (or not) depends on the shell.

If verify is inserted between pipeline nodes, and there were no errors, it will forward its input to the next node.

Renumber

You can renumber a BASIC language file using the renumber subcommand:

a2kit get -f program.bas | a2kit renumber -t atxt -b 0 -e 1000 -f 1 -s 1

This would renumber all lines with 0 <= line_number < 1000 starting on line 1 and stepping by 1. Both line numbers and references to line numbers are updated. The requested numbering has to be consistent with the existing numbering, e.g., when renumbering a segment it cannot cross into another segment, or else an error will be returned.

If you want to allow a block of lines to move to a space in between another two blocks of lines, use the --reorder flag.

When renumber Integer BASIC, be aware that line number references computed from an expression will not be automatically updated.

Minify

You can reduce the size of a language file using the minify subcommand:

a2kit get -f program.bas | a2kit minify -t atxt --level 1

The transformations this entails will generally depend on the language. As of this writing minify is only implemented for Applesoft BASIC. Note that in some cases further reduction can be obtained by using renumber. Increasing the minifier level increases the aggressiveness of the transformations. See table below.

Level	Transformations
0	identity
1	intra-line transformations: strip comments, reduce variable names, strip separators
2	delete unnecessary lines
3	combine lines where possible, minify ampersands

For self-contained Applesoft programs without ampersands, level 3 should be perfectly safe. If there is external code that references line numbers, levels 2 and 3 are unsafe, but can be guarded with --extern. If your ampersand parser does something unusual, level 3 is unsafe.

Tokenization

You can tokenize using the tokenize subcommand. For example, to error check and then tokenize Integer BASIC, use

a2kit get -f program.ibas | a2kit verify -t itxt | a2kit tokenize -t itxt

For Applesoft,

a2kit get -f program.abas | a2kit verify -t atxt | a2kit tokenize -t atxt -a 2049

You can detokenize using the detokenize subcommand. For example, to get an Integer BASIC program from a disk image and display the code, use

a2kit get -f program1 -t itok -d progs.dsk | a2kit detokenize -t itok

You can treat Merlin sources the exact same way, i.e., tokenize will put a Merlin source file in the format expected by the Merlin editor, and detokenize will make it readable as ordinary text:

a2kit get -f asm.prog.s | a2kit tokenize -t mtxt
a2kit get -f asm.prog.s -t mtok -d progs.dsk | a2kit detokenize -t mtok

Assembly and Disassembly

There is a limited Merlin assembler in a2kit. The assembler handles all processor instructions and addressing modes of the 6502 through 65816 processors. It handles all of the Merlin data pseudo-operations, plus a few more like ORG. It handles any valid Merlin expression. It does not handle macros, modules, or conditional assembly. It handles symbol values to the extent that the symbol table handed to it by the analyzer is complete. At present this is true only in limited cases. The assembler is invoked as a pipe:

a2kit get -f asm.prog.s | a2kit asm -a m8 -w /path/to/workspace 

where m8 refers to Merlin 8 (this can also be m16, m16+, or m32).

The assembler really exists (at present) to help with disassembly, i.e., to convert code to data during a disassembly session managed by higher level software. To invoke the disassembler from the CLI

a2kit get -f somebinary | a2kit dasm -p 65816 --mx 00 -o 32768

Here -p 65816 selects the target processor, --mx 00 sets the MX status bits, and -o 32768 is the starting address. The disassembler will recognize various data patterns including strings, but will do so only when the next few bytes cannot be interpreted as code.