The Mercury binding

clunkyard exposes the native API as deterministic IO predicates. Inputs come first, followed by the status and the IO state. Copy-out arguments use typed references: allocate with new_float_ref, call the core predicate, then use read_float_ref. check(Robot, Status, !IO) throws the core's error text for a negative status; cy_none means absent.

Native record types are opaque and owned by Mercury's collector. Allocate with new_contact or new_contact_array(Count, ...), then read fields with predicates such as contact_range. contact_at selects an element of an array. set_vec3 and the other record constructors accept every field in schema order. References and record views must stay within their allocated capacity. Buffers preserve explicit byte lengths, including embedded NUL: text_buffer copies a string, while new_buffer and buffer_set_byte construct arbitrary UTF-8 bytes. buffer_text copies a returned text value.

Install with make install SDK=/opt/clunkyard/sdk. Build in the source directory with mmc --make --mld /opt/clunkyard/sdk/bindings/mercury/lib/mercury --ml clunkyard --mercury-linkage static --c-include-directory /opt/clunkyard/sdk/include --ld-flags -Wl,--whole-archive,/opt/clunkyard/sdk/lib/libclunkyard.a,--no-whole-archive -l pthread -l dl -l m bot. The core and Mercury runtime link statically; the artifact carries the executable. The archive flags make core symbols available before Mercury's library is linked.

run(Turn, Start, !IO) owns the session and protocol loop. Callbacks receive the core handle and IO state. Exceptions are logged and the turn sends any controls already set; forfeit(Code, Message) makes an explicit forfeit. A core fault sends the empty reply and continues. play(Lines, Turn, Start, Replies, !IO) runs a memory session.

A tiny robot

:- module bot.
:- interface.
:- import_module io.
:- pred main(io::di, io::uo) is det.
:- implementation.
:- import_module clunkyard, int.
:- pred set(pred(robot, float, int, io, io)::in(pred(in, in, out, di, uo) is det), robot::in, float::in, io::di, io::uo) is det.
set(Control, R, Value, !IO) :- Control(R, Value, Status, !IO), check(R, Status, !IO).
:- pred status(robot::in, string::in, float::in, io::di, io::uo) is det.
status(R, Text, Value, !IO) :- text_buffer(Text, Bytes, Length, !IO), cy_status_text(R, Bytes, Length, S, !IO), check(R, S, !IO), set(cy_status_value, R, Value, !IO).
:- pred start(robot::in, io::di, io::uo) is det.
start(_, !IO).
:- pred turn(robot::in, io::di, io::uo) is det.
turn(R, !IO) :-
    new_contact(Target, !IO), cy_sensors_nearest(R, Target, Found, !IO),
    new_float_ref(Number, !IO), cy_me_heading(R, Number, HS, !IO), check(R, HS, !IO), read_float_ref(Number, Heading, !IO),
    (if Found = cy_ok then
        contact_range(Target, Range, !IO), contact_bearing(Target, Bearing, !IO), contact_elevation(Target, Elevation, !IO),
        cy_gun_power_for_flight_time(R, Range, 1.0, Number, PS, !IO), check(R, PS, !IO), read_float_ref(Number, Power, !IO),
        new_solution(Aim, !IO), cy_gun_lead(R, Target, Power, Aim, AS, !IO),
        (if AS = cy_ok then solution_heading(Aim, AH, !IO), solution_pitch(Aim, AP, !IO) else AH = Bearing, AP = Elevation),
        set(cy_gun_aim_heading, R, AH, !IO), set(cy_gun_aim_pitch, R, AP, !IO),
        new_int_ref(Fire, !IO), cy_gun_can_fire(R, Power, 10.0, Fire, FS, !IO), check(R, FS, !IO), read_int_ref(Fire, CanFire, !IO),
        (if CanFire \= 0 then cy_gun_fire(R, Fired, !IO), check(R, Fired, !IO), set(cy_gun_power, R, Power, !IO) else true),
        cy_angles_angle_diff(Bearing, Heading, Number, DS, !IO), check(R, DS, !IO), read_float_ref(Number, Delta, !IO),
        cy_angles_clamp(Delta, -1.0, 1.0, Number, CS, !IO), check(R, CS, !IO), read_float_ref(Number, Control, !IO),
        set(cy_drive_throttle, R, 0.5, !IO), set(cy_drive_turn, R, Control, !IO),
        set(cy_scanner_heading, R, Bearing, !IO), set(cy_scanner_arc, R, 10.0, !IO), status(R, "TRACK", Range, !IO)
    else
        set(cy_drive_throttle, R, 0.75, !IO), set(cy_drive_turn, R, 0.25, !IO),
        set(cy_scanner_heading, R, Heading, !IO), set(cy_scanner_arc, R, 40.0, !IO),
        new_scan(Last, !IO), cy_scanner_last(R, Last, LS, !IO), check(R, LS, !IO), scan_arc(Last, Arc, !IO), status(R, "SEARCH", Arc, !IO)
    ).
main(!IO) :- run(turn, start, !IO).

make test checks every generated Mercury predicate against the core's full vectors, including typed foreign arguments and records, exact floating-point results and serialized acts.

Names

Every entry of the robot API 2.0.0 in Mercury. names.md has every language side by side.

Download this page as Markdown