Skip to content

Latest commit

 

History

History
339 lines (223 loc) · 10.9 KB

MeTTaLog.md

File metadata and controls

339 lines (223 loc) · 10.9 KB

MeTTaLog: An Implementation of MeTTa in Prolog

MeTTaLog is a superfluous implementation of MeTTa, a language designed to succeed OpenCog Classic Atomese. As part of the OpenCog Hyperon initiative, MeTTa offers well-defined semantics for meta-language features, supports various types of inference, and more.

Latest Test Results

Installation Guide

MeTTaLog provides an environment for managing and interacting with Prolog-based logic systems. To set up MeTTaLog on your system, follow the steps below:

1. Clone the MeTTaLog Repository

Clone the repository using the following command:

git clone https://github.com/logicmoo/vspace-metta

Navigate to the cloned directory:

cd vspace-metta

2. Build and Install Required Packages

Run the installation script:

./INSTALL.sh

This script will install necessary Prolog packs, including predicate_streams, logicmoo_utils, and dictoo. During installation, you may encounter prompts for configuration choices. It's generally recommended to accept the default options.

3. Update the PATH

After installation, add the vspace-metta directory to your system's PATH to easily access the MeTTaLog executable:

echo 'export PATH="$PATH:$(pwd)"' >> ~/.profile
source ~/.profile

Note: This command updates the PATH for the current user. If you need system-wide access, consider adding the path to a system-wide profile file, such as /etc/profile.

Usage

Once installed, MeTTaLog can be accessed through the MeTTa script included in the repository, which serves as a front-end for the compiled Sav.$hostname.MeTTaLog executable. The name "MeTTa" is used in this context because the corresponding Rust executable is all lowercase metta.

Running

Within the REPL, you can interact directly with the MeTTaLog system. For instance:

MeTTaLog --repl

metta &self +> !(+ 1 1)
!(+ 1 1)

Deterministic: 2

; Execution took 0.000105 secs. (105.29 microseconds)
metta &self +>

To exit the REPL, press ctrl-D.

Running Tests

To run your first unit test (referred to as a LoonIt Test):

MeTTa --html examples/compat/scripts/00_lang_case.metta

Upon execution, the output will be saved as examples/compat/scripts/00_lang_case.metta.html.

Note: Remember, the MeTTa script's name is case-sensitive. Do not confuse it with metta, which might refer to a different tool written in Rust.

To run a metta file normally:

MeTTa examples/compat/scripts/b0_chaining_prelim.metta

To run the REPL (such as to debug) once the file is loaded:

MeTTa examples/compat/scripts/b0_chaining_prelim.metta --repl

To run the REPL:

MeTTa --repl

