website 8c4db6c44aea81818370f73283a9a8233be506e0

0 views

Skip to first unread message

letha...@gmail.com

unread,

May 21, 2009, 5:25:42 PM5/21/09

to syx-c...@googlegroups.com

Branch: website
commit 8c4db6c44aea81818370f73283a9a8233be506e0
Author: Luca Bruno <letha...@gmail.com>
Date: Tue Jan 27 16:20:39 2009 +0100

Added lua to syx example

:100644 100644 e4e5f6c... b307eb6... M .gitignore
:100644 100644 59ac320... 7d4ef8b... M css/site.css
:100644 100644 3a442f1... d0d96b8... M wml/Makefile
:100644 100644 b74b426... 7759014... M wml/doc/examples.wml
:000000 100644 0000000... c73dd23... A wml/doc/examples/embedding/lua.wml
:100644 100644 2452a72... f4fafbe... M wml/doc/syntax.inc

diff --git a/.gitignore b/.gitignore
index e4e5f6c..b307eb6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
-*~
\ No newline at end of file
+*~
+*.html
\ No newline at end of file
diff --git a/css/site.css b/css/site.css
index 59ac320..7d4ef8b 100644
--- a/css/site.css
+++ b/css/site.css
@@ -24,6 +24,10 @@ code {
margin: 0.5em 0 0.5em 1em;
}

