Improving documentation

README.md

@@ -2,3 +2,47 @@ C+Perl
 ======
 
 The minimal Perl Wrapper for C++
+This Library makes possible to call Perl functions (sub) from a C++ program in a very easy way.
+
+Code Usage 
+----------
+*See docs/example.cpp for a working code example.*
+
+If you have a Perl function in a file "example.pl" you want to use in your C++ program, first you will do:
+
+	PerlInterface interface("example.pl");
+
+Now you have your interface with Perl, just call your function by its name as it appears in the Perl file:
+
+	interface.sub("superFuction");
+
+This is it, easy as that!
+Now suppose you want to give this function some parameters:
+
+	interface << 2 << 3;
+	int result = interface.sub("sum").get();
+
+This passes the parameters to the interface and call it with them. Note that we use get() to get the result, this is important and will be clear in the next examples.
+
+Perl allow us to return multiple values from a function, of course we may keep doing it:
+
+	interface << 5 << 6 << 9;
+	PerlStack ret = interface.sub("squareAll");
+	int results[] = {ret.get(), ret.get(), ret.get()};//there is a smarter way of doing it, specially when you don't know how many parameters you will get
+
+See what get() does? It gets the next value from a PerlStack, the sub() method returns a PerlStack, when you know there is only one return from your Perl function or simply don't care about the others, you don't need to keep the PerlStack, you may simply use get() and store only the value you want. This is what we did in the previous example.
+
+In fact the PerlInterface is also a PerlStack, that is why you can pass the parameters directly to the interface, an alternative way to do it is to create a PerlStack and pass it to the sub method, check it out:
+
+	PerlStack awesomeStack = interface.newStack();
+	awesomeStack << 2 << 3;
+	int result = interface.sub("sum", awesomeStack).get();
+
+Uhm.. If the sub() returns a PerlStack and also accepts one as parameter, we may pass the output of one function to an other:
+
+	interface.sub("function1", interface.sub("function2"));
+
+
+
+
+

docs/Makefile

@@ -33,15 +33,16 @@ HEADER=CPlusPerl.h
 
 EXP=example.cpp
 EXP_OBJS=$(subst .cpp,.o,$(EXP))
-EXP_EXEC= example1
+EXP_EXEC= example
 
 
 .cpp.o:
 	$(CXX) $(CXXFLAGS) -c $<
 
 all: $(LIB) $(HEADER) $(EXP_EXEC)
 	@echo "=================================================================================================="
-	@echo "=== Go to the docs directory to execute the example1, the source code is also available there. ==="
+	@echo "=== Go to the docs directory to execute the example, the source code is also available there. ==="
+	@echo "=================================================================================================="
 
 $(EXP_EXEC): $(EXP_OBJS)
 	$(LD) -o $(EXP_EXEC) $(EXP_OBJS) $(LIB) $(LDFLAGS)

docs/example.cpp

@@ -9,52 +9,52 @@ void teste();
 
 int main(int argc, char **argv)
 {
-	PerlInterface interface("example1Perl1.pl");//Iniciando o arquivo perl
+	PerlInterface interface("example1Perl1.pl");//Starting the Perl in Interpreter in this Perl File
 
-	cout << "Funcao 1 (sem parametros e sem valor de retorno)" << endl;
+	cout << "Function 1 (no parameters and no return)" << endl;
 	interface.sub("showtime");
 
-	cout << endl << "Funcao 2 (com parametros e com 1 retorno)" << endl;
+	cout << endl << "Function 2 (with parameters and one return)" << endl;
 	interface  << 2 << 3;
-	int resultado = interface.sub("soma").get();
-	cout << "Resultado: " << resultado << endl << endl;
+	int result = interface.sub("sum").get();
+	cout << "Result: " << result << endl << endl;
 
-	cout << "Funcao 3 (Retornando multiplos parametros)" << endl;
+	cout << "Function 3 (Returning multiple values)" << endl;
 	interface << 5 << 6 << 9;
 	PerlStack ret = interface.sub("squareAll");
-	int resultados[] = {ret.get(), ret.get(), ret.get()};
-	cout << "Resultados: " << resultados[0] << ", " << resultados[1] << ", " << resultados[2] << endl << endl;
+	int results[] = {ret.get(), ret.get(), ret.get()};
+	cout << "Results: " << results[0] << ", " << results[1] << ", " << results[2] << endl << endl;
 
-	cout << "Funcao 4 (Passando saida de uma funcao como argumento de outra)" << endl;
+	cout << "Function 4 (Passing the return of a function to an other)" << endl;
 	interface << 2 << 4 << 9;
 	PerlStack stackToAdd = interface.newStack();
-	stackToAdd << 1 << 2 << "lalala" << 3.14159;
+	stackToAdd << 1 << 2 << "C+Perl is awesome!" << 3.14159;
 	interface.sub("distArg", stackToAdd << interface.sub("squareAll"));
 
 
 
-	cout << endl << endl << "Agora usando um outro arquivo" << endl;
+	cout << endl << endl << "Now using an other file" << endl;
 
-	PerlInterface interface2("example1Perl2.pl");
+	PerlInterface interface2("example1Perl2.pl");//Look that we need a different PerlInterface when using a different file
 
-	cout << "Funcao 1 (sem parametros e sem valor de retorno)" << endl;
+	cout << "Function 1 (no parameters and no return)" << endl;
 	interface2.sub("showtime");
 
-	cout << endl << "Funcao 2 (com parametros e com 1 retorno)" << endl;
+	cout << endl << "Function 2 (with parameters and one return)" << endl;
 	interface2  << 2 << 3;
-	resultado = interface2.sub("soma").get();
-	cout << "Resultado: " << resultado << endl << endl;
+	result = interface2.sub("sum").get();
+	cout << "Result: " << result << endl << endl;
 
-	cout << "Funcao 3 (Retornando multiplos parametros)" << endl;
+	cout << "Function 3 (Returning multiple values)" << endl;
 	interface2 << 5 << 6 << 9;
 	PerlStack ret2 = interface2.sub("squareAll");
-	int resultados2[] = {ret2.get(), ret2.get(), ret2.get()};
-	cout << "Resultados: " << resultados2[0] << ", " << resultados2[1] << ", " << resultados2[2] << endl << endl;
+	int results2[] = {ret2.get(), ret2.get(), ret2.get()};
+	cout << "Results: " << results2[0] << ", " << results2[1] << ", " << results2[2] << endl << endl;
 
-	cout << "Funcao 4 (Passando saida de uma funcao como argumento de outra)" << endl;
+	cout << "Function 4 (Passing the return of a function to an other)" << endl;
 	interface2 << 2 << 4 << 9;
 	interface2.sub("distArg", interface2.sub("squareAll"));
 
-	cout << "Fim" << endl;
+	cout << "The end" << endl;
 	return 0;
 }

docs/example1Perl1.pl

@@ -4,7 +4,7 @@ sub showtime {
   print "Time: ", time, "\n";
 }
 
-sub soma {
+sub sum {
   return $_[0] + $_[1];
 }
 

docs/example1Perl2.pl

@@ -1,10 +1,10 @@
 
 sub showtime {
-  print "Tempo 2: ", time, "\n";
+  print "Time 2: ", time, "\n";
 }
 
-sub soma {
-  print "(Soma 2) $_[0] + $_[1]\n";
+sub sum {
+  print "(Sum 2) $_[0] + $_[1]\n";
   return $_[0] + $_[1];
 }