ACGtk user documentation

Install

Installation Process

ACGtk depends on several OCaml libraries. Fortunately, the OCaml package manager opam makes the installation fast and easy.

The installation typically goes that way:

  1. First install opam using your preferred distribution/packaging mode.
  2. Then initialize the opam environment. opam environments can use the Ocaml compiler provided by your distribution, or locally install a compiler. They are called switches.

  3. Don't forget to add the required libraries in the path running

    $ eval `opam config env`

  4. ACGtk depends on several external libraries, i.e., libraries that are not OCaml libraries and need to be installed by your OS distribution. This can be done by opam as well running

    $ opam depext acgtk

  5. then continue with the ACG toolkit installation running

    $ opam install acgtk

This will install the binaries acgc and acg in the .opam/OCAML_VERSION/bin directory (where OCAML_VERSION is the OCaml version that you are using with opam. It can be system in case you are using the compiler installed by your OS distribution, or a version number (such as 4.05.0) otherwise).

It will also install:

To get the actual path of the share directory, just run

$ opam var share

For best results (correct rendering of symbols in the graphical output), please also install the free DejaVu fonts for your OS distribution.

ACG emacs mode

There is an ACG emacs mode acg.el in the emacs directory.

Its main feature is to be loaded when editing an acg data file (with signatures and lexicons). It is automatically loaded for files with a .acg extension

It basically contains compilation directives and next error searching.

  1. First load an acg file
  2. then run M-x compile (or C-c C-c) to call the compiler (acgc)
  3. then run M-x next error (or C-x) to search for the next error (if any) and highlight it.

Quick Way to Have It Work

Copy the following lines in your .emacs

