diff options
| author | bringert <bringert@cs.chalmers.se> | 2005-12-06 16:23:29 +0000 |
|---|---|---|
| committer | bringert <bringert@cs.chalmers.se> | 2005-12-06 16:23:29 +0000 |
| commit | 41aaed58d4734b7cec5a4d2567283cb818f77cbb (patch) | |
| tree | 63f33adabdaa7751d653ccbf962ced80ead24d1f /doc | |
| parent | 1094204640cf1b12de751651c00b78f18d047429 (diff) | |
Moved transfer documentation to doc/. Added sections and text to transfer tutorial and reference. Added script for generating html from txt2tags files.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/darcs.html | 4 | ||||
| -rw-r--r-- | doc/transfer-reference.html | 484 | ||||
| -rw-r--r-- | doc/transfer-reference.txt | 413 | ||||
| -rw-r--r-- | doc/transfer-tutorial.html | 210 | ||||
| -rw-r--r-- | doc/transfer-tutorial.txt | 164 | ||||
| -rw-r--r-- | doc/transfer.html | 30 | ||||
| -rw-r--r-- | doc/transfer.txt | 24 | ||||
| -rw-r--r-- | doc/txt2html.sh | 13 |
8 files changed, 1340 insertions, 2 deletions
diff --git a/doc/darcs.html b/doc/darcs.html index b45dd38f3..7c74741e6 100644 --- a/doc/darcs.html +++ b/doc/darcs.html @@ -7,7 +7,7 @@ <P ALIGN="center"><CENTER><H1>GF Darcs repository</H1> <FONT SIZE="4"> <I>Author: Björn Bringert <bringert@cs.chalmers.se></I><BR> -Last update: Tue Dec 6 13:23:38 2005 +Last update: Tue Dec 6 14:29:33 2005 </FONT></CENTER> <P></P> @@ -492,5 +492,5 @@ For more info about what you can do with darcs, see <A HREF="http://darcs.net/ma </P> <!-- html code generated by txt2tags 2.0 (http://txt2tags.sf.net) --> -<!-- cmdline: txt2tags darcs.txt transfer-reference.txt transfer-tutorial.txt transfer.txt --> +<!-- cmdline: txt2tags darcs.txt --> </BODY></HTML> diff --git a/doc/transfer-reference.html b/doc/transfer-reference.html new file mode 100644 index 000000000..d96269db5 --- /dev/null +++ b/doc/transfer-reference.html @@ -0,0 +1,484 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> +<META NAME="generator" CONTENT="http://txt2tags.sf.net"> +<TITLE>Transfer language reference</TITLE> +</HEAD><BODY BGCOLOR="white" TEXT="black"> +<P ALIGN="center"><CENTER><H1>Transfer language reference</H1> +<FONT SIZE="4"> +<I>Author: Björn Bringert <bringert@cs.chalmers.se></I><BR> +Last update: Tue Dec 6 14:26:07 2005 +</FONT></CENTER> + +<P></P> +<HR NOSHADE SIZE=1> +<P></P> + <UL> + <LI><A HREF="#toc1">Layout syntax</A> + <LI><A HREF="#toc2">Imports</A> + <LI><A HREF="#toc3">Function declarations</A> + <LI><A HREF="#toc4">Data type declarations</A> + <LI><A HREF="#toc5">Lambda expressions</A> + <LI><A HREF="#toc6">Local definitions</A> + <LI><A HREF="#toc7">Types</A> + <UL> + <LI><A HREF="#function_types">Function types</A> + <LI><A HREF="#toc9">Basic types</A> + <LI><A HREF="#toc10">Records</A> + <LI><A HREF="#toc11">Tuples</A> + <LI><A HREF="#toc12">Lists</A> + </UL> + <LI><A HREF="#toc13">Pattern matching</A> + <UL> + <LI><A HREF="#toc14">Constructor patterns</A> + <LI><A HREF="#toc15">Variable patterns</A> + <LI><A HREF="#toc16">Wildcard patterns</A> + <LI><A HREF="#toc17">Record patterns</A> + <LI><A HREF="#toc18">Disjunctive patterns</A> + <LI><A HREF="#toc19">List patterns</A> + <LI><A HREF="#toc20">Tuple patterns</A> + <LI><A HREF="#toc21">String literal patterns</A> + <LI><A HREF="#toc22">Integer literal patterns</A> + </UL> + <LI><A HREF="#toc23">Meta variables</A> + <LI><A HREF="#toc24">Type classes</A> + <LI><A HREF="#toc25">Operators</A> + <LI><A HREF="#toc26">Compositional functions</A> + <LI><A HREF="#toc27">do notation</A> + </UL> + +<P></P> +<HR NOSHADE SIZE=1> +<P></P> +<P> +This document describes the features of the Transfer language. +See the <A HREF="transfer-tutorial.html">Transfer tutorial</A> +for an example of a Transfer program, and how to compile and use +Transfer programs. +</P> +<P> +Transfer is a dependently typed functional programming language +with eager evaluation. +</P> +<A NAME="toc1"></A> +<H2>Layout syntax</H2> +<P> +Transfer uses layout syntax, where the indentation of a piece of code +determines which syntactic block it belongs to. +</P> +<P> +To give the block structure of a piece of code without using layout +syntax, you can enclose the block in curly braces (<CODE>{ }</CODE>) and +separate the parts of the blocks with semicolons (<CODE>;</CODE>). +</P> +<P> +For example, this case expression: +</P> +<PRE> + case x of + p1 -> e1 + p2 -> e2 +</PRE> +<P></P> +<P> +is equivalent to this one: +</P> +<PRE> + case x of { + p1 -> e1 ; + p2 -> e2 + } +</PRE> +<P></P> +<P> +Here the layout is insignificant, as the structure is given with +braces and semicolons. Thus the above is equivalent to: +</P> +<PRE> + case x of { p1 -> e1 ; p2 -> e2 } +</PRE> +<P></P> +<A NAME="toc2"></A> +<H2>Imports</H2> +<P> +A Transfer module start with some imports. Most modules will have to +import the prelude, which contains definitons used by most programs: +</P> +<PRE> + import prelude +</PRE> +<P></P> +<A NAME="toc3"></A> +<H2>Function declarations</H2> +<P> +Functions need to be given a type and a definition. The type is given +by a typing judgement on the form: +</P> +<PRE> + f : T +</PRE> +<P></P> +<P> +where <CODE>f</CODE> is the function's name, and <CODE>T</CODE> its type. See +<A HREF="#function_types">Function types</A> for a how the types of functions +are written. +</P> +<P> +The definition of the function is the given as a sequence of pattern +equations. The first equation whose patterns match the function arguments +is used when the function is called. Pattern equations are on the form: +</P> +<PRE> + f p1 ... p1n = exp + ... + f qn1 ... qnm = exp +</PRE> +<P></P> +<A NAME="toc4"></A> +<H2>Data type declarations</H2> +<P> +Transfer supports Generalized Algebraic Datatypes. +They are declared thusly: +</P> +<PRE> + data D : T where + c1 : Tc1 + ... + cn : Tcn +</PRE> +<P></P> +<P> +Here <CODE>D</CODE> is the name of the data type, <CODE>T</CODE> is the type of the type +constructor, <CODE>c1</CODE> to <CODE>cn</CODE> are the data constructor names, and +<CODE>Tc1</CODE> to <CODE>Tcn</CODE> are their types. +</P> +<A NAME="toc5"></A> +<H2>Lambda expressions</H2> +<P> +<I>Lambda expressions</I> are terms which express functions, without +giving names to them. For example: +</P> +<PRE> + \x -> x + 1 +</PRE> +<P></P> +<P> +is the function which takes an argument, and returns the value of the +argument + 1. +</P> +<A NAME="toc6"></A> +<H2>Local definitions</H2> +<P> +To give local definition to some names, use: +</P> +<PRE> + let x1 : T1 = exp1 + ... + xn : Tn = expn + in exp +</PRE> +<P></P> +<A NAME="toc7"></A> +<H2>Types</H2> +<A NAME="function_types"></A> +<H3>Function types</H3> +<P> +Functions types are of the form: +</P> +<PRE> + A -> B +</PRE> +<P></P> +<P> +This is the type of functions which take an argument of type +<CODE>A</CODE> and returns a result of type <CODE>B</CODE>. +</P> +<P> +To write functions which take more than one argument, we use <I>currying</I>. +A function which takes n arguments is a function which takes 1 +argument and returns a function which takes n-1 arguments. Thus, +</P> +<PRE> + A -> (B -> C) +</PRE> +<P></P> +<P> +or, equivalently, since <CODE>-></CODE> associates to the right: +</P> +<PRE> + A -> B -> C +</PRE> +<P></P> +<P> +is the type of functions which take 2 arguments, the first of type +<CODE>A</CODE> and the second of type <CODE>B</CODE>. This arrangement lets us do +<I>partial application</I> of function to fewer arguments than the function +is declared to take, returning a new function which takes the rest +of the arguments. +</P> +<H4>Dependent function types</H4> +<P> +In a function type, the value of an argument can be used later +in the type. Such dependent function types are written: +</P> +<PRE> + (x1 : T1) -> ... -> (xn : Tn) -> T +</PRE> +<P></P> +<P> +Here, <CODE>x1</CODE> can be used in <CODE>T2</CODE> to <CODE>Tn</CODE>, <CODE>x1</CODE> can be used +in <CODE>T2</CODE> to <CODE>Tn</CODE> +</P> +<A NAME="toc9"></A> +<H3>Basic types</H3> +<H4>Integers</H4> +<P> +The type of integers is called <CODE>Integer</CODE>. +standard decmial integer literals are used to represent values of this type. +</P> +<H4>Floating-point numbers</H4> +<P> +The only currently supported floating-point type is <CODE>Double</CODE>, which supports +IEEE-754 double-precision floating-point numbers. Double literals are written +in decimal notation, e.g. <CODE>123.456</CODE>. +</P> +<H4>Strings</H4> +<P> +There is a primitive <CODE>String</CODE> type. This might be replaced by a list of +characters representation in the future. String literals are written +with double quotes, e.g. <CODE>"this is a string"</CODE>. +</P> +<H4>Booleans</H4> +<P> +Booleans are not a built-in type, though some features of the Transfer language +depend on them. +</P> +<PRE> + data Bool : Type where + True : Bool + False : Bool +</PRE> +<P></P> +<P> +In addition to normal pattern matching on booleans, you can use the built-in +if-expression: +</P> +<PRE> + if exp1 then exp2 else exp3 +</PRE> +<P></P> +<P> +where <CODE>exp1</CODE> must be an expression of type <CODE>Bool</CODE>. +</P> +<A NAME="toc10"></A> +<H3>Records</H3> +<P> +Record types are created by using a <CODE>sig</CODE> expression: +</P> +<PRE> + sig { p1 : T1; ... ; pn : Tn } +</PRE> +<P></P> +<P> +Here, <CODE>p1</CODE> to <CODE>pn</CODE> are the field labels and <CODE>T1</CODE> to <CODE>Tn</CODE> are their types. +</P> +<P> +Record values are constructed using <CODE>rec</CODE> expressions: +</P> +<PRE> + rec { p1 = exp1; ... ; pn = expn } +</PRE> +<P></P> +<P> +The curly braces and semicolons are simply explicit layout syntax, so +the record type and record expression above can also be written as: +</P> +<PRE> + sig p1 : T1 + pn : Tn +</PRE> +<P></P> +<PRE> + rec p1 = exp1 + pn = expn +</PRE> +<P></P> +<H4>Record subtyping</H4> +<P> +A record of some type R1 can be used as a record of any type R2 +such that for every field <CODE>p1 : T1</CODE> in R2, <CODE>p1 : T1</CODE> is also a +field of T1. +</P> +<A NAME="toc11"></A> +<H3>Tuples</H3> +<P> +Tuples on the form: +</P> +<PRE> + (exp1, ..., expn) +</PRE> +<P></P> +<P> +are syntactic sugar for records with fields <CODE>p1</CODE> to <CODE>pn</CODE>. The expression +above is equivalent to: +</P> +<PRE> + rec { p1 = exp1; ... ; pn = expn } +</PRE> +<P></P> +<A NAME="toc12"></A> +<H3>Lists</H3> +<P> +The <CODE>List</CODE> type is not built-in, though there is some special syntax for it. +The list type is declared as: +</P> +<PRE> + data List : Type -> Type where + Nil : (A:Type) -> List A + Cons : (A:Type) -> A -> List A -> List A +</PRE> +<P></P> +<P> +The empty lists can be written as <CODE>[]</CODE>. There is a operator <CODE>::</CODE> which can +be used instead of <CODE>Cons</CODE>. These are just syntactic sugar for expressions +using <CODE>Nil</CODE> and <CODE>Cons</CODE>, with the type arguments hidden. +</P> +<A NAME="toc13"></A> +<H2>Pattern matching</H2> +<P> +Pattern matching is done in pattern equations and by using the +<CODE>case</CODE> construct: +</P> +<PRE> + case exp of + p1 | guard1 -> rhs1 + ... + pn | guardn -> rhsn +</PRE> +<P></P> +<P> +<CODE>guard1</CODE> to <CODE>guardn</CODE> are boolean expressions. Case arms can also be written +without guards, such as: +</P> +<PRE> + pk -> rhsk +</PRE> +<P></P> +<P> +This is the same as writing: +</P> +<PRE> + pk | True -> rhsk +</PRE> +<P></P> +<P> +The syntax of patterns are decribed below. +</P> +<A NAME="toc14"></A> +<H3>Constructor patterns</H3> +<P> +Constructor patterns are written as: +</P> +<PRE> + C p1 ... pn +</PRE> +<P></P> +<P> +where <CODE>C</CODE> is a data constructor which takes <CODE>n</CODE> arguments. +If the value to be matched is the constructor <CODE>C</CODE> applied to +arguments <CODE>v1</CODE> to <CODE>vn</CODE>, then <CODE>v1</CODE> to <CODE>vn</CODE> will be matched +against <CODE>p1</CODE> to <CODE>pn</CODE>. +</P> +<A NAME="toc15"></A> +<H3>Variable patterns</H3> +<P> +A variable pattern is a single identifier: +</P> +<PRE> + x +</PRE> +<P></P> +<P> +A variable pattern matches any value, and binds the variable name to the +value. A variable may not occur more than once in a pattern. +</P> +<A NAME="toc16"></A> +<H3>Wildcard patterns</H3> +<P> +Wildcard patterns are written as with a single underscore: +</P> +<PRE> + _ +</PRE> +<P></P> +<P> +Wildcard patterns match all values and bind no variables. +</P> +<A NAME="toc17"></A> +<H3>Record patterns</H3> +<P> +Record patterns match record values: +</P> +<PRE> + rec { l1 = p1; ... ; ln = pn } +</PRE> +<P></P> +<P> +A record value matches a record pattern, if the record value has all the +fields <CODE>l1</CODE> to <CODE>ln</CODE>, and their values match <CODE>p1</CODE> to <CODE>pn</CODE>. +</P> +<P> +Note that a record value may have more fields than the record pattern and +they will still match. +</P> +<A NAME="toc18"></A> +<H3>Disjunctive patterns</H3> +<P> +It is possible to write a pattern on the form: +</P> +<PRE> + p1 || ... || pn +</PRE> +<P></P> +<P> +A value will match this pattern if it matches any of the patterns <CODE>p1</CODE> to <CODE>pn</CODE>. +FIXME: talk about how this is expanded +</P> +<A NAME="toc19"></A> +<H3>List patterns</H3> +<A NAME="toc20"></A> +<H3>Tuple patterns</H3> +<P> +Tuples patterns on the form: +</P> +<PRE> + (p1, ... , pn) +</PRE> +<P></P> +<P> +are syntactic sugar for record patterns, in the same way as tuple expressions. +</P> +<A NAME="toc21"></A> +<H3>String literal patterns</H3> +<P> +String literals can be used as patterns. +</P> +<A NAME="toc22"></A> +<H3>Integer literal patterns</H3> +<P> +Integer literals can be used as patterns. +</P> +<A NAME="toc23"></A> +<H2>Meta variables</H2> +<A NAME="toc24"></A> +<H2>Type classes</H2> +<A NAME="toc25"></A> +<H2>Operators</H2> +<A NAME="toc26"></A> +<H2>Compositional functions</H2> +<A NAME="toc27"></A> +<H2>do notation</H2> + +<!-- html code generated by txt2tags 2.0 (http://txt2tags.sf.net) --> +<!-- cmdline: txt2tags darcs.txt transfer-reference.txt transfer-tutorial.txt transfer.txt --> +</BODY></HTML> diff --git a/doc/transfer-reference.txt b/doc/transfer-reference.txt new file mode 100644 index 000000000..dd16e2d39 --- /dev/null +++ b/doc/transfer-reference.txt @@ -0,0 +1,413 @@ +Transfer language reference +Author: Björn Bringert <bringert@cs.chalmers.se> +Last update: %%date(%c) + + +% NOTE: this is a txt2tags file. +% Create an html file from this file using: +% txt2tags transfer.txt + +%!target:html +%!options(html): --toc + + + + + + +This document describes the features of the Transfer language. +See the [Transfer tutorial transfer-tutorial.html] +for an example of a Transfer program, and how to compile and use +Transfer programs. + +Transfer is a dependently typed functional programming language +with eager evaluation. + +== Layout syntax== + +Transfer uses layout syntax, where the indentation of a piece of code +determines which syntactic block it belongs to. + +To give the block structure of a piece of code without using layout +syntax, you can enclose the block in curly braces (``{ }``) and +separate the parts of the blocks with semicolons (``;``). + +For example, this case expression: + +``` +case x of + p1 -> e1 + p2 -> e2 +``` + +is equivalent to this one: + +``` +case x of { + p1 -> e1 ; + p2 -> e2 +} +``` + +Here the layout is insignificant, as the structure is given with +braces and semicolons. Thus the above is equivalent to: + +``` +case x of { p1 -> e1 ; p2 -> e2 } +``` + +== Imports == + +A Transfer module start with some imports. Most modules will have to +import the prelude, which contains definitons used by most programs: + +``` +import prelude +``` + + +== Function declarations == + +Functions need to be given a type and a definition. The type is given +by a typing judgement on the form: + +``` +f : T +``` + +where ``f`` is the function's name, and ``T`` its type. See +[Function types #function_types] for a how the types of functions +are written. + +The definition of the function is the given as a sequence of pattern +equations. The first equation whose patterns match the function arguments +is used when the function is called. Pattern equations are on the form: + +``` +f p1 ... p1n = exp +... +f qn1 ... qnm = exp +``` + + +== Data type declarations == + +Transfer supports Generalized Algebraic Datatypes. +They are declared thusly: + +``` +data D : T where + c1 : Tc1 + ... + cn : Tcn +``` + +Here ``D`` is the name of the data type, ``T`` is the type of the type +constructor, ``c1`` to ``cn`` are the data constructor names, and +``Tc1`` to ``Tcn`` are their types. + + +== Lambda expressions == + +//Lambda expressions// are terms which express functions, without +giving names to them. For example: + +``` +\x -> x + 1 +``` + +is the function which takes an argument, and returns the value of the +argument + 1. + + +== Local definitions == + +To give local definition to some names, use: + +``` +let x1 : T1 = exp1 + ... + xn : Tn = expn + in exp +``` + + + +== Types == + +=== Function types ===[function_types] + +Functions types are of the form: + +``` +A -> B +``` + +This is the type of functions which take an argument of type +``A`` and returns a result of type ``B``. + +To write functions which take more than one argument, we use //currying//. +A function which takes n arguments is a function which takes 1 +argument and returns a function which takes n-1 arguments. Thus, + +``` +A -> (B -> C) +``` + +or, equivalently, since ``->`` associates to the right: + +``` +A -> B -> C +``` + +is the type of functions which take 2 arguments, the first of type +``A`` and the second of type ``B``. This arrangement lets us do +//partial application// of function to fewer arguments than the function +is declared to take, returning a new function which takes the rest +of the arguments. + + +==== Dependent function types ==== + +In a function type, the value of an argument can be used later +in the type. Such dependent function types are written: + +``` +(x1 : T1) -> ... -> (xn : Tn) -> T +``` + +Here, ``x1`` can be used in ``T2`` to ``Tn``, ``x1`` can be used +in ``T2`` to ``Tn`` + +=== Basic types === + +==== Integers ==== + +The type of integers is called ``Integer``. +standard decmial integer literals are used to represent values of this type. + +==== Floating-point numbers ==== + +The only currently supported floating-point type is ``Double``, which supports +IEEE-754 double-precision floating-point numbers. Double literals are written +in decimal notation, e.g. ``123.456``. + +==== Strings ==== + +There is a primitive ``String`` type. This might be replaced by a list of +characters representation in the future. String literals are written +with double quotes, e.g. ``"this is a string"``. + + +==== Booleans ==== + +Booleans are not a built-in type, though some features of the Transfer language +depend on them. + +``` +data Bool : Type where + True : Bool + False : Bool +``` + +In addition to normal pattern matching on booleans, you can use the built-in +if-expression: + +``` +if exp1 then exp2 else exp3 +``` + +where ``exp1`` must be an expression of type ``Bool``. + + + +=== Records === + +Record types are created by using a ``sig`` expression: + +``` +sig { p1 : T1; ... ; pn : Tn } +``` + +Here, ``p1`` to ``pn`` are the field labels and ``T1`` to ``Tn`` are their types. + +Record values are constructed using ``rec`` expressions: + +``` +rec { p1 = exp1; ... ; pn = expn } +``` + +The curly braces and semicolons are simply explicit layout syntax, so +the record type and record expression above can also be written as: + +``` +sig p1 : T1 + pn : Tn +``` + +``` +rec p1 = exp1 + pn = expn +``` + +==== Record subtyping ==== + +A record of some type R1 can be used as a record of any type R2 +such that for every field ``p1 : T1`` in R2, ``p1 : T1`` is also a +field of T1. + +=== Tuples === + +Tuples on the form: + +``` +(exp1, ..., expn) +``` + +are syntactic sugar for records with fields ``p1`` to ``pn``. The expression +above is equivalent to: + +``` +rec { p1 = exp1; ... ; pn = expn } +``` + + +=== Lists === + +The ``List`` type is not built-in, though there is some special syntax for it. +The list type is declared as: + +``` +data List : Type -> Type where + Nil : (A:Type) -> List A + Cons : (A:Type) -> A -> List A -> List A +``` + +The empty lists can be written as ``[]``. There is a operator ``::`` which can +be used instead of ``Cons``. These are just syntactic sugar for expressions +using ``Nil`` and ``Cons``, with the type arguments hidden. + + +== Pattern matching == + +Pattern matching is done in pattern equations and by using the +``case`` construct: + +``` +case exp of + p1 | guard1 -> rhs1 + ... + pn | guardn -> rhsn +``` + +``guard1`` to ``guardn`` are boolean expressions. Case arms can also be written +without guards, such as: + +``` + pk -> rhsk +``` + +This is the same as writing: + +``` + pk | True -> rhsk +``` + +The syntax of patterns are decribed below. + +=== Constructor patterns === + +Constructor patterns are written as: + +``` +C p1 ... pn +``` + +where ``C`` is a data constructor which takes ``n`` arguments. +If the value to be matched is the constructor ``C`` applied to +arguments ``v1`` to ``vn``, then ``v1`` to ``vn`` will be matched +against ``p1`` to ``pn``. + + +=== Variable patterns === + +A variable pattern is a single identifier: + +``` +x +``` + +A variable pattern matches any value, and binds the variable name to the +value. A variable may not occur more than once in a pattern. + + +=== Wildcard patterns === + +Wildcard patterns are written as with a single underscore: + +``` +_ +``` + +Wildcard patterns match all values and bind no variables. + + +=== Record patterns === + +Record patterns match record values: + +``` +rec { l1 = p1; ... ; ln = pn } +``` + +A record value matches a record pattern, if the record value has all the +fields ``l1`` to ``ln``, and their values match ``p1`` to ``pn``. + +Note that a record value may have more fields than the record pattern and +they will still match. + + +=== Disjunctive patterns === + +It is possible to write a pattern on the form: + +``` +p1 || ... || pn +``` + +A value will match this pattern if it matches any of the patterns ``p1`` to ``pn``. +FIXME: talk about how this is expanded + + +=== List patterns === + +=== Tuple patterns === + +Tuples patterns on the form: + +``` +(p1, ... , pn) +``` + +are syntactic sugar for record patterns, in the same way as tuple expressions. + +=== String literal patterns === + +String literals can be used as patterns. + + +=== Integer literal patterns === + +Integer literals can be used as patterns. + + +== Meta variables == + +== Type classes == + +== Operators == + +== Compositional functions == + +== do notation == + diff --git a/doc/transfer-tutorial.html b/doc/transfer-tutorial.html new file mode 100644 index 000000000..7ca1c2060 --- /dev/null +++ b/doc/transfer-tutorial.html @@ -0,0 +1,210 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> +<META NAME="generator" CONTENT="http://txt2tags.sf.net"> +<TITLE>Transfer tutorial</TITLE> +</HEAD><BODY BGCOLOR="white" TEXT="black"> +<P ALIGN="center"><CENTER><H1>Transfer tutorial</H1> +<FONT SIZE="4"> +<I>Author: Björn Bringert <bringert@cs.chalmers.se></I><BR> +Last update: Tue Dec 6 14:26:07 2005 +</FONT></CENTER> + +<P></P> +<HR NOSHADE SIZE=1> +<P></P> + <UL> + <LI><A HREF="#toc1">Objective</A> + <LI><A HREF="#toc2">Abstract syntax</A> + <LI><A HREF="#toc3">Concrete syntax</A> + <LI><A HREF="#toc4">Generate tree module</A> + <LI><A HREF="#toc5">Write transfer code</A> + <LI><A HREF="#toc6">Compiling Transfer programs</A> + <LI><A HREF="#toc7">Using Transfer programs in GF</A> + <UL> + <LI><A HREF="#toc8">Loading the grammars</A> + <LI><A HREF="#toc9">Loading the Transfer program</A> + <LI><A HREF="#toc10">Calling Transfer functions</A> + <UL> + <LI><A HREF="#toc11">Transfer between different abstract syntaxes</A> + </UL> + </UL> + </UL> + +<P></P> +<HR NOSHADE SIZE=1> +<P></P> +<A NAME="toc1"></A> +<H1>Objective</H1> +<P> +We want to write a Transfer program which we can use to do aggregation +in sentences which use conjugations on the sentence, noun phrase and +verb phrase levels. For example, we want to be able to transform +the sentence "John walks and Mary walks" to the sentence +"John and Mary walk". We would also like to transform +"John walks and John swims" to "John walks and swims". +</P> +<P> +Thus that what we want to do is: +</P> +<UL> +<LI>Transform sentence conjugation where the verb phrases in the sentences + are identical to noun phrase conjugation. +<LI>Transform sentence conjugation where the noun phrases in the sentences + are identical to verb phrase conjugation. +</UL> + +<P> +This needs to be done recursively and thoughout the sentence, to be +able to handle cases like "John walks and Mary walks and Bill walks", and +"John runs and Mary walks and Bill walks". +</P> +<P> +FIXME: what about John walks and Mary runs and Bill walks"? +</P> +<A NAME="toc2"></A> +<H1>Abstract syntax</H1> +<P> +We will use the abstract syntax defined in +<A HREF="../transfer/examples/aggregation/Abstract.gf">Abstract.gf</A>. +</P> +<A NAME="toc3"></A> +<H1>Concrete syntax</H1> +<P> +There is an English concrete syntax for this grammar in +<A HREF="../transfer/examples/aggregation/English.gf">English.gf</A>. +</P> +<A NAME="toc4"></A> +<H1>Generate tree module</H1> +<P> +To be able to write Transfer programs which sue the types defined in +an abstract syntax, we first need to generate a Transfer file with +a data type defintition corresponding to the abstract syntax. +This is done with the <CODE>transfer</CODE> grammar printer: +</P> +<PRE> + $ gf + > i English.gf + > pg -printer=transfer | wf tree.tr +</PRE> +<P></P> +<P> +Note that you need to load a concrete syntax which uses the abstract +syntax that you want to create a Transfer data type for. Loading just the +abstract syntax module is not enough. FIXME: why? +</P> +<P> +The command sequence above writes a Transfer data type definition to the +file <CODE>tree.tr</CODE>. +</P> +<A NAME="toc5"></A> +<H1>Write transfer code</H1> +<P> +We write the Transfer program +<A HREF="../transfer/examples/aggregation/aggregate.tr">aggregate.tr</A>. +</P> +<P> +FIXME: explain the code +</P> +<A NAME="toc6"></A> +<H1>Compiling Transfer programs</H1> +<P> +Transfer programs are written in the human-friendly Transfer language, +but GF only understands the simpler Transfer Core language. Therefore, +before using a Transfer program, you must first compile it to +Transfer Core. This is done using the <CODE>transferc</CODE> command: +</P> +<PRE> + $ transferc -i<lib> <transfer program> +</PRE> +<P></P> +<P> +Here, <CODE><lib></CODE> is the path to search for any modules which you import +in your Transfer program. You can give several <CODE>-i</CODE> flags. +</P> +<P> +So, to compile <CODE>aggregate.tr</CODE> which we created above, we use: +</P> +<PRE> + $ transferc aggregate.tr +</PRE> +<P></P> +<P> +The creates the Transfer Core file <CODE>aggregate.trc</CODE>. +</P> +<A NAME="toc7"></A> +<H1>Using Transfer programs in GF</H1> +<A NAME="toc8"></A> +<H2>Loading the grammars</H2> +<P> +To use a Transfer Core program to transform abstract syntax terms +in GF, you must first load the grammars which you want to use the +program with. For the example above, we need the grammar <CODE>English.gf</CODE> +and its dependencies. We load this grammar with: +</P> +<PRE> + > i English.gf +</PRE> +<P></P> +<A NAME="toc9"></A> +<H2>Loading the Transfer program</H2> +<P> +There are two steps to using a Transfer Core program in GF. First you load +the program into GF. This is done with the <CODE>i</CODE> command, which is also +used when loading grammar modules. To load the <CODE>aggregate.trc</CODE> which +we created above, we use: +</P> +<PRE> + > i aggregate.trc +</PRE> +<P></P> +<A NAME="toc10"></A> +<H2>Calling Transfer functions</H2> +<P> +To call a Transfer function on a term, we use the <CODE>at</CODE> command. +The <CODE>at</CODE> command takes the name of a Transfer function and an abstract +syntax term, and applies the function to the term: +</P> +<PRE> + > at aggregS ConjS And (Pred John Walk) (Pred Mary Walk) + + Pred (ConjNP And John Mary) Walk +</PRE> +<P></P> +<P> +Of course, the input and output terms of the <CODE>at</CODE> command can +be read from and written to pipes: +</P> +<PRE> + > p "John walks and Mary walks" | at aggregS | l + + John and Mary walk +</PRE> +<P></P> +<P> +To see what is going on between the steps, we can use <CODE>-tr</CODE> flags +to the commands: +</P> +<PRE> + > p -tr "John walks and Mary walks" | at -tr aggregS | l + + ConjS And (Pred John Walk) (Pred Mary Walk) + + Pred (ConjNP And John Mary) Walk + + John and Mary walk +</PRE> +<P></P> +<A NAME="toc11"></A> +<H3>Transfer between different abstract syntaxes</H3> +<P> +If the transfer function which you wan to call takes as input a term in one +abstract syntax, and returns a term in a different abstract syntax, you +can use the <CODE>-lang</CODE> flag with the <CODE>at</CODE> command. This is needed since the +<CODE>at</CODE> command type checks the result it produces, and it needs to +know which abstract sytnax to type check it in. +</P> + +<!-- html code generated by txt2tags 2.0 (http://txt2tags.sf.net) --> +<!-- cmdline: txt2tags darcs.txt transfer-reference.txt transfer-tutorial.txt transfer.txt --> +</BODY></HTML> diff --git a/doc/transfer-tutorial.txt b/doc/transfer-tutorial.txt new file mode 100644 index 000000000..dba660871 --- /dev/null +++ b/doc/transfer-tutorial.txt @@ -0,0 +1,164 @@ +Transfer tutorial +Author: Björn Bringert <bringert@cs.chalmers.se> +Last update: %%date(%c) + +% NOTE: this is a txt2tags file. +% Create an html file from this file using: +% txt2tags -t html --toc darcs.txt + +%!target:html +%!options(html): --toc + + + += Objective = + +We want to write a Transfer program which we can use to do aggregation +in sentences which use conjugations on the sentence, noun phrase and +verb phrase levels. For example, we want to be able to transform +the sentence "John walks and Mary walks" to the sentence +"John and Mary walk". We would also like to transform +"John walks and John swims" to "John walks and swims". + +Thus that what we want to do is: + +- Transform sentence conjugation where the verb phrases in the sentences + are identical to noun phrase conjugation. +- Transform sentence conjugation where the noun phrases in the sentences + are identical to verb phrase conjugation. + + +This needs to be done recursively and thoughout the sentence, to be +able to handle cases like "John walks and Mary walks and Bill walks", and +"John runs and Mary walks and Bill walks". + + +FIXME: what about John walks and Mary runs and Bill walks"? + + += Abstract syntax = + +We will use the abstract syntax defined in +[Abstract.gf ../transfer/examples/aggregation/Abstract.gf]. + += Concrete syntax = + +There is an English concrete syntax for this grammar in +[English.gf ../transfer/examples/aggregation/English.gf]. + += Generate tree module = + +To be able to write Transfer programs which use the types defined in +an abstract syntax, we first need to generate a Transfer file with +a data type defintition corresponding to the abstract syntax. +This is done with the ``transfer`` grammar printer: + +``` +$ gf +> i English.gf +> pg -printer=transfer | wf tree.tr +``` + +Note that you need to load a concrete syntax which uses the abstract +syntax that you want to create a Transfer data type for. Loading just the +abstract syntax module is not enough. FIXME: why? + +The command sequence above writes a Transfer data type definition to the +file ``tree.tr``. + + += Write transfer code = + +We write the Transfer program +[aggregate.tr ../transfer/examples/aggregation/aggregate.tr]. + +FIXME: explain the code + += Compiling Transfer programs = + +Transfer programs are written in the human-friendly Transfer language, +but GF only understands the simpler Transfer Core language. Therefore, +before using a Transfer program, you must first compile it to +Transfer Core. This is done using the ``transferc`` command: + +``` +$ transferc -i<lib> <transfer program> +``` + +Here, ``<lib>`` is the path to search for any modules which you import +in your Transfer program. You can give several ``-i`` flags. + +So, to compile ``aggregate.tr`` which we created above, we use: + +``` +$ transferc aggregate.tr +``` + +The creates the Transfer Core file ``aggregate.trc``. + + += Using Transfer programs in GF = + +== Loading the grammars == + +To use a Transfer Core program to transform abstract syntax terms +in GF, you must first load the grammars which you want to use the +program with. For the example above, we need the grammar ``English.gf`` +and its dependencies. We load this grammar with: + +``` +> i English.gf +``` + +== Loading the Transfer program == + +There are two steps to using a Transfer Core program in GF. First you load +the program into GF. This is done with the ``i`` command, which is also +used when loading grammar modules. To load the ``aggregate.trc`` which +we created above, we use: + +``` +> i aggregate.trc +``` + +== Calling Transfer functions == + +To call a Transfer function on a term, we use the ``at`` command. +The ``at`` command takes the name of a Transfer function and an abstract +syntax term, and applies the function to the term: + +``` +> at aggregS ConjS And (Pred John Walk) (Pred Mary Walk) + +Pred (ConjNP And John Mary) Walk +``` + +Of course, the input and output terms of the ``at`` command can +be read from and written to pipes: + +``` +> p "John walks and Mary walks" | at aggregS | l + +John and Mary walk +``` + +To see what is going on between the steps, we can use ``-tr`` flags +to the commands: + +``` +> p -tr "John walks and Mary walks" | at -tr aggregS | l + +ConjS And (Pred John Walk) (Pred Mary Walk) + +Pred (ConjNP And John Mary) Walk + +John and Mary walk +``` + +=== Transfer between different abstract syntaxes === + +If the transfer function which you wan to call takes as input a term in one +abstract syntax, and returns a term in a different abstract syntax, you +can use the ``-lang`` flag with the ``at`` command. This is needed since the +``at`` command type checks the result it produces, and it needs to +know which abstract sytnax to type check it in.
\ No newline at end of file diff --git a/doc/transfer.html b/doc/transfer.html new file mode 100644 index 000000000..87c5bb05f --- /dev/null +++ b/doc/transfer.html @@ -0,0 +1,30 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> +<META NAME="generator" CONTENT="http://txt2tags.sf.net"> +<TITLE>The GF Transfer language</TITLE> +</HEAD><BODY BGCOLOR="white" TEXT="black"> +<P ALIGN="center"><CENTER><H1>The GF Transfer language</H1> +<FONT SIZE="4"> +<I>Author: Björn Bringert <bringert@cs.chalmers.se></I><BR> +Last update: Tue Dec 6 14:26:07 2005 +</FONT></CENTER> + +<P> +The GF Transfer language is a programming language which can be +used to write functions which work on abstract syntax terms. +</P> +<H1>Transfer tutorial</H1> +<P> +The <A HREF="transfer-tutorial.html">Transfer tutorial</A> shows an example of how to +write and use a simple transfer function for a GF grammar. +</P> +<H1>Transfer reference</H1> +<P> +The <A HREF="transfer-reference.html">Transfer reference</A> aims to cover +all constructs in the Transfer language. +</P> + +<!-- html code generated by txt2tags 2.0 (http://txt2tags.sf.net) --> +<!-- cmdline: txt2tags darcs.txt transfer-reference.txt transfer-tutorial.txt transfer.txt --> +</BODY></HTML> diff --git a/doc/transfer.txt b/doc/transfer.txt new file mode 100644 index 000000000..7952aae5f --- /dev/null +++ b/doc/transfer.txt @@ -0,0 +1,24 @@ +The GF Transfer language +Author: Björn Bringert <bringert@cs.chalmers.se> +Last update: %%date(%c) + +% NOTE: this is a txt2tags file. +% Create an html file from this file using: +% txt2tags transfer.txt + +%!target:html + +The GF Transfer language is a programming language which can be +used to write functions which work on abstract syntax terms. + += Transfer tutorial = + +The [Transfer tutorial transfer-tutorial.html] shows an example of how to +write and use a simple transfer function for a GF grammar. + + += Transfer reference = + +The [Transfer reference transfer-reference.html] aims to cover +all constructs in the Transfer language. + diff --git a/doc/txt2html.sh b/doc/txt2html.sh new file mode 100644 index 000000000..801541e95 --- /dev/null +++ b/doc/txt2html.sh @@ -0,0 +1,13 @@ +#!/bin/sh + +FILES="darcs.txt transfer-reference.txt transfer-tutorial.txt \ + transfer.txt" + +for f in $FILES; do + h=`basename "$f" ".txt"`.html + if [ "$f" -nt "$h" ]; then + txt2tags $f + else + echo "$h is newer than $f, skipping" + fi +done |