Don Porter$Revision: 1.4 $Tcl {C API} subst

This TIP proposes the new public routine Tcl_NRSubstObj to provide extension commands that evaluate Tcl substitutions the ability to do so in a non-recursive manner.

Continuing in the path of and , we want extensions to be able to create NR-enabled commands, and any command procedures currently calling the Tcl_SubstObj routine are not NR-enabled. The solution is to provide the NR-enabled counterpart.

Add the following routine to Tcl's public interface: int Tcl_NRSubstObj(Tcl_Interp *interp, Tcl_Obj *objPtr, int flags) This routine places on the NR stack a request that the Tcl non-recursive trampoline evaluate the objPtr value as a Tcl substitution in interpreter interp, as controlled by the value of flags. The flags value is the same combination of TCL_SUBST_BACKSLASHES, TCL_SUBST_COMMANDS, and TCL_SUBST_VARIABLES that control Tcl_SubstObj. This routine returns the value TCL_OK, since there is (currently) no way this request operation can fail. The proposed interface still provides for an int return value so that future revisions to Tcl's internals have the freedom to change that without need to change the public interface. After the trampoline completes the requested substitution, it will pass the return code, either TCL_OK or TCL_ERROR, to the next callback on the NR-stack, and either the result of the substitution or the error message will be stored in the result of interp. The caller of Tcl_NRSubstObj may also call Tcl_NRAddCallback to request a Tcl_NRPostProc callback routine be placed on the NR stack to receive these results, if needed to achieve the task the caller is performing.

The proposed routine is already present in the HEAD of Tcl as the internal routine TclNRSubstObj. This proposal would simply promote it to Tcl's public interface.

There should be no compatibility issues, since at the interface level this is just the addition of a new routine.

As an example for extensions to follow, consider this template for a Tcl_ObjCmdProc currently calling Tcl_SubstObj. aW50IE9iakNtZChDbGllbnREYXRhIGNkLCBUY2xfSW50ZXJwICppbnRlcnAsIGludCBvYmpjLCBUY2xfT2JqICpjb25zdCBvYmp2W10pICAgIFRjbF9PYmogKnJlc3VsdFB0cjs=ICAgIC8qIGRldGVybWluZSB0ZXh0IHRvIGJlIHN1YnN0aXR1dGVkLCBvYmpQdHIgKi8=ICAgIC8qIGRldGVybWluZSBmbGFncyB2YWx1ZSB0byBjb250cm9sIHN1YnN0aXR1dGlvbiAqLw==ICAgIHJlc3VsdFB0ciA9IFRjbF9TdWJzdE9iaihpbnRlcnAsIG9ialB0ciwgZmxhZ3MpOw==ICAgIGlmIChyZXN1bHRQdHIgPT0gTlVMTCkge3JldHVybiBUQ0xfRVJST1J9ICAgIC8qIHJlc3VsdFB0ciBob2xkcyBzdWJzdGl0dXRpb24gcmVzdWx0OyBjb250aW51ZSAqLw==fQ==VGNsX0NyZWF0ZU9iakNvbW1hbmQoaW50ZXJwLCBuYW1lLCBPYmpDbWQsIC8qIC4uLiAqLyk7 To use Tcl_NRSubstObj to NR-enable this command, rewrite along these lines: aW50IE9iakNtZChDbGllbnREYXRhIGNkLCBUY2xfSW50ZXJwICppbnRlcnAsIGludCBvYmpjLCBUY2xfT2JqICpjb25zdCBvYmp2W10peyAgIHJldHVybiBUY2xfTlJDYWxsT2JqUHJvYyhpbnRlcnAsIE5ST2JqQ21kLCBjZCwgb2JqYywgb2Jqdik7ICB9aW50IE5ST2JqQ21kKENsaWVudERhdGEgY2QsIFRjbF9JbnRlcnAgKmludGVycCwgaW50IG9iamMsIFRjbF9PYmogKmNvbnN0IG9ianZbXSk=eyAgIA==ICAgIC8qIGRldGVybWluZSB0ZXh0IHRvIGJlIHN1YnN0aXR1dGVkLCBvYmpQdHIgKi8=ICAgIC8qIGRldGVybWluZSBmbGFncyB2YWx1ZSB0byBjb250cm9sIHN1YnN0aXR1dGlvbiAqLw==ICAgIFRjbF9OUkFkZENhbGxiYWNrKGludGVycCwgQ2FsbGJhY2ssIC8qLi4uKi8pOw==ICAgIHJldHVybiBUY2xfTlJTdWJzdE9iaihpbnRlcnAsIG9ialB0ciwgZmxhZ3MpOw==fQ==aW50IENhbGxiYWNrKENsaWVudERhdGEgZGF0YVtdLCBUY2xfSW50ZXJwICppbnRlcnAsIGludCBjb2RlKQ==eyAgIFRjbF9PYmogKnJlc3VsdFB0cjs=ICAgIGlmIChjb2RlID09IFRDTF9FUlJPUikge3JldHVybiBUQ0xfRVJST1I7fQ==ICAgIHJlc3VsdFB0ciA9IFRjbF9HZXRPYmpSZXN1bHQoaW50ZXJwKTs=ICAgIC8qIHJlc3VsdFB0ciBob2xkcyBleHByZXNzaW9uIHJlc3VsdDsgY29udGludWUgKi8=fQ==VGNsX05SQ3JlYXRlQ29tbWFuZChpbnRlcnAsIG5hbWUsIE9iakNtZCwgTlJPYmpDbWQsIC8qLi4uKi8pOw==

This document has been placed in the public domain.