Quick Reference

This section provides a brief summary of the SML interface.

Library Structure

See the section Library Structure for a more detailed description.

Each namespace has a structure and a signature that specifies its contents.

structure Namespace : NAMESPACE

A namespace signature specifies named types, constants and functions.

signature NAMESPACE =
  sig
    (* named types *)
    structure Type1 : NAMESPACE_TYPE_1
    structure Type2 : NAMESPACE_TYPE_2(* constants *)
    val CONSTANT_1 : …
    val CONSTANT_2 : …
    …

    (* non-method functions *)
    val function1 : …
    val function2 : …
    …
  end

Therefore, for each named type Type in a namespace Namespace, there is a structure Namespace.Type whose contents are specified by the signature NAMESPACE_TYPE.

signature NAMESPACE_TYPE =
  sig
    (* local types *)
    type local_type_1_t  (* = Namespace.LocalType1.t *)
    type local_type_2_t  (* = Namespace.LocalType2.t *)
    …

    (* type *)
    …
    type t

    (* implemented interfaces - class and interface only *)
    val asIface1 : …
    val asIface2 : …
    …

    (* constants - class and interface only *)
    val CONSTANT_1 : …
    val CONSTANT_2 : …
    …

    (* method functions - class and interface only *)
    val method1 : …
    val method2 : …
    …

    (* non-method functions - any named type except callback *)
    val function1 : …
    val function2 : …
    …

    (* fields - class, record and union only *)
    val field1 : …
    val field2 : …
    …

    (* signals - class and interface only *)
    val signal1Sig : …
    val signal2Sig : …
    …

    (* properties - class and interface only *)
    val property1Prop : …
    val property2Prop : …
    …
  end

Types

Basic types

See the section Basic types for a more detailed description.

For each basic type, the following table shows the Giraffe Library type and equivalent Basis Library type:

Basic type

SML Giraffe Library type

SML Basis Library type

gboolean

GBoolean.t

bool

gchar

GChar.t

char

guchar

GUInt8.t

Word8.word

guint8

gshort

GShort.t

LargeInt.int

gushort

GUShort.t

gint

GInt.t

guint

GUInt.t

glong

GLong.t

gulong

GULong.t

gint8

GInt8.t

gint16

GInt16.t

guint16

GUInt16.t

gint32

GInt32.t

guint32

GUInt32.t

gint64

GInt64.t

guint64

GUInt64.t

gssize

GSSize.t

int

gsize

GSize.t

gfloat

GFloat.t

real

gdouble

GDouble.t

gint file descriptor

GFileDesc.t

Posix.ProcEnv.file_desc

UTF-8 and file name types

See the section UTF-8 and file name types for a more detailed description.

The SML type of UTF-8 text or a file name is Utf8.t. This type is not abstract but is equivalent to the Basis Library type string.

C array types

See the section C array types for a more detailed description.

The SML type of a C array whose element type has SML type Elem.t is as follows:

C array

size

zero terminated

separate parameter

elements

packed inline

ElemCArray.t

ElemCArrayN.t

referenced by a pointer

ElemCPtrArray.t

ElemCPtrArrayN.t

The SML types are abstract and an instance is always mutable.

If Elem is the structure for a named type Type in namespace Namespace, then Elem has the form NamespaceType. Furthermore, if the array whose elements are the named type Type is used in the namespace Namespace, as opposed to another namespace, then there equivalent types local to Namespace where Elem has the form Namespace.Type.

Named types

See the sections Enumeration types, Flags (bitfield) types, Class types, Interface types, Record types and Union types for a more detailed description.

For a named type Type in a namespace Namespace, the SML type is Namespace.Type.t. If Type is a class, this is equivalent to base Namespace.Type.class, which is the SML type for Type but not a subclass of Type. The SML type for Type or any subclass of Type is 'a Namespace.Type.class.

An instance of a enumeration or flags type is immutable. An instance of any other named type is mutable (although a library may treat instances of certain named types, e.g. a record, as immutable).

See the section Class encoding for details of how SML types encode a class hierarchy.

Implemented interfaces

See the section Implemented interfaces for a more detailed description.

For a class or interface Type in a namespace Namespace that implements an interface Iface in a namespace IfaceNamespace, the SML type Namespace.Type.t is not an instance of IfaceNamespace.Iface.t and explicit conversion to IfaceNamespace.Iface.t is required.

If Type is a class, conversion to Iface is provided by the function

Namespace.Type.asIface : 'a Namespace.Type.class -> IfaceNamespace.Iface.t

If Namespace.Type is an interface, conversion to Iface is provided by the function

Namespace.Type.asIface : Namespace.Type.t -> IfaceNamespace.Iface.t