Familiarize Yourself with MeTTa`

  1. Read the MeTTa specification.
  2. Learn the Minimal instruction set

To run all tests:

./total_loonits.sh examples/compat/scripts/

To run a single test:

./MeTTa --html examples/compat/scripts/b0_chaining_prelim.metta

See --help for more options:

./MeTTa --help
 CMD: ./MeTTa
 Usage: MeTTa [options] <metta-files|directories> ... [-- arg ...passed to your program...]
        MeTTa [options] [-o executable] -c metta-file1 -c metta-file2 ... to compile into executable ...
        MeTTa --help         Display this message
        MeTTa --version      Display version information
        MeTTa --abi-version  Display ABI version key
        MeTTa --arch         Display architecture
        MeTTa --dump-runtime-variables[=format]
                        Dump link info in sh(1) format

    -x state                 Start from state (must be first)
    -g goal                  Run goal (may be repeated)
    -t toplevel              Toplevel goal
    -f file                  User initialisation file
    -F file                  Site initialisation file
    -l file                  Script source file
    -s file                  Script source file
    -p alias=path            Define file search path 'alias'
    -O                       Optimised compilation
    --on-error=style         One of print, halt or status
    --on-warning=style       One of print, halt or status
    --tty[=bool]             (Dis)allow tty control
    --packs[=bool]           Do (not) attach add-ons
    --signals[=bool]         Do (not) modify signal handling
    --threads[=bool]         Do (not) allow for threads
    --debug[=bool]           Do (not) generate debug info
    --debug-on-interrupt[=bool] Trap the debugger on interrupt
    --quiet[=bool] (-q)      Do (not) suppress informational messages
    --traditional            Disable extensions of version 7
    --home[=DIR]             Print home or use DIR as SWI-Prolog home
    --stack-limit=size[BKMG] Specify maximum size of Prolog stacks
    --table-space=size[BKMG] Specify maximum size of SLG tables
    --shared-table-space=size[BKMG] Maximum size of shared SLG tables
    --pce[=bool]             Make the xpce gui available
    --pldoc[=port]           Start PlDoc server [at port]
    --python[=bool]          Enable or disable Python support (default: enable)
    --repl                   Start the REPL (Read-Eval-Print Loop) after processing metta files.
                             If no metta files are provided, this is the default behavior.
    --timeout=seconds        Kill the script after so many seconds.
    --html[=bool]            Save an HTML file containing terminal output in the same
                             directory as the input file or directory.
                             Defaults to true if exactly one metta file or directory argument was provided




 Boolean options may be written as --name=bool, --name, --no-name or --noname.
 Both '-' or '_' are accepted as word-separator for long options.

 Configuration File:
    This script reads options from the ~/.mettalogrc file, one option per line.
    Options specified in ~/.mettalogrc are processed before command-line arguments.

Acknowledgments

Special thanks to the OpenCog community and everyone involved in the development and conceptualization of Hyperon and MeTTa.

MeTTa Execution Modes

These are inherited from SWI-Prolog

MeTTa can be executed in one of the following modes:

  • ./MeTTa [option ...] script-file [arg ...] Arguments after the script file are made available in the MeTTa flag argv.

  • ./MeTTa [option ...] metta-file ... [[--] arg ...] This is the normal way to start MeTTa. The MeTTa flag argv provides access to arg .... If the options are followed by one or more MeTTa file names (i.e., names with extension .metta), these files are loaded. The first file is registered in the MeTTa flag associated_file.

  • ./MeTTa -o output -c metta-file ... The -c option is used to compile a set of MeTTa files into an executable.

  • ./MeTTa -o output -b prolog-bootfile metta-file ... Bootstrap compilation.

Command Line Options for Running MeTTa

These are inherited from SWI-Prolog

Boolean options may be written as --name (true), --noname or --no-name (false).

  • --debug-on-interrupt Enable debugging on an interrupt signal immediately.

  • --home[=DIR] Use DIR as home directory.

  • --quiet Set the MeTTa flag verbose to silent, suppressing informational and banner messages. Also available as -q.

  • --no-debug Disable debugging.

  • --no-signals Inhibit any signal handling by MeTTa, a property that is sometimes desirable for embedded applications. This option sets the flag signals to false. Note that the handler to unblock system calls is still installed. This can be prevented using --sigalert=0 additionally.

  • --no-threads Disable threading for the multi-threaded version at runtime. See also the flags threads and gc_thread.

  • --no-packs Do not attach extension packages (add-ons).

  • --no-pce Enable/disable the xpce GUI subsystem. Using --pce loads the xpce system in user space and --no-pce makes it unavailable in the session.

  • --on-error=style How to handle errors.

  • --on-warning=style How to handle warnings.

  • --pldoc[=port] Start the PlDoc documentation system on a free network port. If port is specified, the server is started at the given port and the browser is not launched.

  • --sigalert=NUM Use signal NUM (1 ... 31) for alerting a thread. If NUM is 0 (zero), this handler is not installed.

  • --no-tty Unix only. Switches controlling the terminal.

  • -O Optimised compilation.

  • -l file.metta Load file.metta.

  • -s file.metta Use file.metta as a script file.

  • -f file.metta Use file.metta as initialisation file instead of the default init.metta.

  • -F script Select a startup script from the MeTTa home directory.

  • -x prolog-bootfile Boot from prolog-bootfile instead of the system''s default boot file.

  • -p alias=path1[:path2 ...] Define a path alias for file_search_path.

  • -- Stops scanning for more arguments.

Controlling the Stack Sizes

$ ./MeTTa --stack-limit=32g

  • --stack-limit=size[bkmg] Limit the combined size of the MeTTa stacks to the indicated size.

  • --table-space=size[bkmg] Limit for the table space.

  • --shared-table-space=size[bkmg] Limit for the table space for shared tables.

Running Goals from the Command Line

  • -g goal Goal is executed just before entering the top level.
% ./MeTTa <options> -g (go) -g (quit)
  • -t (goal) Use goal as an interactive top level instead of the default goal !(repl!).

Compilation Options

MeTTa Code is tranliterated to SWI-Prolog code and compiled

  • -c file.metta ... Compile files into an intermediate code file.

  • -o output Used in combination with -c to determine the output file for compilation.

Informational Command Line Options

  • --arch When given as the only option, it prints the architecture identifier (see MeTTa flag arch) and exits. See also --dump-runtime-variables.

  • --dump-runtime-variables [=format] When given as the only option, it prints a sequence of variable settings that can be used in shell scripts to deal with MeTTa parameters.

eval `./MeTTa --dump-runtime-variables`
cc -I$PLBASE/include -L$PLBASE/lib/$PLARCH ...

  • --help When given as the only option, it summarises the most important options.

  • --version When given as the only option, it summarises the version and the architecture identifier.

  • --abi-version Print a key (string) that represents the binary compatibility on a number of aspects.

Maintenance Options

These are inherited from SWI-Prolog

  • -b initfile.metta ...-c file.metta ... Boot compilation.

  • -d token1,token2,... Print debug messages for DEBUG statements.