Alpha_1 Programmer's Manual
Alpha_1 Programmer's Manual
Also, it is not necessary to be a "terminal" application to use the Scl parser and interpreter. There is a C++ interface to these functions in addition to the stdin toploop. This means you can have a graphical interface (i.e., text widgets) to the Scl interpreter.
Once you have decided which type of application to write, the job of the main program is to perform the required initializations.
First, create two static variables for the array of packages and its size in the file containing the main program. Using the current "standard" set of packages you would have this:
/****************************************************************
* TAG( pkgs )
*/
static model_pkg_type *pkgs[] =
{
&anchor_pkg,
&io_pkg,
&feature_pkg,
&fsketch_pkg,
&bushing_pkg,
&arithmetic_pkg,
&array_pkg,
&prop_pkg,
&stock_pkg,
&xform_pkg,
&geom_pkg,
&mfg_pkg,
&pt_pkg,
&vec_pkg,
&ln_pkg,
&link_pkg,
&circ_pkg,
&arc_pkg,
&number_pkg,
&curve_pkg,
&srf_pkg,
&sym_pkg,
&prim_pkg,
&setop_pkg,
&group_pkg,
&assembly_pkg,
&render_pkg,
&poly_pkg,
&plane_pkg,
&shape_op_pkg,
&nc_help_pkg,
&dim_pkg
};
/****************************************************************
* TAG( n_pkgs )
*/
static int n_pkgs = sizeof( pkgs ) / sizeof( model_pkg_type * );
Once these variables are defined, you initialize the symbol table in
the main program with a static member function of the
model_obj class:
model_obj::load_pkgs( pkgs, n_pkgs );
The following includes are required:
#include <model/model_pkg.h> #include <model/_model.h>
/* Set toploop printer function pointer. */
print_concise = pr_concise;
This function resides in the library. This requires the following
includes:
#include <obj_info.h> #include <model/pr_concise.h>After initializing the symbol table and the print_concise variable, the main program calls the static member function "shape_edit" to process stdin:
model_obj::shape_edit();
exit( 0 );
This function does not return until it reads an EOF on
stdin or the user types quit; to the
interpreter. See c_shape_edit.C for an example of a "terminal" application.
In this case there is usually a way to specify a file handler callback to handle Scl input on stdin. Using the Tcl/Tk toolkit for graphics applications, for example, you use:
/* Stdin file handler feeds c_shape_edit toploop. */
Tk_CreateFileHandler( 0, TK_READABLE, scl_handle_stdin, NULL );
model_obj::print_banner(); /* Print initial prompt. */
Tk_MainLoop();
The callback scl_handle_stdin is in the libTCL
library and looks like this:
void
scl_handle_stdin( ClientData, int )
{
if ( model_obj::read_and_eval() == 0 )
exit( 0 );
dlm.flush_dev();
}
The static member function model_obj::read_and_eval reads
stdin until a full expression has been parsed, evaluates it,
prints the result on stdout, and prints the next prompt.
The function returns 0 if an EOF is encountered or
the user types quit;.Before calling the graphics package event handler, the "c_shape_edit" welcome banner and the first prompt is printed by model_obj::print_banner():
Alpha1 C++ Shape Editor 1 shape_edit>For more, see the Shape3d section in Writing Alpha_1 Tck/Tk Applications.
class model_obj ...
{
...
public:
static void register_new_hook( model_hook_fp_type fp );
static void register_update_hook( model_hook_fp_type fp );
static void register_hint_hook( hint_hook_fp_type fp );
...
};
The "new hook" is called whenever a new model_obj is
created. The "update hook" is called whenever a model_obj is
modified (directly or by dependency propagation). The "hint hook" is
called by the Scl functions "show", "unshow", "highlight", and
"unhighlight." The libTCL library provides an update hook
(scl_update_hook) and
a hint hook (scl_handle_hint) for Tcl/Tk based applications to use.
class model_obj ...
{
...
public:
static void set_up_server( int serv_num = 0,
boolean_type fg = TRUE );
...
};
This uses the libMI model_server_type object called
ms to provide the server functionality. As the
program exits the following should be called:
...
ms.quit_server();
exit( 0 );
For "terminal" applications, this is all that is needed. The
"shape_edit" toploop will handle all client connections and
requests. For "graphics" applications that also wish to be servers, there is a polling function model_obj::polling_toploop which can be used as a "work procedure" or "idle procedure" with graphics application event toploops. This capability has only be experimented with and there is no current application that uses it.
class model_obj ...
{
...
public:
static string_type eval_string( string_type expr,
value_obj **return_result = NULL );
...
};
The input string must be a complete Scl expression. If
return_result is provided, the return value of the Scl
interpreter is passed back via this pointer. There is currently no
public helper function for printing this result. The return value of
the model_obj::eval_string function is NULL if it is
successful, and an error message otherwise.
class model_obj ...
{
...
public:
static model_obj *new_model( object_type *param );
static model_obj *new_model( const string_type cons_fn,
prereq_obj *args );
static model_obj *new_model( const string_type obj_name );
...
};
The first creates a model object with a value, but no prerequisites or
constructor function. The resulting model object can be used as a
prerequisite for future model objects and its value can later be updated
(and propagated to its dependents). The model object "owns"
the param argument and it does not copy it, so the
application must provide the copy if required.The second "constructor" takes a function and a list of arguments and creates a model object. The function names are the same as used in Scl (they must be all lower case, however). See section below on constructing argument lists. The resulting model object "owns" the argument list.
The last "constructor" loads a named object and makes a model object from it (with a value but no prerequisites). This "constructor" names the object as well, binding it into the Scl symbol table.
All of the these function return NULL if there is an error. An error message can be found in the static data member model_obj::emsg
Here are some examples:
model_obj *
make_model( object_type *o )
{
/* Somebody else owns "o". */
return model_obj::new_model( o->cp_obj() );
}
model_obj *
make_pt( real_type x, real_type y )
{
prereq_obj *args = NULL;
append_fl_arg( x, args );
append_fl_arg( y, args );
model_obj *m = model_obj::new_model( "pt", args );
if ( !m )
SCREAM( "Model error: %s\n", model_obj::emsg );
return m;
}
model_obj *
load_named_obj( const string_type name )
{
return model_obj::new_model( name );
}
class model_obj ...
{
...
public:
static model_obj *model_from_name( const string_type name );
void rename( const string_type new_name );
...
};
class model_obj ...
{
...
public:
boolean_type update_model( object_type *param );
boolean_type update_model( const string_type cons_fn,
prereq_obj *args );
...
};
These roughly correspond to the two types of constructors
available. Either update method can be called on any model object. It
does not matter how it was constructed or what its current state
is. The first method updates the model object's value and propagates
the change through the graph. It removes any links to the old
prerequisites and the old constructor function (if there was one). The
second one constructs a new value for the model object from the given
constructor function and arguments and then propagates the
change. The update method "owns" the argument list
(args). Both return FALSE if there is an error and
the static model_obj::emsg contains the error message (a text
buffer).
extern void append_int_arg( int i, prereq_obj *&arglist ); extern void append_fl_arg( real_type fl, prereq_obj *&arglist ); extern void append_bool_arg( boolean_type b, prereq_obj *&arglist ); extern void append_str_arg( string_type str, prereq_obj *&arglist ); extern void append_model_arg( model_obj *obj, prereq_obj *&arglist ); extern void prepend_int_arg( int i, prereq_obj *&arglist ); extern void prepend_fl_arg( real_type fl, prereq_obj *&arglist ); extern void prepend_bool_arg( boolean_type b, prereq_obj *&arglist ); extern void prepend_str_arg( string_type str, prereq_obj *&arglist ); extern void prepend_model_arg( model_obj *obj, prereq_obj *&arglist );Start with a NULL list and then use the above functions:
prereq_obj *args = NULL;
append_int_arg( 1, args );
append_fl_arg( 3.14159, args );
...
model_obj *curr_model;
prereq_obj *args = NULL;
/* Traverse some list of model objects. */
while ( ... )
append_model_arg( curr_model, args );
model_obj *array = model_obj::new_model( "array", args );
args = NULL; /* Now make the "outlineCrv" argument list. */
append_model_arg( array, args );
append_bool_arg( open_flag, args );
model_obj::new_model( "outlinecrv", args );
...
If possible, it is recommended that constructions be done through the
Scl parser and interpreter as this avoids the somewhat error prone
process of constructing argument lists in C++. The trade-off is that
the interpreter (model_obj::eval_string) requires the use of
names whereas direct construction make "anonymous" unnamed objects.
class model_obj ...
{
...
public:
void save_model( string_type fname );
static void save_model_list( prereq_obj *models,
a1_stream_type *a1_stream );
static void save_model_list( model_list_obj models,
a1_stream_type *a1_stream );
static void save_model_list( prereq_obj *models,
const cstring_type fname );
static void save_model_list( model_list_obj models,
const cstring_type fname );
static model_list_obj *restore_model( a1_stream_type *a1_stream );
static model_list_obj *restore_model( const cstring_type fname );
static model_list_obj *restore_model( FILE *fp );
...
};
class model_obj ...
{
...
public:
static boolean_type demand_eval, trace_changes, propagate_changes,
parse_echo, interp_echo, type_matching;
...
};
The descriptions are:
Alpha_1 Programmer's Manual Home Page