## markup.api
## (C) 1996, 1997, 1998, Bremen Institute for Safe Systems, Universitaet Bremen
## Author: cxl (Last modification by $Author: 2cxl $)
# Compiled by:
# src/lib/tk/src/toolkit/sources.sublib# *************************************************************************
#
# The tk Markup Language: writing down annotated texts.
#
# This module allows one to write down texts with embedded
# text_items in an SGML-like format. It supplies a class macro which
# generates a parser for a given format.
#
# $Date: 2001/03/30 13:39:46 $
# $Revision: 3.0 $
#
# In general, the parser recognizes SGML "elements" of the form
# <elname arg1 ... argn> ... <\elname>
# where elname is the name of the element and arg1 ... argn is a list
# of arguments. It further recognizes escape sequences of the form
# &esc; where esc can be lt for "<" and amp for "&". Other escape
# sequences are left as they are. The characters < and & only start
# elements or escape sequences of succeeded with a letter.
#
# An elements like above is called a "tag". Tags are translated into
# tk text_items, as defined by the argument api of the
# class macro.
#
# See tests+examples/markup_ex.pkg for an example of how to
# instantiate this class macro.
#
# *************************************************************************
### "To get the medium's magic
### to work for one's aims
### rather than against them
### is to attain literacy."
###
### -- Alan Kay
api Tags {
Tag;
Widget_Info;
matching_tag: String -> Null_Or( Tag );
text_item_for_tag: Tag -> List( String ) -> Widget_Info ->
((tk::Mark, tk::Mark)) ->
tk::Text_Item;
# generate an annotation for a tag. The second argument is
# the list of arguments given to the tag, the third argument
# is some "widgetinfo" (as passed to get_livetext),
# followed by the marks for the current annotation. Widget_Info
# can be any old type; most of the time, one will want to pass
# the Widget_ID of the text widget, but there may be more infor-
# mation one needs to pass to the functions bound to the tags.
#
# text_item_for_tag can raise the following exception if there
# is an error (eg. not enough arguments), where the argument
# is a warning messaged displayed with warning below.
#
# NB: All elements, their arguments and the escape sequences
# below are uniformly converted to _lower case_. Hence,
# matching_tag and escape only must match for lower case
# arguments.
exception TEXT_ITEM_ERROR String;
# Escape sequences -- analogous to the above, but escapes do not
# have arguments, and on the other hand generate a fixed text.
# So for example, textForEscape α might be "a", and the
# annotation would be TEXT_ITEM_TAG[Font Symbolfont] to generate the greek
# letter alpha.
#
# In contrast to tags, escape sequences are _case sensitive_!
# The reason for this is purely practical, it allows us to
# conveniently and intuitively distinguish e::g. ω and Ω
#
# Lastly, the escape sequences &aml; and < for & and < are
# built-in.
Escape;
escape: String -> Null_Or( Escape );
text_for_esc: Escape -> String;
annotation_for_esc: Escape -> ((tk::Mark, tk::Mark)) ->
null_or::Null_Or( tk::Text_Item );
warning: String -> Void; # how to deal with warnings
error: String -> Exception; # exception to be raised if a
# parsing error occurs
};
api Tk_Markup {
Widget_Info; # same as above
# Given some widgetinfo (first argument), and a
# markup' text, generate an the String containing the text and a
# list of appropriate text_items as above.
#
get_livetext: Widget_Info -> String -> tk::Live_Text;
};