[Texmacs-dev] Re: Buffers, Views, Windows, etc.

[David Allouche]

The scheme interface is going to be reorganized, and there have been
an expressed need to devise a well thought out calling convention for
functions which apply to windows, views and buffers.


Object properties

  In order to simplify the scheme interface, a number of getter and
  setter functions will use a new "TM property" inteface to access
  internal properties.

  Window properties

    "views": list of views displayed in this window
    ("view" N): attribute, Nth item of "views" list.
    "current view": view currently active [more...]


  View properties

    "buffer": buffer displayed by this view
    "window": window displaying this view or #n
    "point": logical caret position
    "style": style name  used by this view
    "packages": list of additional package names
    "shrinking factor"... etc, all global settings for the buffer
    [more...]


  Buffer properties

    "read only": boolean
    "source tree": (explanation needed?)
    [more...]


Getters and setters

  Buffer, views and windows provide getter and setter functions to
  access their properties. They provide implicit form, which assume
  the buffer/view/window object from context, and explicit form which
  get this object as a parameter.

  As an notational rule, we suggest that explicit forms are named
  after the corresponding implicit forms plus a star.

  Implicit forms

    (buffer-get prop)            --> value
    (buffer-set prop value)      --> #n

  Explicit forms

    (buffer-get* buf prop)       --> value
    (buffer-set* buf prop value) --> #n


Associations

  window (0,1)---(1,*) view (0,*)---(1) buffer


Calling conventions

  Explicit

    Each window/view/buffer related function takes the target object
    as parameter: e.g. (buffer-set buffer prop value)

    There are no implicit forms, so the explicit forms are named
    without star.

    This convention is the safest, but it may lead to excessive use of
    the current-* functions since most actions are applied to the
    current window/view/buffer.

  Current implicit

    All window/view/buffer related function applies implicitely to the
    current object. However, they all provide variants to use with
    explicit objects.

    That conventions seems to be the more natural and is not very
    complex. Simple things stay simple, and complicated things are
    possible.

  Dynamically scoped implicit

    Joris seems to like the idea of having macros for temporarily
    setting the current window/view/buffer:
    e.g. (with-buffer buf . body).

    The with-* macros would keep simple things simple, and may allow
    to make some complicated things in a terse way. However, maximum
    terseness may only be achieved if call with explicit context is
    allowed as well.

    The obvious way to do it is to have the with-buffer macro to
    temporarily set the "current buffer" global variable. However,
    that may cause subtle problems since indirectly called functions
    may expect the current buffer to be the *real* current buffer.

  Lexically scoped implicit

    The problem with the previous convention is typically a problem of
    dynamic scoping, in Lisp parlance. Scheme is a lexically scoped
    language for a reason... We can expect fewer problems if we use
    lexical scoping semantics.

    We may want some functions to inherit the window/view/buffer of
    the calling scope. Such functions may be defined with a specific
    special form. By default, any function call would restore the
    initial context.


Avoiding conflicts

  Scoped implicit conventions get their name from the use of with-*
  forms used to define a scope in which the context window/view/buffer
  is redefined.

  When a with-* is used, other the-* functions may be undefined if the
  corresponding object is non-existant, or if there are several
  possibilities.

  with-buffer
    
    May unset the-view. 
    If the buffer has an attached view, the-window is set as with
    with-view

  with-view

    Will always set the-buffer.
    May unset the-window is the view is not displayed

  with-window

    Will always unset the-view and the-buffer.


Implementation of lexical scoping

  Most calling conventions have trivial implementationsa, but the
  lexically scoped implicit convention requires some additional
  explanation.

  We propose to implement explicit forms as functions:
  
    (buffer-get* buf prop)       --> value
    (buffer-set* buf prop value) --> #n

  Implicit forms could then be implemented as macros yielding an
  implicit form call:

    (buffer-get prop)       ==> (buffer-get* (the-buffer) prop)
    (buffer-set prop value) ==> (buffer-set* (the-buffer) prop value)

  Explicit expansions use the the-buffer function, which is the base
  of lexical scoping. The the-buffer function defaults (in the
  top-level scope) to the current-buffer function.

  The with-* forms would yield lexical scopes ('let' forms) redefining
  the-buffer, the-window and the-view. We will call that triplet the
  with-context.

  Some functions may want to act in the calling with-context. They
  could be defined by a special form yielding a implicit form macro
  definition and an explicit form function definition:

    (define-with (name . params) . body): macro producing
      (define (name* context . params) (with-restore context . body))
      (define-macro (name . params) (name* (with-context) . params))

  In that example, with-context is a function:

    (define (with-context)
      (list (the-window) (the-view) (the-buffer)))

  and with-restore is a macro:

    (with-restore context . body) ==>
      (let* ((cntxt context)
             (the-window (lambda () (car cntxt)))
             (the-view   (lambda () (cadr cntxt)))
             (the-buffer (lambda () (caddr cntxt))))
         . body)


Identifying buffers/views/windows

  Joris points out this as "the easy part", but I rather see it as a
  very difficult problem... What makes things difficult is the use of
  the "scheme_tree" format internally for callback functions.

  In that format, only lists, strings, symbols and numbers have a
  meaningful representation. Smobs (extension objects) cannot be
  safely used.

  Smobs provide an easy way to make guile's mark-and-sweep system
  interoperate cleanly with the TeXmacs reference counting system, so
  they are a desirable feature.

  Personnally, I do not see the point in using the scheme_tree format
  for callbacks, and I would rather drop it althoghether in favor of
  some opaque scheme_callback class.  


Just my two cents.

-- 
David Allouche         | GNU TeXmacs -- Writing is a pleasure
Free software engineer |    http://www.texmacs.org
   http://ddaa.net     |    http://alqua.com/tmresources
   address@hidden  |    address@hidden
TeXmacs is NOT a LaTeX front-end and is unrelated to emacs.