+em.icode {
+ color: darkred;
+}
+
table {
width: 100%;
}
diff --git a/wml/Makefile b/wml/Makefile
index 3a442f1..d0d96b8 100644
--- a/wml/Makefile
+++ b/wml/Makefile
@@ -6,8 +6,8 @@ DOCINCS=$(wildcard doc/*.inc)
CCDOC=$(CC) $(patsubst %,-i%,$(DOCINCS))
EXINCS=$(wildcard doc/examples/*.inc)
CCEX=$(CCDOC) $(patsubst %,-i%,$(EXINCS))
-SRCS=$(wildcard *.wml) $(wildcard doc/*.wml) $(wildcard doc/examples/basic/*.wml) $(wildcard doc/examples/console/*.wml)
-OBJDIRS=$(TOPDIR)/doc $(TOPDIR)/doc/examples/basic $(TOPDIR)/doc/examples/console
+SRCS=$(wildcard *.wml) $(wildcard doc/*.wml) $(wildcard doc/examples/basic/*.wml) $(wildcard doc/examples/console/*.wml) $(wildcard doc/examples/embedding/*.wml)
+OBJDIRS=$(TOPDIR)/doc $(TOPDIR)/doc/examples/basic $(TOPDIR)/doc/examples/console $(TOPDIR)/doc/examples/embedding
OBJS=$(patsubst %,$(TOPDIR)/%,$(SRCS:.wml=.html))
ARCHIVEDIR=$(subst .,_,$(LATEST))
ARCHIVESRCS=$(patsubst %,$(ARCHIVEDIR)/%,install.wml features.wml release-notes.wml)
@@ -17,20 +17,8 @@ all: $(OBJDIRS) $(OBJS) $(ARCHIVESRCS) $(TOPDIR)/$(ARCHIVEDIR) $(ARCHIVEOBJS)

# Directories creation

-$(TOPDIR)/doc:
- mkdir -p $(TOPDIR)/doc
-
-$(TOPDIR)/doc/examples/basic:
- mkdir -p $(TOPDIR)/doc/examples/basic
-
-$(TOPDIR)/doc/examples/example:
- mkdir -p $(TOPDIR)/doc/examples/example
-
-$(ARCHIVEDIR):
- mkdir -p $(ARCHIVEDIR)
-
-$(TOPDIR)/$(ARCHIVEDIR):
- mkdir -p $(TOPDIR)/$(ARCHIVEDIR)
+$(OBJDIRS) $(ARCHIVEDIR) $(TOPDIR)/$(ARCHIVEDIR):
+ mkdir -p $@

# Release archiving

@@ -50,6 +38,8 @@ $(TOPDIR)/%.html: %.wml $(INCS)

clean:
rm -f $(OBJS)
+ rmdir $(TOPDIR)/doc/examples/embedding
+ rmdir $(TOPDIR)/doc/examples/console
rmdir $(TOPDIR)/doc/examples/basic
rmdir $(TOPDIR)/doc/examples
rmdir $(TOPDIR)/doc
diff --git a/wml/doc/examples.wml b/wml/doc/examples.wml
index b74b426..7759014 100644
--- a/wml/doc/examples.wml
+++ b/wml/doc/examples.wml
@@ -18,7 +18,7 @@

<h3>Embedding</h3>

- Lua to Syx: Embedding a scripting language inside your C/C++ code. The original article related to Lua can be found here
+ Lua to Syx: <a href="$(ROOT)/doc/examples/embedding/lua.html">Embedding a scripting language inside your C/C++ code</a>. The original article related to Lua can be <a href="http://www.debian-administration.org/articles/264">found here</a>


<h3>Web</h3>
diff --git a/wml/doc/examples/embedding/lua.wml b/wml/doc/examples/embedding/lua.wml
new file mode 100644
index 0000000..c73dd23
--- /dev/null
+++ b/wml/doc/examples/embedding/lua.wml
@@ -0,0 +1,334 @@
+{#TITLE#:Lua to Syx:##}
+
+<items>
+ <item "Disclaimer">
+ 
+ First of all, this is a remake of the article <a href="http://www.debian-administration.org/articles/264">Embedding a scripting language inside your C/C++ code</a> of the Lua programming language for Smalltalk YX.
+ 
+ <next "INTRODUCTION">
+ </item>
+
+ <item "Introduction">
+ 
+ These examples can be found in the source distribution of Syx under the examples/embedding directory.
+ 
+
+ 
+ Smalltalk is a well known programming language thanks to its pure object-oriented programming phylosophy and its powerful features such as the graphical environment and reflection. At all, many people don't know what are all the features that Smalltalk YX offers to developers. One of these is the easy embeddability into C/C++ applications.
+ 
+
+ 
+ There are many languages (such as Lua) with the main purpose to be used as scripting languages, but this is the first Smalltalk version you can use for both general and embedding purposes.
+ 
+
+ 
+ This article, briefly describes the main operations you can perform trough the C interface provided by Syx:
+ <ul>
+ <li>Initialise Syx</li>
+ <li>Call from C into a Syx script</li>
+ <li>Call from Syx into your C application</li>
+ </ul>
+ 
+
+ <next "INITIALISING SMALLTALK YX">
+ </item>
+
+ <item "Initialising Smalltalk YX">
+ 
+ The main thing to do before start scripting with Syx into your application, is initializing the entire interpreter engine:
+ <code>
+ #include <syx/syx.h> 
+ 
+ int main (int argc, char *argv[]) 
+ { 
+   /* initialize Syx */ 
+   syx_init (argc, argv, NULL); 
+   
+   /* load the default image */ 
+   syx_memory_load_image (NULL); 
+   
+   /* cleanup Syx */ 
+   syx_quit (); 
+   
+   return 0; 
+ }
+ </code>
+ 
+
+ 
+ Once you have saved this as init.c you can compile it by typeing:
+ <pre>
+ $ gcc -o init init.c -Wall -lsyx
+ </pre>
+ 
+
+ 
+ If you didn't get any errors, you should be able to execute the program and get no output from it:
+ <pre>
+ $ ./init
+ $
+ </pre>
+ 
+
+ 
+ The <f syx_init()> function prepares the external environment of Syx such as the root path and the image path. <f syx_memory_load_image()> loads the image at the given location: in this case we specified NULL which belongs to the default image path. Finally, <f syx_quit()> frees all the memory used by Syx without saving the image.
+ 
+
+ <next "CALLING FROM C INTO A SMALLTALK SCRIPT">
+ </item>
+
+ <item "Calling from C into a Smalltalk script">
+ 
+ Now it's time code more and know how C can interact with Syx. These two examples show the basic operations you can perform to reach the most common purposes for your application.
+ 
+
+ 
+ The first example will illustrate how to load a Smalltalk file, something like emulating the same behavior of <icode syx do-me.st/> from the command line.
+ 
+
+ 
+ The second example pass some arguments to a Smalltalk method in a way much closer to C.
+
+ Copy these lines of code in a file named <file do-me.st/>:
+ <code>
+ 'Start' printNl 
+ 1 to: 10 do: [ :i | 
+     i printNl ]. 
+ 'End' printNl
+ </code>
+ 
+
+ 
+ Now create <file do-me.c/> file to load this file without scheduling the operation:
+ <code>
+ #include <syx/syx.h> 
+ 
+ int main (int argc, char *argv[]) 
+ { 
+   /* initialize Syx */ 
+   syx_init (argc, argv, NULL); 
+   
+   /* load the default image */ 
+   syx_memory_load_image (NULL); 
+   
+   /* now file in our file in blocking mode, .i.e without scheduling the Process */ 
+   syx_file_in_blocking ("do-me.st"); 
+ 
+   /* cleanup Syx */ 
+   syx_quit (); 
+   
+   return 0; 
+ }
+ </code>
+ 
+
+ 
+ Now compile the program as showed in the previous example and run it. The output will be the same as doing <icode syx do-me.st> from the command line:
+ <pre>
+ $ gcc -o do-me do-me.c -lsyx -Wall
+ $ ./do-me
+ Start
+ 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+ 10
+ End
+ $
+ </pre>
+ 
+
+ 
+ Let's create a class named Sum and a simple method <f #with:and:/> that returns the result of adding two numbers. This is the <file add.st/> file:
+ <code>
+ Object subclass: #Sum 
+        instanceVariableNames: '' 
+        classVariableNames: ''! 
+ 
+ !Sum methodsFor: 'examples'! 
+ 
+ with: firstNumber and: secondNumber 
+       ^firstNumber + secondNumber 
+ ! !
+ </code>
+ 
+
+ 
+ I hope you have some knowledge of the Smalltalk interchange format, this cold syntax has been created to let the developer interchange Smalltalk code between different Smalltalk implementation and also to write code outside the Smalltalk environment.
+
+ Let's create a C interface called <file add.c/> and do the equivalent of <icode Sum new with: 3 and: 4/>:
+ <code>
+ #include <syx/syx.h> 
+ 
+ int main (int argc, char *argv[]) 
+ { 
+   SyxOop instance; 
+   SyxOop context; 
+   SyxOop process; 
+   SyxOop result; 
+ 
+   /* initialize Syx */ 
+   syx_init (argc, argv, NULL); 
+   
+   /* load the default image */ 
+   syx_memory_load_image (NULL); 
+   
+   /* now file in class and method declarations from our ST file */ 
+   syx_file_in_blocking ("add.st"); 
+ 
+   /* create a Sum instance */ 
+   instance = syx_object_new (syx_globals_at ("Sum")); 
+   
+   /* create a Process */ 
+   process = syx_process_new (); 
+ 
+   /* create a MethodContext which sends the #with:and: message */ 
+   context = syx_send_message (instance,                    // the receiver 
+                               "with:and:",                 // the selector 
+                               2,                           // the number of arguments 
+                               syx_small_integer_new (41),   // first argument 
+                               syx_small_integer_new (22)); 
+ 
+   /* enter the context in the created process */ 
+   syx_interp_enter_context (process, context); 
+ 
+   /* execute the process in blocking mode */ 
+   syx_process_execute_blocking (process); 
+ 
+   /* fetch the last returned object (an instance variable of Process) */ 
+   result = SYX_PROCESS_RETURNED_OBJECT (process); 
+ 
+   printf ("The result is %d\n", SYX_SMALL_INTEGER (result)); 
+ 
+   /* cleanup Syx */ 
+   syx_quit (); 
+   
+   return 0; 
+ }
+ </code>
+ 
+
+ 
+ Smalltalk YX uses its own scheduler with its own threads (called processes). Each method or block being executed runs respectively into a <c MethodContext> or <c BlockContext> inside a <c Process>. This is why we need that way of doing things, and the reason for which you can save the entire state of the interpreter in the image.
+ 
+
+ 
+ Compile <file add.c/> in the usual way and you see the result:
+ <pre>
+ $ gcc -o add add.c -lsyx -Wall
+ $ ./add
+ The result of the sum is: 63
+ $
+ </pre>
+ 
+ <next "CALL FROM SYX INTO YOUR C APPLICATION">
+ </item>
+
+ <item "Call from Syx into your C application">
+ 
+ Smalltalk YX is also able to do the inverse thing as above very easily. There're several methods to call C from Smalltalk:
+ <ul>
+ <li>Use standard primitives, which are available into the interpreter for doing basic operations</li>
+ <li>Use a plugin </li>
+ </ul>
+ 
+
+ 
+ The second is what we need to extend Syx with external libraries. You can either create a method with a special syntax to boost up the call or use the general purpose method <f "Smalltalk>>#plugin:call:withArguments">. In this example, we'll use <f "Smalltalk>>#call:withArguments:"> to interface directly into the main program.
+ 
+
+ 
+ The <file average.st> file is the following:
+ <code>| avgAndSum | 
+ avgAndSum := Smalltalk cCall: 'average' withArguments: #(10 20 30 40 50). 
+ ('The average is ', avgAndSum first printString) printNl. 
+ ('The sum is ', avgAndSum second printString) printNl
+ </code>
+ 
+
+ And this is the <file average.c /> file containing the average function:
+ <code>
+ #include <syx/syx.h> 
+ 
+ SYX_FUNC_PRIMITIVE(average) 
+ { 
+   syx_int32 i; 
+   syx_int32 sum = 0; 
+   SyxOop oop; 
+ 
+   /* obtain the number of arguments that has been sent */ 
+   syx_int32 args = es->message_arguments_count; 
+ 
+   /* create the array to hold both the average and the sum */ 
+   SyxOop result = syx_array_new_size (2); 
+ 
+   for (i=0; i < args; i++) 
+     { 
+       /* get the nth argument */ 
+       oop = es->message_arguments[i]; 
+       /* assert the object is a SmallInteger */ 
+       if (!SYX_IS_SMALL_INTEGER (oop)) 
+         { 
+           SYX_PRIM_FAIL; 
+         } 
+ 
+       /* get the integer value of the object and sum */ 
+       sum += SYX_SMALL_INTEGER (oop); 
+     } 
+   
+   /* put into the array the two results */ 
+   SYX_OBJECT_DATA(result)[0] = syx_small_integer_new (sum / args); 
+   SYX_OBJECT_DATA(result)[1] = syx_small_integer_new (sum); 
+   
+   SYX_PRIM_RETURN(result); 
+ } 
+ 
+ int main (int argc, char *argv[]) 
+ { 
+   /* initialize Syx */ 
+   syx_init (argc, argv, NULL); 
+   
+   /* load the default image */ 
+   syx_memory_load_image (NULL); 
+   
+   /* now file in our file in blocking mode, .i.e without scheduling the Process */ 
+   syx_file_in_blocking ("average.st"); 
+ 
+   /* cleanup Syx */ 
+   syx_quit (); 
+   
+   return 0; 
+ }
+ </code>
+ 
+
+ 
+ SYX_FUNC_PRIMITIVE is a macro to create a primitive function for Syx. We use a macro to mantain code compatibility for future versions. The <icode es> veriable is an argument of the average function, automatically defined by the macro. This variable contains all the state of the interpreter, exactly it's the <c SyxExecState> structure. Notice how the interface is pretty simple and easy to understand.
+ 
+
+ 
+ Smalltalk doesn't support multiple return values, so we need to put both the average and the sum into an array. The macro SYX_PRIM_FAIL exits from the primitive and enters a Syx method that either raises an exception or perform operations similar to the primitive that fails to emulate the same behavior in Smalltalk itself.
+ 
+
+ 
+ Compile this with the <icode -rdynamic> option to allow the dynamic loader to lookup the average function (it's not needed on Windows):
+ <pre>
+ $ gcc -o average average.c -lsyx -Wall -rdynamic
+ $ ./average
+ The average is 30
+ The sum is 150
+ $
+ </pre>
+ 
+
+ 
+ This is basically what Syx currently offers when embedded, and will be surely improved in the future.
+ 
+ <top>
+ </item>
+</items>
diff --git a/wml/doc/syntax.inc b/wml/doc/syntax.inc
index 2452a72..f4fafbe 100644
--- a/wml/doc/syntax.inc
+++ b/wml/doc/syntax.inc
@@ -1,6 +1,6 @@
# Classes
-m4_define(_Transcript, Transcript)
-m4_define(_TextCollector, TextCollector)
+m4_define(_Transcript, <c Transcript>)
+m4_define(_TextCollector, <c TextCollector>)

# Methods
m4_define(_printNl, printNl)
@@ -13,4 +13,24 @@ m4_define(_printNl, printNl)
# String
<define-tag s>
'%attributes'
+</define-tag>
+
+# Function
+<define-tag f>
+ %attributes
+</define-tag>
+
+# Class
+<define-tag c>
+ %attributes
+</define-tag>
+
+# Inline code
+<define-tag icode>
+ %attributes
+</define-tag>
+
+# Filenames
+<define-tag file>
+ %attributes
</define-tag>
\ No newline at end of file

Reply all

Reply to author

Forward

0 new messages