Debian package wip

[chiark-tcl.git] / base / chiark-tcl.h

diff --git a/base/chiark-tcl.h b/base/chiark-tcl.h
index 4c022cb82c8c5922ecf2ac7046af64643a8e4216..2f80d58172904c0eea95e3feef49fe1e04e294da 100644 (file)
--- a/base/chiark-tcl.h
+++ b/base/chiark-tcl.h
@@ -1,4 +1,21 @@
 /*
+ * base code for various Tcl extensions
+ * Copyright 2006 Ian Jackson
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation; either version 2 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301, USA.
  */
 
 #ifndef CHIARK_TCL_H
@@ -35,20 +52,30 @@ int cht_pat_enum(Tcl_Interp*, Tcl_Obj*, const void**,
 
 /* from scriptinv.c */
 
-typedef struct { /* semi-opaque - read only, and then only where commented */
-  Tcl_Interp *ip; /* valid, non-0 and useable if set */
-  Tcl_Obj *obj; /* non-0 iff set (but only test for 0/non-0) */
-  Tcl_Obj *xargs;
-  int llength;
+typedef struct { /* opaque; comments are for scriptinv.c impl'n only */
+  /* states:                Cancelled       Set                          */
+  Tcl_Interp *ipq;     /*    0               valid, non-0, useable       */
+  Tcl_Obj *script;     /*    0               valid, non-0                */
+  Tcl_Obj *xargs;      /*    0               valid, may be 0             */
+  int llen;            /*    undefined       llength of script + xargs   */
 } ScriptToInvoke;
 
-void cht_scriptinv_init(ScriptToInvoke *si);
+void cht_scriptinv_init(ScriptToInvoke *si); /* undefined -> Cancelled */
 int cht_scriptinv_set(ScriptToInvoke *si, Tcl_Interp *ip,
-                 Tcl_Obj *newscript, Tcl_Obj *xargs);
-void cht_scriptinv_cancel(ScriptToInvoke *si); /* then don't invoke */
-  /* no separate free function - just cancel */
+                     Tcl_Obj *newscript, Tcl_Obj *xargs);
+  /* Cancelled/Set -> Set (newscript!=0, ok) / Cancelled (otherwise) */
+void cht_scriptinv_cancel(ScriptToInvoke *si);
+  /* Cancelled/Set -> Cancelled.  No separate free function - just cancel. */
+#define cht_scriptinv_interp(si) ((si)->ipq)
+  /* int cht_scriptinv_interp(ScriptToInvoke *si);  returns 0 if Cancelled */
+
+int cht_scriptinv_invoke_fg(ScriptToInvoke *si, int argc,
+                           Tcl_Obj *const *argv);
+  /* is a no-op if Cancelled rather than Set */
+  /* if script fails, returns that error */
 
 void cht_scriptinv_invoke(ScriptToInvoke *si, int argc, Tcl_Obj *const *argv);
+  /* if script fails, reports it with Tcl_BackgroundError */
 
 /* from idtable.c */