DOT PROMPT...........The Dot-Prompt Interpreter
COMMAND LINE.........The Command Line editor
NAVIGATION...........Navigating the command-line and command-stack
COMMAND SETS.........Including, Excluding, and Disabling Command Sets
MACRO-COMPILER.......The Macro-Compiler's role in the interpreter
HOT KEYS.............Hot-keys at the dot-prompt
VARIABLE SCOPING.....Accessing and creating variables at the dot-prompt
SET KEYS.............Setting and using SET KEYS at dot-prompt
DOT PROMPT
The Dot-Prompt Interpreter
Description:
dCLIP's main strength is it's interpreter which provides
similar functionality to the dBASE/FoxPro dot-prompt. The
heart of dCLIP's interpreter is the built-in pre-processor and
command-set that pre-processes all Clipper commands and dCLIP
commands to run sets of functions from the Clipper libraries
and dCLIP libraries which are linked into the application.
In addition, the interpreter will translate all commands that
have been loaded into the pre-processor array from header
(*.CH) files.
If you grew up with dBASE-II or dBASE-III and graduated to
Clipper, you will find yourself in familiar territory when you
start the dCLIP program. The dCLIP dot prompt is similar to the
dBASE interactive programming environment that allows any of
the builit-in command set to be invoked from the dot prompt.
dCLIP is slightly different however, because it combines the
best of 3 worlds. This "integration" of a pre-processor,
intepreter, and compiler allows unsurpassed speed and
compatability in accomplishing Clipper development tasks.
When a command is entered at the dot-prompt, it's first passed
through the Clipper-compatible pre-processor to convert it to a
set of expressions. The expression list is then
"macro-compiled" and evaluated.
The dCLIP dot prompt is fully-interactive, meaning that you get
an instant response to the command at the moment you enter it
from the keyboard.
EXAMPLE:
Assume that your client wants to get a quick average of all
sales within a specified date period. Then he wants to
replace the sales representative for all his CALIFORNIA
customers. If you did not accomodate this capability in your
executable program, your client is out of luck or must
accomplish the task without the aid of your program. With
dCLIP or the DC_DOT() function linked into your program, this
task can be accomplished in seconds by entering the following
commands at the dot:
. USE \ACCTSPAY\CUSTOMER VIA DBFSIX
. AVER SALES TO TOTSALES FOR SHIPDATE ) DATE()-30
. ? TOTSALES 12677.52
. REPL SALESREP WITH 'JONES' FOR STATE='CA'
If you like working from a command-line, then the DOT is the
starting place or "home" for just about everything you need to
do in dCLIP. You can run any other executable program
(regardless of size), run any DOS command, run any Clipper or
dCLIP command, evaluate any Clipper expression UDF, execute any
batch file, edit source files, even compile and run object code
without ever leaving the interactive environment of the dot
prompt. When you run an application program, you will return
to the DOT. When you run another executable program such as
your own editor, word- processor, spread-sheet, calendar, etc.
you will return to the DOT. When you compile your source code,
you will return to the DOT.
COMMAND LINE
The Command Line editor
Description:
The command line prompt is always at the bottom row of the
display and is preceded with a DOT (.) to prompt you that dCLIP
is waiting for you to enter a command.
The dot prompt command line editor allows you to enter any
command (including complex expressions with functions) up to
254 characters in length. The screen will horizontally scroll
if you pass the 79th column. All the editing keys which are
valid in the Clipper MEMOEDIT() function can be used on this
command line. You can enter insert mode, delete characters,
delete words, move forward or back, etc. - see NAVIGATION.
Each time a command is entered, it is saved away in a "command
stack" so you may reinvoke it at any time by simply moving up
or down through the previous commands with the up/down arrow
keys or the PgUp/PgDn keys. After you find the command you
wish, the stack pointer is now moved to that command and you
can simply reinvoke all the previously entered commands by
pressing (enter) for each command.
The CTRL-PGUP key will take you to the top of the command stack
and the CTRL-PGDN key will take you to the end of the command
stack. The command stack allows up to 100 commands before it
starts "wrapping" and writing over the top of the stack.
The main advantage of this method of handling previous commands
is in the ability to step through a set of commands succesive
times after changing something in the environment, using new
data files, or slightly modifying the commands for a different
set of parameters.
If a command is entered with improper "syntax", then the
message "Syntax error" is displayed on the screen and the
command stack pointer will continue to display the entered
command so you can make changes without retyping the entire
command. If you want to clear the command line and remove a
command from the stack just press ESCAPE after selecting the
desired command from the stack.
NAVIGATION
Navigating the command-line and command-stack
Description:
The command line editor Navigation keys are described as
follows:
Key Function
---------------- --------------------------
Ctrl-E/Up Arrow Go to Previous command in stack
Ctrl-X/Dn Arrow Go to Next command in stack
Ctrl-A/Ctrl-Left Move left one word
Ctrl-F/Ctrl-Right Move right one word
Ctrl-C/PgDn Go to bottom of command stack
Ctrl-R/PgUp Go to top of command stack
ESCape Delete command from stack
Home/Ctrl-PgUp Go to beginning of line
End/Ctrl-PgDn Go to End of line
Ctrl-V Toggle insert mode
Ctrl-G Delete character at cursor
Ctrl-S/Left Arrow Move left one character
Ctrl-D/Right Arrow Move right one character
Ctrl-T Delete word right
Ctrl-C/PgDn Go to bottom of command stack
Ctrl-R/PgUp Go to top of command stack
Enter Process entered command
. (enter) Pop-up command stack pick-list
COMMAND SETS
Including, Excluding, and Disabling Command Sets
Description:
The dot-prompt interpreter supports the ability to create your
own commands by either loading pre-existing command-definition
(*.CH) files or by creating them on the fly. The complete
command sets supported by STD.CH, DCLIP.CH, and DBFSIX.CH are
compiled into the dCLIP command translator so there is no need
to perform any special initialization to activate these default
command sets.
LOADING A NEW COMMAND SET
Additional command sets can be loaded by several methods:
1. Use the INCLUDE or #INCLUDE command to load the *.CH
command set.
2. Use the INCLUDE command to load a "compiled" command set by
dynamic-linking an .OBJ file created with INCLUDE..TO.
3. Use INCLUDE=(cCommandSet) in DCLIP.SYS file to automatically
load a *.CH file when starting dCLIP or calling DC_DOT()
the first time.
4. Use INCLUDE=(cCommandSet).OBJ in DCLIP.SYS to automatically
"activate" a "compiled" command set that was linked into the
dCLIP.EXE engine or your application.
UNLOADING A COMMAND SET
Previously loaded command sets can be permanently removed from
memory by using the EXCLUDE command at the dot prompt. You
must issue the same name that was assigned to the command set
when it was loaded less any pathing information. This name is
the prefix of the .CH file or .OBJ file. For example, if you
load a command set as follows:
. INCLUDE \DBFSIX\MACHSIX
then it can be unloaded as follows:
. EXCLUDE MACHSIX
ACTIVATING / DEACTIVATING A COMMAND SET
A loaded command set can be temporarily deactivated by using
the command:
. DISABLE (cCommandSet)
and then reactivated with:
. ENABLE (cCommandSet)
Deactivating (DISABLEing) a command set has the same affect as
if the command set was never loaded yet the command will remain
in memory so it can be quickly enabled again.
Command sets are automatically activated when they are loaded.
COMMAND EVALUATION ORDER
Commands are evaluated on a last-in, first-out basis, i.e. if
you wish to replace the default USE command with your own USE
command, loaded command sets will be evaluated before internal
command sets. If a new command set is loaded with another USE
command, then it will be evaluated before the previously loaded
command set.
Commands within command sets are evaluated from the bottom up,
i.e. if you have two USE commands in the same command set, the
last USE command will be evaluated for proper syntax first.
THE "DOT" COMMAND SET
Commands which are created with the #TRANSLATE command or
#DEFINE at the dot prompt are stored in a command-set labeled
"DOT". This command set can also be DISABLEd or EXCLUDEd if
you wish to clear out all your "on-the-fly" commands.
MACRO-COMPILER
The Macro-Compiler's role in the interpreter
Description:
Clipper's Macro-compiler is the "heart" of dCLIP's interpreter.
The macro compiler compiles expressions at runtime almost in
the same way Clipper.exe compiles code into .OBJ files. The
macro-compiler was designed to allow a "late-binding" affect so
the functionality of the application isn't fixed to a specified
sequence of routines, but instead allows the user to create
custom functionality on the fly.
Basically, the way dCLIP accomplishes this task is a follows:
1. A command is entered at dot prompt.
2. The command line is converted to an array of expressions via
the pre-processor.
3. Each expression in the array is evaluated using the macro &
operator.
CAVEATS:
Approximately 99.5 % of all commands and expressions that can
be entered in your source code can also be interpreted at the
dot prompt. As powerful as the Clipper macro-compiler is,
however, it still has it's limitations. The following is a
list of known caveats when using expressions at the dot prompt
due to the limitations of the macro-compiler:
1. Statements such as DO..WHILE, FOR..NEXT, CASE..ENDCASE
cannot be used at the dot prompt because they normally are
part of a program structure and cannot be simply
interpreted. dCLIP supports an alternative method to
accomplish reiterative tasks at the dot prompt by
pre-processing special commands that use new functions like
DC_DOWHILE(), DC_FORNEXT, DC_DOCASE(), DC_DBEVAL(), etc.
See the dot-prompt "FOR" command for an example.
2. Code blocks can be used freely in expressions with the
following limitations:
a. Code blocks cannot be nested.
b. Compound assignment operators (++,--,etc) are not
supported by the macro-compiler in a code block.
3. Array elements can be accessed in the same manner as
accessible in source code except that the macro-compiler
does not support the following:
(function)()[nElement]
If you wish to access a STATIC array element via a function
at the dot prompt, you must first copy the array to a
PRIVATE array as follows:
Source code method:
? colorarray()[1,4]
Dot-prompt method:
aColorArray := colorarray()
? aColorArray[1,4]
HOT KEYS
Hot-keys at the dot-prompt
Description:
Several HOT-KEYs are active at the dot-prompt to speed up the
use of DBMS commands, debugging, and creating expressions.
These keys are redefinable in DCLIP.SYS or the SET COMMAND.
They are as follows:
1. Field Pick-List key (FLDKEY) - Default ALT-F (287)
dCLIP.SYS command: FLDKEY=(nInkey)
Dot prompt command: SET FLDKEY TO (nInkey)
Pressing ALT-F will pop-up a pick-list of all parent and child
fields based on the currently selected work area. The name of
the selected field will then be written to the command line at
the current cursor position.
Example:
. INDEX ON (press Alt-f to select field) TO TEMP
2. Query key (QUERYKEY) - Default ALT-Q (272)
dCLIP.SYS command: QUERYKEY=(nInkey)
Dot prompt command: SET QUERYKEY TO (nInkey)
Pressing ALT-Q will pop-up the query builder to build or
select a complex query from the DCQUERY.DBF database based on
the currently selected work area. The created or selected
query expression will then be written to the command line at
the current cursor position.
Example:
. INDEX ON (press Alt-f) TO TEMP FOR (press Alt-Q for Query
Builder)
3. Character key (CHRKEY) - Default ALT-G (290)
dCLIP.SYS command: CHRKEY=(nInkey)
Dot prompt command: SET CHRKEY TO (nInkey)
Pressing ALT-G will pop-up the ASCII chart pick-list to choose
1 of 256 displayable characters. This is handier than using
ALT and the numeric pad when you wish to enter a character on
the command line that is not a normal keyboard character.
The character selected will be written to the command line at
the current cursor position.
Example:
. @ 10,10,20,40 BOX '(press Alt-G key for picklist)'
4. DEFINE-List key - Default ALT-#/ALT-3 (378)
Pressing ALT-# or ALT-3 will pop-up a pick-list to display
all standard manifest constants defined in the complete set of
Clipper *.CH files. Also included in the list will be all the
manifest constants loaded in user-defined *.CH files with the
INCLUDE command. The "defined value" will be written to the
command line at the current cursor position.
5. Index builder key (INDEXKEY) - Default ALT-I (279)
dCLIP.SYS command: INDEXKEY=(nInkey)
Dot prompt command: SET INDEXKEY TO (nInkey)
Pressing ALT-I will pop-up the index expression builder to
create a complex index expression from pick-lists based on the
currently selected work area. The created index expression
will then be written to the command line at the current cursor
position.
Example:
. INDEX ON (press Alt-Q for index builder) TO TEMP
6. Step key (STEPKEY) - Default ALT-S (287)
dCLIP.SYS command: STEPKEY=(nInkey)
Dot prompt command: SET STEPKEY TO (nInkey)
Pressing ALT-S is equivalent to issuing the command SET STEP
ON for source-level debugging before running a function that
has been compiled with debug information.
Example:
. OBJ MYPROCS
. (Press ALT-S)
. CALC()
VARIABLE SCOPING
Accessing and creating variables at the dot-prompt
Description:
When running the DC_DOT(), DC_QDOT() functions or the main
dCLIP dot prompt or debug dot-prompt, all PUBLIC memvars are
accessible via dot-prompt expressions. LOCALs and STATICs have
no meaning when using the dot-prompt, instead any memory
variable or array created at the dot-prompt is automatically
scoped as PUBLIC and will be retained for the life of the
program or until a RELEASE (memvar) command is issued. If you
want memvars and arrays which were created at the dot- prompt
to be released when returning to the called program, then you
must SET PUBLIC OFF at the dot-prompt or call the function
DC_SETT('PUBLIC',.f.). This action will have the affect of
creating all memvars and arrays as PRIVATE.
If a double-dot prompt was invoked via the ALT-D key (debug
mode), thereby suspending an executing program, the values of
LOCALS and STATICS in the suspended program can be accessed via
the ? command or the WATCH window provided that they are not
included in any expressions which require the macro-compiler.
See DEBUGGING for more information about viewing LOCALs and
STATICs.
SET KEYS
Setting and using SET KEYS at dot-prompt
Description:
The SET KEY command can be issued at the dot-prompt in the same
way it can be used in source code to run a procedure from a
specified key. You must exercise caution however when setting
hot keys because you are actively running a Clipper application
when you are at the dot prompt. dCLIP's command-line editor
uses the clipper MEMOEDIT() function and several keys have been
set to change the behavior of MEMOEDIT() so it will
automatically exit when the Up/Down, PgUp/PgDn, or ENTER keys
have been pressed. If you have your own hot keys set to call a
function while at the dot-prompt, the function will be called
but may not behave properly when trying to use the Up/Down,
PgUp/PgDn or Enter keys. To prevent this problem, make sure
you clear and restore all SET KEYs in your called function.
This can be easily accomplished by adding the following to your
function:
LOCAL aHotKeys := dc_keysave()
(your code)
dc_keyrestore( aHotKeys )
return