Constants

See the section Constants for a more detailed description.

For a constant SOME_CONSTANT_NAME defined in a namespace Namespace, the SML interface provides

Namespace.SOME_CONSTANT_NAME : valueType

For a constant SOME_CONSTANT_NAME defined in a class or interface Type in a namespace Namespace, the SML interface provides

Namespace.Type.SOME_CONSTANT_NAME : valueType

Functions

See the section Functions for a more detailed description.

Non-method functions

For a function some_function_name defined in a namespace Namespace, the SML interface provides

Namespace.someFunctionName : inTypes -> retOutTypes

For a non-method function some_function_name defined in a named type Type in a namespace Namespace, the SML interface provides

Namespace.Type.someFunctionName : inTypes -> retOutTypes

inTypes contains the types of the ‘in’ and ‘inout’ arguments. retOutTypes contains the return type followed by the types of the ‘out’ and ‘inout’ arguments (except as described below). inTypes and retOutTypes use a tuple type if they contain more than one type.

When calling the SML function for a non-method:

  • the argument provides the values of the ‘in’ arguments and the before values of the ‘inout’ arguments;

  • the result provides the return value and the values of the ‘out’ arguments and the final values of the ‘inout’ arguments.

val (ret, y1, y2, …) = Namespace.Type.someFunctionName (x1, x2, …)

If the return type is void or the return type is gboolean and there is an error ‘out’ argument, retOutTypes does not include the return type.

val (y1, y2, …) = Namespace.Type.someFunctionName (x1, x2, …)

If inTypes contains fewer than two types, it cannot be a tuple type, in which case it is either just the single type or it is unit.

val … = Namespace.Type.someFunctionName x1
val … = Namespace.Type.someFunctionName ()

Similarly, if retOutTypes contains fewer than two types, it is either just the single type or it is unit.

val y1 = Namespace.Type.someFunctionName
val () = Namespace.Type.someFunctionName

If the return type is gboolean and there are ‘out’ arguments and none is an error ‘out’ argument, the ‘out’ arguments are treated as conditional on the return value. In this case, retOutTypes does not include the return type and groups the types for the ‘out’ arguments in an optional type whose value is not NONE if and only if the return value is not false.

let
  val (y1, y2, …, condOuts) = Namespace.Type.someFunctionName (x1, x2, …)
in
  case condOuts of
    SOME (z1, z2) => …
  | NONE => …
end

Method functions

For a method function some_function_name defined in a class Type in a namespace Namespace, the SML interface provides

Namespace.Type.someFunctionName : 'a Namespace.Type.class -> inTypes -> retOutTypes

For a method function some_function_name defined in an interface Type in a namespace Namespace, the SML interface provides

Namespace.Type.someFunctionName : Namespace.Type.t -> inTypes -> retOutTypes

When calling the SML function for a method, the first curried argument is the instance object. The result of applying the SML function to the instance object is a function that is called as described above for a non-method function.

Namespace.Type.someFunctionName obj : inTypes -> outTypes

If Namespace.Type is an interface, not a class, but obj is an instance of a class ClassNamespace.Class that implements the interface, obj must be explicitly converted, as described above in the section Implemented interfaces, to have an SML type that is an instance of the interface.

Namespace.Type.someFunctionName (ClassNamespace.Class.asType obj) : inTypes -> outTypes

Errors

If a function can raise an error, the corresponding SML function can raise the exception

GLib.Error (e : exn, error : GLib.Error.t)

let
  val (ret, y1, y2, …) = Namespace.Type.someFunctionName (x1, x2, …)
in
  …
end
  handle
    GLib.Error (_, error) => …

If a function can raise an error and the return type is gboolean, retOutTypes does not include the return type.

let
  val (y1, y2, …) = Namespace.Type.someFunctionName (x1, x2, …)
in
  …
end
  handle
    GLib.Error (_, error) => …

Fields

See the section Fields for a more detailed description.

For a readable field some_field_name of a record Record in a namespace Namespace, the SML interface provides

Namespace.Record.someFieldName : {get : Namespace.Record.t -> readType, ...}

and the value read from the field of a struct s : Namespace.Record.t is

#get Namespace.Record.someFieldName s : readType

For a writable field some_field_name of a record Record in a namespace Namespace, the SML interface provides

Namespace.Record.someFieldName : {set : writeType -> Namespace.Record.t -> unit, ...}

and the value x : writeType is written to the field of a struct s : Namespace.Record.t by

#set Namespace.Record.someFieldName x s : unit

Signals

See the section Signals for a more detailed description.

For a signal “some-signal-name” of a class Type in a namespace Namespace, the SML interface provides

