LPC Language Compiler Library

Parser and checker API for LPC (Lars Pensjö C) - an object-oriented programming language derived from C and developed originally by Lars Pensjö to facilitate MUD building on LPMuds.

Currently supports LDMud and FluffOS.

If you are lookin for the VS Code language server, please visit: https://marketplace.visualstudio.com/items?itemName=jlchmura.lpc

See CHANGELOG.md.

Example

For an example mudlib, pre-configured to work with LPC Language Services, see the Nightmare Residuum mudlib. This mudlib has been fully annotated with LPCDoc and can been successfully validated by the LPC Language Service and build task without errors.

If you love this package, you could

Semantic Analysis

Semantic analysis (sometimes refered to as the type checker) will perform many useful checks on your code, but you must opt-in to this feature. To enable semantic code analysis, set the diagnostics options to "on".

LPCDoc Comments

LPC Language Services uses JSDoc-style comments to provide additional context during hover and signature help.

Example:

/**
 * Attempts to run a command
 * @param {string} cmd - The command to run
 * @returns 1 if successful, otherwise 0
 */
int doCommand(string cmd) {
    return 1;
}

Similar to typed languages like TypeScript, the type annotations are optional but can provide valuable context to the language server. For more, see Type Annotations, below.

Disable Checks on Per-File Basis

Semantic checks can be disabled for a single file by placing a nocheck directive at the top of the file:

// @lpc-nocheck

this_object()

By default, the type checker will assume this_object() refers to the file in which you are working. At runtime, that is not always the case, in particular when the file is included in a larger object. If needed, the type checker can be instructed to override the object type of this_object() by using a comment directive placed at the top of the file:

// @this_object /std/living

Ignoring a single line - @lpc-ignore

You can instruct the checker to ignore errors on a single line by adding the @lpc-ignore comment directive:

// @lpc-ignore - ignore int to string assignment error
string foo = 123;

Disabling checks for a single file - @lpc-nocheck

Diagnostics can be disabled for an entire file by addding a @lpc-nocheck comment directive to the top of the file.

// @lpc-nocheck
... statements

Expect an error - @lpc-expect-error

Indiciates that the next line is expected to return an error. If it does not, the directive will be flagged as an error

// @lpc-expect-error: method does not exist
o->foo();

Type Annotations

In many instance, the type checker can automatically infer the type of an object. For example:

object itm = clone_object("std/item");

However, often times a parameter or variable gives the type checker no information as to its type (other than object). Consider this example in which ->query_name() will report an error, because it cannot validate that the function exists on object player:

void welcomePlayer(object player) {
  write("Hi " + player->query_name());
}

This can be solved by using a type annotation in a doc comment:

/**
 * @param {"/std/player.c"} player - The player to welcome
 */
void welcomePlayer(object player) {
  write("Hi " + player->query_name());
}

Annotations can also be used on variables and return statements:

/**
 * @returns {"/std/player.c"} The current player object
 */
object getPlayer() {
  return lookupPlayer();
}

void testWeapon() {  
  object player = getPlayer();
  /** @type {"/std/weapon.c"} */
  object weapon;
  
  if (player) {
    weapon = player->getWeapon();
    weapon->runTest();    
  }  
}

Setting up your workspace

The VS Code LPC Language Services extension does not use your MUD driver to compile code. As such, several configuration options are available to help the language server understand the structure of your mudlib.

Workspace Root vs Lib Root

First create an lpc-config.json file that is used to store setting for the language server. This file must be located in your workspace root, or in your lib root. If no config file is found, the language server will still work but won't be able to take advante of global include files, include search dirs, etc.

For example, see this GLPU Fork in which the config file is placed in the workspace root.

Driver Options - driver

| Setting | Description | | --------- | ---------------------------------------------------- | | type | Driver type. Valid options are ldmud or fluffos. | | version | The driver version string, i.e. "3.6.7" |

Include - include

Specifies an array of filenames or patterns to include in the program. These filenames are resolved relative to the directory containing the lpc-config.json file.

Default: **/*

Example:

{
  "include": ["lib/**/*"]
}

Exclude - exclude

Specifies an array of filenames or patterns that should be skipped when resolving include.

Important: exclude only changes which files are included as a result of the include setting. A file specified by exclude can still become part of your codebase due to a statement in your code such as an include, a types inclusion, clone_object, etc.

It is not a mechanism that prevents a file from being included in the codebase - it simply changes what the include setting finds.

Lib File Locations - libFiles

| Setting | Description | | ---------------- | ----------------------------------------------------------------------- | | master | The location of your master object. Defaults to "/obj/master.c" | | simul_efun | The location of your simul_efun file. Defaults to "/obj/simul_efun.c" | | global_include | When provided, will add this file as an #include to each file. | | player | The location of your player file. Defaults to "/obj/player.c" |

Lib Root Dir - rootDir

If your config file is located in a folder other than your lib's root directory, use this setting to specify the location of the root folder.

Include Search Dirs - libInclude

An array of folders that are searched when including files via the #include directive.

Defaults to ["/sys", "/obj", "/room"]

Predefined Macros - defines

Since your code is not being evaluated in the mud driver, you may need to simulate one or more defines that are normally provided by the driver's compiler. Values are an array of key value pairs. Example:

"defines": [
  { "__HOST_NAME__": "\"localhost\"" },
  { "TLS_PORT": "5555" }
]

In the example above, __HOST_NAME__ will be defined as the string value "localhost". TLS_PORT on the other hand, will be defined as an int value 5555.

Diagnostics - diagnostics

Semantic analysis is always run, but diagnostics are only reported if you opt in to receiving them. (Syntax errors will always be reported.) Example:

"diagnostics": "on"

Compiler Options - compilerOptions

Compiler options are specified under the compilerOptions object:

{
  "compilerOptions": {
    ...
  }
}

Strict Object Type Checking - strictObjectTypes

Defaults to false unless strict is on.

When enabled, strick object checking will report an error when an untyped object is being assigned to a typed object. For example:

/** 
 * @param {"std/player.c"} p
 */
void foo(object p) {
  tell_object(p, "hi");
}
void bar(object p)  {
  tell_object(p, "hi");
}

object player;
foo(p); /* p will report an error when strictObjectTypes is true, because it is an untyped object. */
bar(p); /* this call is ok because both objects are untyped */

Grammar ToDo's

Language services is a work in progress. Some major areas that have yet to be implemented are:

• LWObjects
• Named object validation
• Coroutines

Credits

Syntax highlighting is based on the LPC Language VS Code extension by Gwenn Reece, adjusted for LDMud.

The guts of this language server is a heavily modified version of the TypeScript compiler/server. None of it would be possible without the work of the many brilliant people working on that team.

Many thanks for the fellow MUD admins, wizards, and LPC aficionados in the LPC Discord for their inspiration.

Contact / Feature Requests / Bugs

Feedback welcome. You can open an issue in the lpc-language-server repo. Otherwise, you can usually find me on the LPC Discord or idling on Infinity Mud.