Stephen Pelc, 21 August 2006

20060922 Enhanced current practice section.
Fixed some typos.
20060821 First draft.


Rationale
=========
Problem
-------
Various words have been used to generate a new name for an
existing word. This required when porting code and when
generating application wordlists that contain a reference
to an existing word, e.g. when providing limited access
to Forth system kernel words.

Especially with native code compiling Forth systems and cross
compilers, these words have not provided full access to the
required behaviour. The behaviour may require carnal knowledge
of the underlying system, which is one reason why SYNONYM should
be standardised.

Current practice
----------------
The proposed form SYNONYM has been in use at MPE with cross
compilers and VFX Forth since 1998. It is also implemented
in Win32Forth and PFE.

Many people have suggested that we stay with words such as
AKA, ALIAS or ALIAS:, usually of the form

' oldname ALIAS newname

This has merit in terms of common practice, but will break
code for several systems. Some systems, e.g. cross compilers,
cannot generate enough information using the xt of a word alone.
All surveyed systems can implement SYNONYM.

Solution
--------
Although many people have objected to parsing words, parsing
permits the host system the most flexibility in implementation
and is thus the preferred solution.

The syntax is:
SYNONYM <newname> <oldname>
where <newname> will behave identically to <oldname>.

Note that <newname> may be the same as <oldname>.

Proposal
========
10.6.2.xxxx SYNONYM
synonym FACILITY EXT

( "<spaces>newname" "<spaces>oldname" -- )
For both strings kip leading space delimiters. Parse name
delimited by a space. definition for newname with the semantics
defined below. Newname may be the same as oldname.

newname interpretation: ( i*x -- j*x )
Perform the interpretation semantics of oldname

newname compilation: ( i*x -- j*x )
Perform the compilation semantics of oldname

Ambiguous conditions:
The word newname is parsed by ' or ['] or POSTPONE.
oldname is not found.
IMMEDIATE is used for a word defined by SYNONYM.

Labelling
=========
TBD

Reference Implementation
========================
The implementation of SYNONYM requires carnal knowledge of the host
implementation, which is one reason why it should be standardised.
The implementation below is imperfect and specific to VFX Forth.

: Synonym \ <"new-name"> <"curdef"> --
\ *G Create a new definition which redirects to an existing one.
create immediate
hide ' , reveal
does>
@ state @ 0= over immediate? or
if execute else compile, then
;

Test Cases
==========
TBD