Re-add some files lost from v0.51

In particular the C examples (now in examples.api/)

Signed-off-by: Steve Bennett <steveb@workware.net.au>

8 files changed, 496 insertions, 0 deletions

diff --git a/examples.api/Makefile b/examples.api/Makefile
new file mode 100644
index 0000000..059adda
--- /dev/null
+++ b/examples.api/Makefile
@@ -0,0 +1,16 @@
+CFLAGS+= -Wall -g
+CFLAGS+= -L.. -I..
+CFLAGS+= -ljim
+
+EXAMPLES=		\
+	jim_command	\
+	jim_hello	\
+	jim_list	\
+	jim_obj		\
+	jim_return
+
+all: $(EXAMPLES)
+
+clean:
+	rm -rf $(EXAMPLES)
+	rm -rf *.core
diff --git a/examples.api/README b/examples.api/README
new file mode 100644
index 0000000..d3fc8be
--- /dev/null
+++ b/examples.api/README
@@ -0,0 +1,36 @@
+Jim examples
+============
+BSD 2-clause license, (c) 2010 Wojciech A. Koszek <wkoszek@FreeBSD.org>
+
+
+This directory contains examples of Jim interpreter API. In order to start
+working with Jim API one may just want to copy existing example .c file
+into new file, modify Makefile and start working on a new program.
+
+Existing examples
+=================
+
+jim_command
+	Simple command implementation in Jim's API. Command is then executed
+	in a script encoded within a program.
+
+jim_hello
+	Standard "Hello world!" program.
+
+jim_inline
+	Similar "Hello world!" program, but the result comes from a Tcl
+	script interpreted in Jim. Result is printed back on a terminal.
+
+jim_list
+	Will teach you how to create a list in Jim's API.  Once created,
+	will show how to name and export it, so that variable is visible in
+	the script's source code. Once done, interpretation of separate
+	print.tcl file is presented. As a result, the script can print a
+	list members created from within ANSI C program.
+
+jim_obj
+	Basic object creation in Jim.
+
+jim_return
+	Similar to jim_command example, but implemented command actually
+	returns a value.
diff --git a/examples.api/jim_command.c b/examples.api/jim_command.c
new file mode 100644
index 0000000..43dd8f4
--- /dev/null
+++ b/examples.api/jim_command.c
@@ -0,0 +1,96 @@
+/*-
+ * Copyright (c) 2010 Wojciech A. Koszek <wkoszek@FreeBSD.org>
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ *
+ * $Id$
+ */
+
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define JIM_EMBEDDED
+#include <jim.h>
+
+/*
+ * Program which we want to get executed.
+ */
+#define JIM_PROGRAM	"if {1 < 2} { MySampleCommand sample }"
+
+static int
+MySampleCommandFunc(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
+{
+	const char *str;
+	int len;
+
+	if (argc != 2) {
+		Jim_WrongNumArgs(interp, 1, argv, "string");
+		return (JIM_ERR);
+	}
+
+	str = Jim_GetString(argv[1], &len);
+	assert(str != NULL);
+	printf("%s\n", str);
+
+	return (JIM_OK);
+}
+
+/*
+ * Now we try to write big enough code to duplication our array in Jim's
+ * list implementation. Later, we try to load a sample script in Tcl that
+ * could print our list.
+ */
+int
+main(int argc, char **argv)
+{
+	Jim_Interp *interp;
+	int error;
+
+	/* Create an interpreter. */
+	interp = Jim_CreateInterp();
+	assert(interp != NULL && "couldn't create interpreter");
+
+	/* We register base commands, so that we actually implement Tcl. */
+	Jim_RegisterCoreCommands(interp);
+
+	/* And initialise any static extensions */
+	Jim_InitStaticExtensions(interp);
+
+	/* Register our Jim commands. */
+	Jim_CreateCommand(interp, "MySampleCommand", MySampleCommandFunc,
+	    NULL, NULL);
+
+	/* Run a script. */
+	error = Jim_Eval(interp, JIM_PROGRAM);
+	if (error == JIM_ERR) {
+		Jim_MakeErrorMessage(interp);
+		fprintf(stderr, "%s\n", Jim_GetString(Jim_GetResult(interp), NULL));
+		Jim_FreeInterp(interp);
+		exit(EXIT_FAILURE);
+	}
+
+	Jim_FreeInterp(interp);
+	return (EXIT_SUCCESS);
+}
diff --git a/examples.api/jim_hello.c b/examples.api/jim_hello.c
new file mode 100644
index 0000000..831fcc7
--- /dev/null
+++ b/examples.api/jim_hello.c
@@ -0,0 +1,58 @@
+/*-
+ * Copyright (c) 2010 Wojciech A. Koszek <wkoszek@FreeBSD.org>
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ *
+ * $Id$
+ */
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+#include <jim.h>
+
+int
+main(int argc, char **argv)
+{
+	Jim_Interp *interp;
+
+	interp = NULL;
+
+	/* Create Jim instance */
+	interp = Jim_CreateInterp();
+	assert(interp != NULL && "couldn't create interpreter!");
+
+	/* We register base commands, so that we actually implement Tcl. */
+	Jim_RegisterCoreCommands(interp);
+
+	/* And initialise any static extensions */
+	Jim_InitStaticExtensions(interp);
+
+
+	/* Print a string to standard output */
+	Jim_Eval(interp, "puts {Hello world!}");
+
+	/* Free the interpreter */
+	Jim_FreeInterp(interp);
+	return (EXIT_SUCCESS);
+}
diff --git a/examples.api/jim_list.c b/examples.api/jim_list.c
new file mode 100644
index 0000000..93999fd
--- /dev/null
+++ b/examples.api/jim_list.c
@@ -0,0 +1,112 @@
+/*-
+ * Copyright (c) 2010 Wojciech A. Koszek <wkoszek@FreeBSD.org>
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ *
+ * $Id$
+ */
+
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define JIM_EMBEDDED
+#include <jim.h>
+
+/*
+ * We have a list of sample words in 'C'..
+ */
+const char *strings[] = {
+	"simple",
+	"strings",
+	"which",
+	"should",
+	"get",
+	"interpreted",
+	"by",
+	"Jim",
+};
+
+/* 
+ * We have macros which let us to easily obtain of array presented above
+ */
+#define	ARRAY_SIZE(a)	(sizeof((a)) / sizeof((a)[0]))
+#define	SAMPLE_OBJS	ARRAY_SIZE(strings)
+
+/*
+ * Now we try to write big enough code to duplication our array in Jim's
+ * list implementation. Later, we try to load a sample script in Tcl that
+ * could print our list.
+ */
+int
+main(int argc, char **argv)
+{
+	Jim_Interp *interp;
+	Jim_Obj	*obj[SAMPLE_OBJS];
+	Jim_Obj	*list;
+	int i;
+	int error;
+
+	/* Create an interpreter */
+	interp = Jim_CreateInterp();
+
+	/* We register base commands, so that we actually implement Tcl. */
+	Jim_RegisterCoreCommands(interp);
+
+	/* And initialise any static extensions */
+	Jim_InitStaticExtensions(interp);
+
+	/* Create an empty list */
+	list = Jim_NewListObj(interp, NULL, 0);
+	assert(list != NULL);
+
+	/*
+	 * For each string..
+	 */
+	for (i = 0; i < SAMPLE_OBJS; i++) {
+		/* Duplicate it as an array member. */
+		obj[i] = Jim_NewStringObj(interp, strings[i], -1);
+		assert(obj[i] != NULL);
+
+		/* We append newly created object to the list */
+		Jim_ListAppendElement(interp, list, obj[i]);
+	}
+
+	/* 
+	 * We bind a Tcl's name with our list, so that Tcl script can
+	 * identify the variable.
+	 */
+	Jim_SetVariableStr(interp, "MYLIST", list);
+
+	/*
+	 * Parse a script
+	 */
+	error = Jim_EvalFile(interp, "./print.tcl");
+	if (error == JIM_ERR) {
+		Jim_MakeErrorMessage(interp);
+		fprintf(stderr, "%s\n", Jim_GetString(Jim_GetResult(interp), NULL));
+	}
+	Jim_FreeInterp(interp);
+	return (EXIT_SUCCESS);
+}
diff --git a/examples.api/jim_obj.c b/examples.api/jim_obj.c
new file mode 100644
index 0000000..607ef7c
--- /dev/null
+++ b/examples.api/jim_obj.c
@@ -0,0 +1,76 @@
+/*-
+ * Copyright (c) 2010 Wojciech A. Koszek <wkoszek@FreeBSD.org>
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ *
+ * $Id$
+ */
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define JIM_EMBEDDED
+#include <jim.h>
+
+#define	OBJ_DESC	"hello world"
+
+int
+main(int argc, char **argv)
+{
+	Jim_Interp *interp;
+	Jim_Obj *obj;
+	const char *obj_desc;
+	int obj_size;
+
+	obj = NULL;
+	obj_desc = NULL;
+	obj_size = -1;
+
+	/* Create an interpreter */
+	interp = Jim_CreateInterp();
+
+	/* We register base commands, so that we actually implement Tcl. */
+	Jim_RegisterCoreCommands(interp);
+
+	/* And initialise any static extensions */
+	Jim_InitStaticExtensions(interp);
+
+
+	/* Create some empty object */
+	obj =  Jim_NewObj(interp);
+
+	/* Name the object */
+	Jim_InitStringRep(obj, OBJ_DESC, strlen(OBJ_DESC)) ;
+
+	/* Obtain internal representation of an object */
+	obj_desc = Jim_GetString(obj, &obj_size);
+	assert(obj_desc != NULL && "Jim should return NULL as a description");
+	printf("Object described as '%s'; object size is %d\n", obj_desc,
+	    obj_size);
+
+	Jim_FreeObj(interp, obj);
+	Jim_FreeInterp(interp);
+
+	return (EXIT_SUCCESS);
+}
diff --git a/examples.api/jim_return.c b/examples.api/jim_return.c
new file mode 100644
index 0000000..58b8a94
--- /dev/null
+++ b/examples.api/jim_return.c
@@ -0,0 +1,97 @@
+/*-
+ * Copyright (c) 2010 Wojciech A. Koszek <wkoszek@FreeBSD.org>
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ *
+ * $Id$
+ */
+
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define JIM_EMBEDDED
+#include <jim.h>
+
+/*
+ * Program which we want to get executed.
+ */
+#define JIM_PROGRAM	"set l [CountChars Sample]; puts $l"
+
+/*
+ * Our function.
+ */
+static int
+CountCharsFunc(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
+{
+	const char *str;
+	int len;
+
+	if (argc != 2) {
+		Jim_WrongNumArgs(interp, 1, argv, "string");
+		return (JIM_ERR);
+	}
+	str = Jim_GetString(argv[1], &len);
+	Jim_SetResult(interp, Jim_NewIntObj(interp, (jim_wide)len));
+	return (JIM_OK);
+}
+
+/*
+ * Now we try to write big enough code to duplication our array in Jim's
+ * list implementation. Later, we try to load a sample script in Tcl that
+ * could print our list.
+ */
+int
+main(int argc, char **argv)
+{
+	Jim_Interp *interp;
+	int error;
+
+	/* Create an interpreter. */
+	interp = Jim_CreateInterp();
+	assert(interp != NULL && "couldn't create interpreter");
+
+	/* We register base commands, so that we actually implement Tcl. */
+	Jim_RegisterCoreCommands(interp);
+
+	/* And initialise any static extensions */
+	Jim_InitStaticExtensions(interp);
+
+
+	/* Register our Jim command. */
+	Jim_CreateCommand(interp, "CountChars", CountCharsFunc,
+	    NULL, NULL);
+
+	/* Run a script. */
+	error = Jim_Eval(interp, JIM_PROGRAM);
+	if (error == JIM_ERR) {
+		Jim_MakeErrorMessage(interp);
+		fprintf(stderr, "%s\n", Jim_GetString(Jim_GetResult(interp), NULL));
+		Jim_FreeInterp(interp);
+		exit(EXIT_FAILURE);
+	}
+
+	Jim_FreeInterp(interp);
+	return (EXIT_SUCCESS);
+}
diff --git a/examples.api/print.tcl b/examples.api/print.tcl
new file mode 100644
index 0000000..e05d48b
--- /dev/null
+++ b/examples.api/print.tcl
@@ -0,0 +1,5 @@
+puts "-- List present in an array constructed from C program --"
+foreach {str} $MYLIST {
+	puts $str
+}
+puts "---------------------------------------------------------"