Lua :: The Programming Language

Lua is a powerful, fast, lightweight, embeddable scripting language.

Lua combines simple procedural syntax with powerful data description constructs based on associative arrays and extensible semantics. Lua is dynamically typed, runs by interpreting bytecode for a register-based virtual machine, and has automatic memory management with incremental garbage collection, making it ideal for configuration, scripting, and rapid prototyping.

Why choose Lua?

There are many reasons why one should use, here are some from the Lua website. You should use it because Lua:-

• is a proven, robust language
• is fast
• is portable
• is embeddable
• is powerful (but simple)
• is small
• is free

Visit the Lua website: http://www.lua.org

CouchDB 101 - 2 : Install and Get Started

It is time to get down with the CouchDB. As I work on there tutorial there a number of assumptions I am making, the platform being used.

Platform Specifications

• OS: Ubuntu 9.10 (Linux 2.6.31-20-generic #58-Ubuntu SMP Fri Mar 12 05:23:09 UTC 2010 i686 GNU/Linux)
• Apache: Apache 2 (Server version: Apache/2.2.12 (Ubuntu) | Server built:   Mar  9 2010 21:20:44)
• Shell: bash (GNU bash, version 4.0.33(1)-release (i486-pc-linux-gnu))

Installing on Ubuntu 9.10

Update source

$ sudo apt-get update

Install couchdb

$ sudo apt-get install couchdb

Install curl - curl is a command line tool for transferring data with URL syntax, supporting FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, LDAP, LDAPS, FILE, IMAP, SMTP, POP3 and RTSP.

$ sudo apt-get install curl

Testing if the CouchDB is installed and running correctly. CouchDB runs on port 5984

$ curl http://127.0.0.1:5984/

if all is okay and the CouchDB is running correctly, you should get something like

{"couchdb":"Welcome","version":"0.10.0"}

If you get some message like this

curl: (7) couldn't connect to host

then the CouchDB is nor running. Start it manual and test it again

$ sudo /etc/init.d/couchdb start

Getting Started

Now that we know our CouchDB is installed and running correctly, lets do some basic task. We will make use of the curl tool to make it all happen.

Creating a new database

Creating a database is as easy

$ curl -X PUT http://127.0.0.1:5984/your-database-name

where your-database-name is the name of your database. So for example here I will create the database with a name ostools to store open source tools I use daily.

$ curl -X PUT http://127.0.0.1:5984/ostools

on successful excutions you should get a message

{"ok":true}

To see the database created, list all the databases on your save, run

$ curl -X GET http://127.0.0.1:5984/_all_dbs

you should get

["ostools"]

Try to create another database.

$ curl -X PUT http://127.0.0.1:5984/linuxdistro

and then list databases

$ curl -X GET http://127.0.0.1:5984/_all_dbs

you should get

["linuxdistro","ostools"]

Creating, updating, and deleting database documents

Creating.CouchDB databases are schema-free, meaning that their structure is not strictly defined, and as a result you can change them on the fly as your needs require. If one tool has a graphical front-end, you include it in that ostools’s document. If another tool doesn’t have a graphical front-end, you simply don’t include it. If a tool has several dependencies, you can set the dependency field to be an array of dependencies objects—there is no need to define separate tables.

Lets create a document:-

curl -X PUT http://127.0.0.1:5984/ostools/fish -d '{}'

you should get a response similar to the following:

{"ok":true,"id":"fish","rev":"1-967a00dff5e02add41819138abb3284d"}

You’ve just created a document with the document ID of fish. The CouchDB server has automatically generated a revision number and included this in its response.

Now that your document is in the database, let’s issue a command to retrieve it from CouchDB:

$ curl -X GET http://127.0.0.1:5984/ostools/fish

You should receive a response like the following:

{"_id":"fish","_rev":"1-967a00dff5e02add41819138abb3284d"}

At this point you’re probably thinking that this tool information isn’t very useful. All it has is a unique ID and a revision number; it has no tools-related data whatsoever. So, let’s just delete this contact altogether. Deleting a document in CouchDB is quite similar to deleting a database, except you must specify the latest revision number of the document you want to delete.

curl -X DELETE http://127.0.0.1:5984/ostools/fish?rev=1-967a00dff5e02add41819138abb3284d

All going well, you should receive a response similar to the following:

{"ok":true,"id":"fish","rev":"2-eec205a9d413992850a6e32678485900"}

Passing the wrong revision number will result to "Document update conflict." error.

Now you will create a new tool with some datab for the document. A document in CouchDB is simply a JSON object, and you simply include this JSON in your
curl request using the -d flag to send it along with your HTTP request.

{
 "name":"bash",
 "type":"shell",
 "license":"GPL",
 "url":"http://www.gnu.org/software/bash/"
}

Let create the document

curl -X PUT http://127.0.0.1:5984/ostools/bash -d '{"name":"bash","type":"shell","license":"GPL","url":"http://www.gnu.org/software/bash/"}'

You should get

{"ok":true,"id":"bash","rev":"1-41406722a8966f543acbf49e06c66968"}

To get back this document from the database, use the following command:

curl -X GET http://127.0.0.1:5984/ostools/bash

And guess what your document is back

{"_id":"bash","_rev":"1-41406722a8966f543acbf49e06c66968","name":"bash","type":"shell","license":"GPL","url":"http://www.gnu.org/software/bash/"}

Create another tool can be done using an existing tools as a template. Issue the following command:

curl -X COPY http://127.0.0.1:5984/ostools/bash -H "Destination":"kigm"

Respond will be like

{"id":"kigm","rev":"1-41406722a8966f543acbf49e06c66968"}

Checking on the document kigm, you will see it has the same informations as bash. So lets update that information to reflect the new information for kigm

curl -X GET http://127.0.0.1:5984/ostools/kigm

{"_id":"kigm","_rev":"1-41406722a8966f543acbf49e06c66968","name":"bash","type":"shell","license":"GPL","url":"http://www.gnu.org"}

So lets update that information to reflect the new information for kigm

{
 "name":"kigm",
 "type":"webapp",
 "license":"GPL",
 "url":"http://wiki.github.com/eferuzi/kiGM/",
 "requires":["apache","php","mysql"],
 "developer":"Emanuel Feruzi"
}

When doing an update, you must include the revision field in your JSON document, with the revision identifier that the changes are based on, this is to prevent multiple users from making changes to the same document at the same time.

curl -X PUT http://127.0.0.1:5984/ostools/kigm -d '{"_rev":"1-41406722a8966f543acbf49e06c66968","name":"kigm", "type":"webapp", "license":"GPL", "url":"http://wiki.github.com/eferuzi/kiGM/", "requires":["apache","php","mysql"],"developer":"Emanuel Feruzi"}'

Response

{"ok":true,"id":"kigm","rev":"2-f56ac37c3805fc6058c840462ae85756"}

Let’s check it out with a GET request at any rate:

curl -X GET http://127.0.0.1:5984/ostools/kigm

{"_id":"kigm","_rev":"2-f56ac37c3805fc6058c840462ae85756","name":"kigm","type":"webapp","license":"GPL","url":"http://wiki.github.com/eferuzi/kiGM/","requires":["apache","php","mysql"],"developer":"Emanuel Feruzi"}

Now you can experiment more and share your findings with us.

Next: CouchDB 101 - 3 Creating Views

CouchDB 101 - 1: What is CouchDB?

CouchDB Discovery

It is my tradional to visit www.linuxtoday.com daily to get updated as to what is happening. So as I was scrolling, NoSQL poped up and I was interested as to what that is. As There was another aricle that really cought my attention, CouchDB basics for PHP developers. So the journey began.

What is CouchDB?

Apache CouchDB is a document-oriented database that can be queried and indexed in a MapReduce fashion using JavaScript. CouchDB also offers incremental replication with bi-directional conflict detection and resolution.

CouchDB provides a RESTful JSON API than can be accessed from any environment that allows HTTP requests. There are myriad third-party client libraries that make this even easier from your programming language of choice. CouchDB’s built in Web administration console speaks directly to the database using HTTP requests issued from your browser.

From: The CouchDB Project

Key Characteristics

Documents

A CouchDB document is an object that consists of named fields. Field values may be strings, numbers, dates, or even ordered lists and associative maps. A CouchDB database is a flat collection of these documents. Each document is identified by a unique ID.

Example

{
  "firstName": "Emanuel",
  "lastName": "Feruzi",
  "email": [
       "emanuel.feruzi@trilabs.co.tz",
       "feruzi@gmail.com"
  ],
   "web": "http://www.joelennon.ie"
} 

In the example above, the firstName, lastName and web are string values, where as email contains a list of emails addresses.

Schema-Free

Unlike SQL databases which are designed to store and report on highly structured, interrelated data, CouchDB is designed to store and report on large amounts of semi-structured, document oriented data. CouchDB greatly simplifies the development of document oriented applications, which make up the bulk of collaborative web applications.

In an SQL database, as needs evolve the schema and storage of the existing data must be updated. This often causes problems as new needs arise that simply weren’t anticipated in the initial database designs, and makes distributed “upgrades” a problem for every host that needs to go through a schema update.

With CouchDB, no schema is enforced, so new document types with new meaning can be safely added alongside the old. The view engine, using Javascript, is designed to easily handle new document types and disparate but similar documents.

Views

To address this problem of adding structure back to semi-structured data, CouchDB integrates a view model using Javascript for description. Views are the method of aggregating and reporting on the documents in a database, and are built on-demand to aggregate, join and report on database documents. Views are built dynamically and don’t affect the underlying document, you can have as many different view representations of the same data as you like.

Distributed

CouchDB is a peer based distributed database system. Any number of CouchDB hosts (servers and offline-clients) can have independent “replica copies” of the same database, where applications have full database interactivity (query, add, edit, delete). When back online or on a schedule, database changes are replicated bi-directionally.
CouchDB has built-in conflict detection and management and the replication process is incremental and fast, copying only documents and individual fields changed since the previous replication. Most applications require no special planning to take advantage of distributed updates and replication.
Unlike cumbersome attempts to bolt distributed features on top of the same legacy models and databases, it is the result of careful ground-up design, engineering and integration. The document, view, security and replication models, the special purpose query language, the efficient and robust disk layout are all carefully integrated for a reliable and efficient system.

Next: CouchDB 101 - 2: The First Encounter - Install and Get Started

Day 1: Shell Scripting From Scratch

A friend of mine at UDSM is doing a course that requires shell scripting so I agree to take time out an cover the basic of shell scripting, and you are welcome to join us. It really for beginners in shell.

Day 1: Laying the Foundation

What Is a Shell?

A shell is a program that takes commands you typed and tell the operating system to run them. The shell interprets your commands. For example, you may use the shell to enter a command to list the files in a directory, such as ls, or a command to copy a file, such as cp.

Example: ls is a command to list the content of the current folder.

$ ls
bin/    dev/         initrd.img.old@  media/  root/     sys/  vmlinuz@
boot/   etc/         lib/             mnt/    sbin/     tmp/  vmlinuz.old@
build/  home/        lib64/           opt/    selinux/  usr/
cdrom@  initrd.img@  lost+found/      proc/   srv/      var/

The $ is the shell prompt, which tells you the shell awaits your commands. ls listed all the content of the current directory, worry not we will get to these in a moment.

How does it work?

The shell looks for a program — that is, a file with execute permissions — with the name ls. The shell looks at all the directories in your command path. The shell runs the first program found that matches the name, checks if you have permission to excutes it and if you have its excutes it and then displays the results of the program to your screen, as in the second and third lines in the code example.

The command path is stored in the environment variable named PATH

$ $ echo $PATH
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:
/home/eferuzi/apps/go/bin:/home/eferuzi/apps/go/bin

A shell acts as a form of wrapper around the OS, hence the term shell.

Why Use Shells?

Unix was the first popular operating system to break free of the single-shell monopoly, which can still be seen in MS-DOS shell on Windows. In Day 2: we will cover how to break free of the single-shell monopoly on Windows.

The Unix philosophy is that one command should do one thing and do it well. So the complex commands are combination of small commands. In this context, a shell is simply another command — a command that facilitates combining other commands. The ability to combine commands allows you to create new commands, thereby adding value to your operating system.

In addition, most shells allow you to group a number of commands in a file, called a shell script. When you run the shell script file, the shell executes the commands in the script file in order.

What Kind of Shells Are There?

Since there is no monopoly on shells, you are free to run any shell you desire. That’s all well and good,but choosing a shell without knowing the alternatives isn’t very helpful. So lets look at a few main shell out there.

• The Bourne Shell - original Unix shell is known as sh, short for shell, created by Steven Bourne, and has been considered a standard part of Unix for decades.
  
• The C Shell - was so named because much of its syntax parallels that of the C programming language, and added some neat features to the Bourne shell, especially the ability to recall previous commands (and parts of previous commands) to help create future commands.
  
• The Korn Shell - like the C shell but also backward compatible with the older Bourne shell syntax.
  
• Bash, the Bourne Again Shell - it is said "bash shell answered a clear need, a need shown by the initial success of the Korn shell". So bash offers command-line editing like the Korn shell, file-name completion like the C shell, and a host of
  other advanced features.
• Other Shells - Over the years, a number of other shells have appeared, each with a small but devoted following. These shells include ash, zsh, and rc. Ash is the default shell and appears as sh on the Cygwin environment for Windows.
  
• 
  

Choosing a Shell

For example, when administrators assume everyone runs the Korn shell, they may set up parts of the environment that break in strange ways for users of other shells, particularly users of the C shells. So before choosing to another shell make sure it will work given the assumptions made before. Most modern shell are all pretty good anyway.

Changing Your Default Shell

The chsh command, short for change shell, allows you to change your default, or login, shell.

Syntax:

chsh username new_default_shell

Example:change user jkpaul to use csh, run the chsh command as follows

$ chsh jkpaul /bin/bash

Note that you need to enter the full path to the shell. You may required to type you password for security reasons.The new login shell will be available for use the next time you log in.

That is it for day one, so now we are ready to get into using shell.

NEXT: Day 2: Running Shell and Commands

Google's Go - a systems programming language

November 10, Google release it's  new systems programming language called Go.  According to the website http://golang.org Go has the following outstanding features:-

• simple in term of programming syntax, less typing
• fast  compilers produce fast code fast. Typical Go builds take a fraction of a second yet the resulting programs run nearly as quickly as comparable C or C++ code.
• safe in type safe and memory safe. Go has pointers but no pointer arithmetic. For random access, use slices, which know their limits.
• concurrent is a core part of the language. Go promotes writing systems and servers as sets of lightweight communicating processes, called goroutines, with strong support from the language. Run thousands of goroutines if you want—and say good-bye to stack overflows.
• fun to work with. Go has fast builds, clean syntax, garbage collection, methods for any type, and run-time reflection. It feels like a dynamic language but has the speed and safety of a static language. It's a joy to use
• open source, Go is realised under the BSD licence.

After watching a video on Google TechTalk by one of the archtechts of the language, I thought of giving a try. I have installed it on my Ubuntu, with no difficulty at all, and have done a few example. I have not done anything worth showing, but during the course I will blog more about it.

Visit their site,http://golang.org, and see if you can make use of this language.

Introduction to TDD with PHPUnit

What is TDD?

Test Drive Development [TDD] is an approach to development which combines test-first development where you write a test before you write just enough production code to fulfill that test and refactoring. So basically you first decide the functions or sections of your code you want to test. Then write test for these functions for different scenarios with expected values. Then write the implement the functions while checking if they meet the different scenarios you captured in the tests, if not refactoring is done till all tests have passed.

Why use TDD?

• by focusing on the different test cases first, developer(s) focuses on the functionality more than the implementation
• it allows the developer to focus on a small section of the implementations at a time till its working as expected
• can lead to more modularized, flexible, and extensible code
• no more code is written than necessary to pass a failing test case, automated tests tend to cover every code path
• while it is true that more code is required with TDD than without TDD because of the unit test code, total code implementation time is typically shorter

TDD Example with PHP

There are many ways in which one can implement a TDD. In this example, we will create a simple calculator with the four basic operations that is (add, subtract, multiply and divide).
But after looking around and looking back to my exprience, it looks like there is one way that most developers agree on:-

1. design your class/API
2. create a test suite
3. run the test, and in this case all tests should fail
4. implement the class
5. run the test, an this time some test will pass and some will fail
6. fix failures or errors
7. repeat 5 and 6 till all tests have passed

Download Source Code

Designing the class/API

This basically mean designing the skeleton of the class, so the class body with its functions signatures without the actually implementation

/* === calculator.php === */
class Calculator{
/**
* Constructor
* NOTE: if you are using function __constructor() can also be used for older version of PHP
* @return unknown_type
*/
function Calculator(){

}

/**
* add two numbers (a + b)
* @param $a an integer
* @param $b an integer
* @return a + b or null otherwise
*/
function add($a, $b){

}

/**
* subtact b from a numbers (a - b)
* @param $a an integer
* @param $b an integer
* @return a - b or null otherwise
*/
function subtract($a, $b){

}

/**
* multipy a and b numbers (a x b)
* @param $a an integer
* @param $b an integer
* @return a x b or null otherwise
*/
function  multiply($a, $b){

}

/**
* divide a by b numbers (a / b)
* @param $a an integer
* @param $b an integer
* @return a / b or null otherwise
*/
function  multiply($a, $b){

}
}

Creating the test class

To test a function there is two (or more depending on the test used) things that are  needed, value returned by the function and the values expected. Then using a once of the many assert functions to establish if the test has passed or not. Look at the comments on the code.

/* === calculatortest.php === */
require_once 'calculator.php';
require_once 'PHPUnit.php';

class CalculatorTest extends PHPUnit_TestCase{
 /**
  * Constructor
  * NOTE: if you are using function __constructor() can also be used for older version of PHP
  * @return unknown_type
  */
 var $calc;

 function CalculatorTest($name){
  $this->PHPUnit_TestCase($name);
 }

 /**
  * Used to set up and default values
  *
  * (non-PHPdoc)
  * @see PHPUnit/PHPUnit_TestCase#setUp()
  */
 function setUp(){
  // creating the Calculator object
  $this->calc = new Calculator();
 }

 /**
  * Used to destroy values that where set in the setUp()
  *
  * (non-PHPdoc)
  * @see PHPUnit/PHPUnit_TestCase#tearDown()
  */
 function tearDown(){
  // destroying the  calculator object 
  unset($this->calc);
 }

 /**
  * Testing add two numbers (a + b)
  */
 function testAdd(){
  $actual = $this->calc->add(2,3);
  $expected = 5;
  //checking if value returned value is what we expected
  $this->assertEquals($expected, $actual);
 }

 /**
  * Testing subtact b from a numbers (a - b)
  */
 function testSubtract(){
  $actual = $this->calc->subtract(5,2);
  $expected = 3;
  //checking if value returned value is what we expected
  $this->assertEquals($expected, $actual);
 }

 /**
  * Testing multipy a and b numbers (a x b)
  */
 function  testMultiply(){
  $actual = $this->calc->multiply(5,2);
  $expected = 10;
  //checking if value returned value is what we expected
  $this->assertEquals($expected, $actual);
 }

 /**
  * Testing divide a by b numbers where b=0
  */
 function  testDivideByZero(){
  $actual = $this->calc->divide(3,0);
  $expected = NULL;
  //checking if value returned value is what we expected
  $this->assertEquals($expected, $actual);
 }

 /**
  * Testing divide a by b numbers (a / b)
  */
 function  testDivide(){
  $actual = $this->calc->divide(10,2);
  $expected = 5;
  //checking if value returned value is what we expected
  $this->assertEquals($expected, $actual);
 }
}

Write the Testing

Now we need to write the code to actual run the code

/* ==== test.php ==== */

require_once 'calculatortest.php';
require_once 'PHPUnit.php';

/* the value passed duing the instantiating must be the name of the test class */
$suite  = new PHPUnit_TestSuite("CalculatorTest");
/*rin the test*/
$result = PHPUnit::run($suite);
/*dispay the result */
echo $result->toString();

Running the test

Start up your terminal and run the test.php with php or if run it through your apache and view the result on the browser

eferuzi@feruzi /v/w/phpunit> php5 test.php
TestCase CalculatorTest->testDivideByZero() passed
TestCase CalculatorTest->testAdd() failed: expected 5, actual  in /var/www/phpunit/calculatortest.php:56
TestCase CalculatorTest->testSubtract() failed: expected 3, actual  in /var/www/phpunit/calculatortest.php:66
TestCase CalculatorTest->testMultiply() failed: expected 10, actual  in /var/www/phpunit/calculatortest.php:76
TestCase CalculatorTest->testDivide() failed: expected 5, actual  in /var/www/phpunit/calculatortest.php:96

As you can see we have one passing because the functions are not returning anything at the moment and that test checks if NULL is returned.

Implementations of the Calculator

So now we add implementation into the functions in the Calculator class

/* === calculatortest.php === */


require_once 'calculator.php';
require_once 'PHPUnit.php';

class CalculatorTest extends PHPUnit_TestCase{
 /**
  * Constructor
  * NOTE: if you are using function __constructor() can also be used for older version of PHP
  * @return unknown_type
  */
 var $calc;

 function CalculatorTest($name){
  $this->PHPUnit_TestCase($name);
 }

 /**
  * Used to set up and default values
  *
  * (non-PHPdoc)
  * @see PHPUnit/PHPUnit_TestCase#setUp()
  */
 function setUp(){
  // creating the Calculator object
  $this->calc = new Calculator();
 }

 /**
  * Used to destroy values that where set in the setUp()
  *
  * (non-PHPdoc)
  * @see PHPUnit/PHPUnit_TestCase#tearDown()
  */
 function tearDown(){
  // destroying the  calculator object
  unset($this->calc);
 }

 /**
  * Testing add two numbers (a + b)
  */
 function testAdd(){
  $actual = $this->calc->add(2,3);
  $expected = 5;
  //checking if value returned value is what we expected
  $this->assertEquals($expected, $actual);
 }

 /**
  * Testing the add method with wrong or none numerical input
  */
 function testAddInvalidValues(){
  $actual = $this->calc->add('ugali',3);
  //checking if value returned value is what we expected
  $this->assertNull($actual);
 }


 /**
  * Testing subtact b from a numbers (a - b)
  */
 function testSubtract(){
  $actual = $this->calc->subtract(5,2);
  $expected = 3;
  //checking if value returned value is what we expected
  $this->assertEquals($expected, $actual);
 }

 /**
  * Testing multipy a and b numbers (a x b)
  */
 function  testMultiply(){
  $actual = $this->calc->multiply(5,2);
  $expected = 10;
  //checking if value returned value is what we expected
  $this->assertEquals($expected, $actual);
 }

 /**
  * Testing divide a by b numbers where b=0
  */
 function  testDivideByZero(){
  $actual = $this->calc->divide(3,0);
  $expected = NULL;
  //checking if value returned value is what we expected
  $this->assertEquals($expected, $actual);
 }

 /**
  * Testing divide a by b numbers (a / b)
  */
 function  testDivide(){
  $actual = $this->calc->divide(10,2);
  $expected = 5;
  //checking if value returned value is what we expected
  $this->assertEquals($expected, $actual);
 }

Re-run the test

Re-run the test again and this time you should see some more passes if not refactor your code till you get all passes.

eferuzi@feruzi /v/w/phpunit> php5 test.php
TestCase CalculatorTest->testAdd() passed
TestCase CalculatorTest->testAddInvalidValues() passed
TestCase CalculatorTest->testSubtract() passed
TestCase CalculatorTest->testMultiply() passed
TestCase CalculatorTest->testDivideByZero() passed
TestCase CalculatorTest->testDivide() passed

Download Source Code

More information:-

• TDD:
• http://en.wikipedia.org/wiki/Test-driven_development
• http://www.extremeprogramming.org/rules.html
• PHPUnit:
• http://www.phpunit.de/

Do not hesitate to ask me questions.