(setq load-path (cons "EMACS_DIR_PATH" load-path))
(setq auto-mode-alist (cons '("\\.acg" . acg-mode) auto-mode-alist))
(autoload 'acg-mode "acg" "Major mode for editing ACG definitions" t)

where EMACS_DIR_PATH is .opam/OCAML_VERSION/share/acgtk/emacs.

Site Distribution

  1. Copy acg.el under an acg directory in your site-lisp directory (typically /usr/share/emacs/site-lisp/ or /usr/local/share/emacs/site-lisp/)

  2. Create a 50acg.el file into the /etc/emacs/site-start.d directory and copy the following lines in it:

    (setq load-path (cons "EMACS_DIR_PATH" load-path))
(setq auto-mode-alist (cons '("\\.acg" . acg-mode) auto-mode-alist))
(autoload 'acg-mode "acg" "Major mode for editing ACG definitions" t)

    where EMACS_DIR_PATH is the acg directory in your site-lisp directory (typically /usr/share/emacs/site-lisp/acg)

Dependencies

Installation of the required libraries is automatically performed by opam. But here is the list of the required libraries.

OCaml libraries

Optionally, in order to make some changes to the code, the following libraries are required as well:

Non Ocaml Libraries

These libraries should be installed automatically running

$ opam depext acgtk

They are:

  1. the development library for cairo
  2. the development library for freetype
  3. the development library for readline
  4. pkg-config

To know the required packages on your OS in order to install ACGtk, you can run:

$ opam list --rec --required-by acgtk --external

and look at the output corresponding to your system.

Quick Start

Example files both for acgc and acg are provided in the example directory.

acgc: Compiling Abstract Categorial Grammars

acgc is a "compiler" of ACG source code, i.e., files containing definitions of signatures and lexicons. It basically checks whether they are correctly written (syntactically and w.r.t. types and constant typing) and outputs an .acgo object file.

Run

$ acgc --help

to get help.

For instance, let's assume a file my_acg.acg. A basic usage of the acgc command could be:

$ acgc -o my_acg.acgo my_acg.acg

This will produce a my_acg.acgo file (note that this is the default name if the -o option is not provided).

acg: Using Abstract Categorial Grammars

acg is an interpreter of commands of the specific scripting language to use user-defined ACGs. Parameters of the interpreter are available running acg --help.

To get the list of available commands of the scripting language, run

$ acg

It will launch the interpreter in interactive mode. Then, on the prompt, type

ACGtk> help

Type CTRL-D to exit from the program.

Running a script

It is also possible to run scripts with acg. Run

$ acg script.acgs

to execute the script script.acgs in non-interactive mode.

Loading Data

Assuming the file my_acg.acgo was produced as explained above, running :

$ acg

will open a prompt in which you can type:

ACGtk> load "my_acg.acgo"

to load the data contained compiled from the my_acg.acg file into my_acg.acgo.

Alternatively, you could directly load the data file:

ACGtk> load "my_acg.acg"

Type-Checking Terms

Assuming you have defined the signature Sig and the lexicon Lex, you can then run the following commands:

ACGtk> "lambda x.some_cst x: NP ->S" | check signature=Sig

to check whether lambda x.some_cst x is a term of type NP ->S according to Sig.

Interpreting (or Realizing) Terms

Run:

ACGtk> "lambda x.some_cst x: NP ->S" | realize lexicon=Lex

to compute the image of lambda x.some_cst x by Lex (assuming this term and this type are correct according to the abstract signature of Lex).

Parsing Terms

Run:

ACGtk> "John+loves+Mary: string" | parse lexicon=Lex type=S

to check whether the term John+loves+Mary of type string has an antecedent of type S by Lex, assuming that string is the interpretation of the type S by Lex.

Manual

Syntax of Data Files

You can look at the examples/tag.acg file for an example).

An ACG data file is a sequence of signature or lexicon declarations, separated with a ;.

Signatures

signature my_sig_name=
	sig_entries
end

sig_entries is a list of sig_entry, separated with a ;. A sig_entry can be:

About Associativity and Precedence of Operators

Prefix operators have precedence over application, and application has precedence over infix operators. Relative precedence among infix operators can be defined.

When no associativity specification is set, the default is left associative.

When no precedence definition is given, the default is higher precedence over any infix operator defined so far.

When declaring or defining an infix operator with the keyword 'infix', the optional specification for the associativity and the relative precedence can be set.

A specification is given between square brackets. The syntax is as follows:

infix [specification] SYM …

(the remaining part of the declaration is the same as without the specification)

A specification is non-empty comma-separated list of:

It is possible to use an infix symbol as a normal constant by surrounding it with left and right parenthesis, so that t SYM u = (SYM) t u.

See examples/infix-examples.acg and examples/infix-examples-script for examples.

Lexicons

There are two ways to define a lexicon:

  1. By using the keyword lexicon or nl_lexicon as in :

    lexicon my_lex_name(abstract_sig_name) : object_sig_name =
	lex_entries
end

    or

    nl_lexicon my_lex_name(abstract_sig_name) : object_sig_name =
	lex_entries
end

    With the lexicon keyword, lambda (resp. ->) is interpreted as lambda (resp. ->), whereas with nl_lexicon, lambda (resp. ->) is interpreted as Lambda (resp. =>). I.e., everything is interpreted non-linearly. It is useful when not interested in linear constraints in the object signature (as, for instance, in the context-free lambda grammars).

    Lex_entries is a list of lex_entry, separated with a ;. A lex_entry can be of the following forms:

    • abstract_atomic_type1, abstract_atomic_type2 := object_type;
    • abstract_const1, abstract_const2 := object_term;

  2. By lexicon composition as in:

    lexicon my_new_lex = lex_2 << lex_1

Keywords

The keywords are signature, lexicon, nl_lexicon, end, type, prefix, infix, binder, lambda, λ⁰ (means the same thing as lambda), Lambda, and λ (means the same thing as Lambda).

The reserved symbols are =, <<, ;, :, ,, (, ), ., -> (and →), => (and ⇒), and :=.

Inside a signature or a lexicon, signature, lexicon and nl_lexicon are not considered as keywords and can be used as identifiers.

Other keywords can be used as identifiers when escaped with \ (e.g., \end).

Identifiers

Identifiers may use Unicode characters. They follow the following grammar:

IDENT := id_start id_continue* (subscripts|superscripts)* '*

where:

Symbols

Symbols (introduced with the keywords infix, prefix, or binder) may use Unicode characters as well. They follow the following grammar:

SYMBOL := symbols+ (subscripts|superscripts)* (_ | id_continue*)? (subscripts|superscripts)*

where symbols is a set of mathematical symbols:

acgc

Command Line

acgc [OPTION] … FILE …

acgc parses each file FILE, which is supposed to be a file containing ACG signatures or lexicons, either as source files (typically with the .acg extension) or object files (with the .acgo extension).

If all the files are successfully parsed, a binary containing all the ACG signatures and lexicons is created. By default, the name of the generated binary file is FILEn.acgo where FILEn.acg is the last parameter (see option -o).

Options

acg

Command Line

acg [OPTION] … [FILE] …

acg parses each file FILE (if any), which is supposed to be a file containing ACG commands, and interpret them. If no file is provided, of if option --interactive is set, it then interactively runs the ACG command interpreter.

A list of the available commands is available by running the help command in the interpreter.

Options

Scripting Language

The scripting language is described here.

Graphical Output

If a svg="realize.svg" option is provided when running a realize command during an acg session, a file realize.svg is generated in the current directory.

Such a file contains a representation as a tree of the operations described by the term to realize (applications, abstractions). Each node contains the abstract term and its realizations by each of the lexicons specified on the command line. The graphic file can for instance been observed through a web browser.

Four rendering engines are available so far to render the terms in each node:

The association between the name of a signature and a rendering engine is declared in a configuration file that can be loaded through the --realize option of acg and that looks like:

$ cat config.json
{
    "signatures": [
	{ "name": "TAG", "engine": "trees" },
	{ "name": "DSTAG", "engine": "trees" },
	{ "name": "CoTAG", "engine": "trees" },
	{ "name": "derivations", "engine": "trees" },
	{ "name": "strings", "engine" : "strings"},
	{ "name": "Strings", "engine" : "strings"},
	{ "name": "logic", "engine" : "logic"},
	{ "name": "low_logic", "engine" : "logic"},
	{ "name": "derived_trees", "engine" : "unranked trees"},
	{ "name": "Derived_trees", "engine" : "unranked trees"},
	{ "name": "trees", "engine" : "unranked trees"}
    ],
  "colors": {
      "node-background": (239, 239, 239),
      "background": (255,255,255)
  }
}

An example file is given in examples/config.json(examples/config.json)