Namespace.Type.someSignalNameSig : ('a Namespace.Type.class, argType_e, argType_h, resType_h, resType_e) Signal.t

For a signal “some-signal-name” of an interface Type in a namespace Namespace, the SML interface provides

Namespace.Type.someSignalNameSig : (Namespace.Type.t, argType_e, argType_h, resType_h, resType_e) Signal.t

Detail

The SML representation of a signal includes the detail string. The detail string is empty for signals in the SML interface: Signal.detail Namespace.Type.someSignalNameSig is "".

The signal with its detail string replaced by detail is

Signal.withDetail (Namespace.Type.someSignalNameSig, detail) : ... Signal.t

The signal with its detail string replaced by the name of a property prop : (propInstanceType, ...) Property.t is

Signal.withPropDetail (Namespace.Type.someSignalNameSig, prop) : (instanceType, ...) Signal.t

where instanceType matches with both the instance type of the signal and with propInstanceType.

Handlers

A handler function f : argType_h -> resType_h is connected to the signal on an object obj by

Signal.connect obj (Namespace.Type.someSignalNameSig, f) : Signal.handler_id

If Namespace.Type is an interface, not a class, but obj is an instance of a class ClassNamespace.Class that implements the interface, the SML types must be explicitly aligned as described above in the section Implemented interfaces. In this case, it is necessary to convert either

  • the SML type of obj by

    ClassNamespace.Class.asType obj
  • the SML type of Namespace.Type.someSignalNameSig by

    Signal.conv ClassNamespace.Class.asType Namespace.Type.someSignalNameSig

A signal handler on an object obj with id handlerId : Signal.handler_id is blocked by

Signal.handlerBlock obj handlerId

and is unblocked by

Signal.handlerUnblock obj handlerId

A signal handler on an object obj with id handlerId : Signal.handler_id is disconnected by

Signal.handlerDisconnect obj handlerId

Whether there is a signal handler on an object obj with id handlerId : Signal.handler_id is indicated by

Signal.handlerIsConnected obj handlerId

Emission

The signal is emitted on an object obj by the function

Signal.emit obj Namespace.Type.someSignalNameSig : argType_e -> resType_e

If Namespace.Type is an interface, not a class, but obj is an instance of a class ClassNamespace.Class that implements the interface, the SML types must be explicitly aligned as described above in the section Implemented interfaces. In this case, it is necessary to convert either

  • the SML type of obj by

    ClassNamespace.Class.asType obj
  • the SML type of Namespace.Type.someSignalNameSig by

    Signal.conv ClassNamespace.Class.asType Namespace.Type.someSignalNameSig

Properties

See the section Properties for a more detailed description.

For a property “some-property-name” of a class Type in a namespace Namespace, the SML interface provides

Namespace.Type.somePropertyNameProp : ('a Namespace.Type.class, getType, setType, initType) Property.t

For a property “some-property-name” of an interface Type in a namespace Namespace, the SML interface provides

Namespace.Type.somePropertyNameProp : (Namespace.Type.t, getType, setType, initType) Property.t

Accessors

If the property is readable, getType is unit -> readType and the value read from the property of an object obj is

Property.get Namespace.Type.somePropertyNameProp obj : readType

Otherwise, if the property is not readable, getType is unit and the above expression does not type check.

If the property is writable after construction, i.e. writable and not construct-only, setType is writeType -> unit and the value x : writeType is written to the property of an object obj by

Property.set Namespace.Type.somePropertyNameProp x obj : unit

Otherwise, if the property is not writable after construction, setType is unit and the above expression does not type check.

If Namespace.Type is an interface, not a class, but obj is an instance of a class ClassNamespace.Class that implements the interface, the SML types must be explicitly aligned as described above in the section Implemented interfaces. In this case, it is necessary to convert either

  • the SML type of obj by

    ClassNamespace.Class.asType obj
  • the SML type of Namespace.Type.somePropertyNameProp by

    Property.conv ClassNamespace.Class.asType Namespace.Type.somePropertyNameProp

Initialization on object construction

If the property is writable, initType is writeType -> unit and the value x : writeType is used to initialize the property on construction of an object of class C by

val obj = GObject.Object.new (CClass.t, […, Property.init Namespace.Type.somePropertyNameProp x, …])

Otherwise, if the property is not writable, initType is unit and the above expression does not type check.

If Namespace.Type is an interface, not a class, but C is equal to or a subclass of a class ClassNamespace.Class, the SML types must be explicitly aligned as described above in the section Implemented interfaces. In this case, it is necessary to convert the type of Namespace.Type.somePropertyNameProp by

Property.conv ClassNamespace.Class.asType Namespace.Type.somePropertyNameProp