Lobster Programming Language

Lobster uses an isolated multi-threading model where each thread runs an independent Lobster VM on a hardware core.

Key Characteristics:

• No Shared Memory: Threads do not share memory or VM state. This eliminates race conditions and the need for a Global Interpreter Lock (GIL).
• Communication via Tuple Spaces: Threads communicate by passing messages through a "tuple space" (a bag of Lobster objects). Messages are copied rather than shared.
• Concurrency Style: This model is optimized for "worker" style concurrency, where tasks are placed in a tuple space and available VMs grab and complete them, providing automatic load balancing.

For a practical implementation example, refer to samples/threads.lobster in the repository.

Before using Lobster, be aware of its design constraints:

• Not for beginners: Requires familiarity with concepts like higher-order functions and the rendering pipeline.
• Not for large-scale/team programming: The type system favors expressive power over building rigid interfaces for large teams.
• No built-in IDE or Editor: Everything is handled via code; there is no visual game editor.
• Not a mainstream/C-based language: It uses a terse syntax and functional semantics that differ significantly from C-style languages.

Lobster's syntax is a mix of Python and C conventions. Key lexical rules include:

• Whitespace: Uses spaces, tabs, carriage returns, and comments.
• Comments:
  • Single-line: //
  • Nested/Multi-line: /* ... */
• Strings:
  • Standard: Delimited by " (e.g., "hello").
  • Character constants: Delimited by ' (e.g., 'A').
  • Triple-quotes: """ allows verbatim content including newlines and quotes.
  • Escape codes: \n, \t, \r, \", \', \, and \x followed by 2 hex digits (e.g., \xFF).
• Numbers:
  • Integers: 123
  • Hexadecimal: 0xABADCAFE
  • Floating point: .1, 1., or 1.1
• Identifiers: Alphanumeric characters and _ (cannot start with a digit).
• Indentation: Uses indent and dedent tokens. Adjacent lines must start with the same sequence of spaces/tabs to ensure visual consistency.

Lobster uses a hybrid memory management strategy combining runtime reference counting with a compile-time ownership analysis algorithm. This is often referred to as "compile-time reference counting."

How it works:

• The algorithm automatically picks a single owner for each new heap allocation (usually the first variable or field it is assigned to).
• Subsequent uses of that value are treated as borrows.
• Ownership and borrows do not require runtime reference counting.
• Runtime reference counting is only inserted when a new owner is required (e.g., when a value is assigned to a new variable that needs to own it).
• This approach typically removes approximately 95% of runtime reference count operations.

Note: While the system is mostly automatic, the compiler may occasionally require minor code adjustments to satisfy ownership requirements.

To enable syntax highlighting for .lobster files in Notepad++:

1. Set your theme to a dark background (e.g., Zenburn) via Settings -> Style Configurator -> Select Theme.
2. Go to Language -> Define your language....
3. Click Import... and select the docs/notepad++/notepadpp_udl_lobster.xml file from the repository.
4. Use Save As... to name the language lobster.

Once configured, .lobster files will automatically use the correct highlighting, or you can select it manually from the Language menu.

To use SublimeText as an IDE for Lobster, follow these steps:

1. Copy the files from the docs/sublime directory in the Lobster repository to your SublimeText Packages/User folder.
   • Windows path example: \Users\YourUserName\AppData\Roaming\Sublime Text 3\Packages\User
2. Open lobster.sublime-build and verify that the path to your lobster executable is correct.
3. Note that the build system uses a custom version of the execution script called lobster_exec.py. This version suppresses window pop-ups, which means any graphical output from Lobster will be disabled.
4. Open a .lobster file and press Ctrl+B to run the program.

Lobster provides several ways to invoke functions:

1. Standard: name(1, 2)
2. Dot Notation: 1.name(2). If the function has only one argument, parentheses can be omitted: v.length.
3. No Parentheses: print "hi!". This is allowed for known functions with one expression argument used as a statement.

Note: When using dot notation, the first argument is placed ahead of the call.

To use HIDAPI in your own CMake-based project, use find_package(hidapi REQUIRED).

Basic Usage

project(my_application)

add_executable(my_application main.c)

find_package(hidapi REQUIRED)
target_link_libraries(my_application PRIVATE hidapi::hidapi)

Locating HIDAPI

If find_package fails to locate HIDAPI, specify the installation path using the hidapi_ROOT variable (requires CMake 3.12+):

cmake <your_project_source> -Dhidapi_ROOT=<path_to_hidapi_prefix>

For older CMake versions, use CMAKE_PREFIX_PATH instead.