Jazzyk SDK

To support development of 3^rd party concrete application domain KR modules, we provide a software development kit (Jazzyk SDK). It includes a sample module which you can instantly compile, install and use on you system with installed Jazzyk interpreter. Apart from the C++ implementation of the module template, it comes together with a fully functional template for GNU Autotools chain which can serve as a basis for your own module development.

To start, simply download the SDK package from the File Repository, unpack it and follow the instructions in the “module.cpp” source file.

To develop a new Jazzyk KR module, you basically need to add flesh to the query and update methods of the KR module class derived from AbstractKRModule class provided by the include file “jazzyk.hpp” which is installed to your system by the standard install procedure (however not on Win32 platform!).

It is very easy to add a new module. For an example, you might want to consult the source code of the provided jzconsole package. We did as much as we could to make a KR module development easy for Jazzyk users.

The SDK package is a set of raw GNU Autotools configuration files. In order to build these, simply run the “autogen.sh” script. The complete compilation of the package then consists of the following sequence of commands:

    $ ./autogen.sh
    $ ./configure
    $ make

To demonstrate the easiness of Jazzyk KR module development, here we list the content of the template class in “module.cpp” file:

/*
 ******************************************************************************
 * Jazzyk - Modular BDI Agent Architecture programming language interpreter
 * Copyright (C) 2006, 2007  Peter Novak 
 * 
 * Jazzyk 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 program; if not, write to the Free Software Foundation, Inc., 59 Temple
 * Place, Suite 330, Boston, MA  02111-1307  USA
 ******************************************************************************
*/

/*
 * $Id: module.cpp 256 2008-02-23 23:34:04Z pno $
 * $Author: pno $
 * $Description: Template file for a Jazzyk KR module development (SDK).$
 * 
 * $HeadURL: http://rb02.in.tu-clausthal.de/svn/jazzyk/trunk/sdk/module.cpp $
 * $Revision: 256 $
 * 
*/

/*!
 * This is a template example file for development of a custom knowledge
 * representation module for the Jazzyk interpreter.
 *
 * The full documentation on how to create new KR modules can be found in the
 * official Jazzyk documenation to the jazzyk.hpp file.
 *
 * For more documentation, please check the README file of the Jazzyk SDK.
 *
 */

/*
 * If you get a compile error here because of missing jazzyk.hpp header, either
 * 1) your compiler is misconfigured and does not find the correct header where
 * it expects (by default /usr/local/include/), or 2) you did not install the
 * package Jazzyk (Jazzyk interpreter) correctly.
 */
#include 


//! Knowledge representation module implementation class
/*!
 * In order to create a new module, simply create a subclass of
 * jazzyk::AbstractKRModule, implement required virtuals, implement yor
 * specialized query/update interface and finally register this interface using
 * macros of the JZMODULE_MANIFEST family.
 *
 * NOTE:
 * 	Methods' definitions are implemented in the body class for brevity
 * 	only. Normally, you should put them into a separate .cpp implementation
 * 	file, of course.
 */

#include 

class CMyModule :
	public jazzyk::AbstractKRModule
{
public:
	
	//! KR module initialization callback
	/*!
	 * The routine is invoked right after the module is loaded before the
	 * Jazzyk program interpretation itself.
	 *
	 * The argument is a KR module specific code to be executed on the
	 * initialize notification specified in the Jazzyk program.
	 */
	virtual jazzyk::EKRModuleError initialize(const std::string& szCode)
	{ 
		/* Put your initialization code here. */

		std::cout << "\"" << szCode << "\"" << std::endl;

		return jazzyk::OK;
	}

	//! KR module finalization callback
	/*!
	 * The routine is invoked right before the module is about to be
	 * unloaded. 
	 *
	 * The argument is a KR module specific code to be executed on the
	 * finalize notification specified in the Jazzyk program.
	 *
	 * Note:
	 * 	In the case of a non normal interpreter exit, the interpreter
	 * 	does it's best to call finalize on all its modules, however it
	 * 	might happen that it won't be called.
	 */
	virtual jazzyk::EKRModuleError finalize(const std::string& szCode)
	{
		/* Put your finalization code here. */

		std::cout << "\"" << szCode << "\"" << std::endl;

		return jazzyk::OK;
	}

	//! KR module cycle callback
	/*!
	 * The routine is invoked after each completed interpreter deliberation
	 * cycle.
	 *
	 * The argument is a KR module specific code to be executed on the
	 * cycle notification specified in the Jazzyk program.
	 */
	virtual jazzyk::EKRModuleError cycle(const std::string& szCode)
	{ 
		/* Put your cycle notification code here. */

		std::cout << "\"" << szCode << "\"" << std::endl;

		return jazzyk::OK;
	}

	//! Custom KR module query operation
	/*!
	 * When the module is queried, a code block (query formula) [first
	 * argument] is passed to it together with the current substitutions of
	 * the relevant variables [second argument]. The query routine is
	 * supposed to return a query formula execution result [fifth argument]
	 * and a new variable substitution for the query-formula-relevant free
	 * variables [fourth argument].
	 *
	 * Remark:
	 * 	This method is normally invoked very often. Therefore
	 * 	optimization of its time complexity is important for a general
	 * 	KR module quality.
	 */
	virtual jazzyk::EKRModuleError queryImplementation(
			const std::string& szQueryCode,
			const jazzyk::TKRVarSubstitution& inSubst,
			jazzyk::TKRVarSubstitution& outSubst,
			bool& bResult)
	{
		/* 
		 * Implementation of the query interface goes here and
		 * to methods with the same signature.  
		*/

		std::cout << "\"" << szQueryCode << "\"" << std::endl;

		// Example of variable substitution handling
		if (!outSubst.empty())
		{
			std::cout 
				<< "substituting variable " 
				<< outSubst.begin()->first << std::endl;
			outSubst[outSubst.begin()->first] = "A value";
		}

		// IMPORTANT: fill in the query result
		bResult = true;

		return jazzyk::OK;
	}
	
	//! Custom KR module update operation
	/*!
	 * When finally the Jazzyk interpreter performs an update operation on
	 * a KR module, this routine is invoked. The module gets a code block
	 * to be executed (update formula) [first argument], together with a
	 * relevant variable substitution [second argument].
	 */
	virtual jazzyk::EKRModuleError updateImplementation(
			const std::string& szUpdateCode,
			const jazzyk::TKRVarSubstitution& mapSubstitution)
	{
		/* 
		 * Implementation of the update interface goes here and
		 * to methods with the same signature. 
		 */

		std::cout << "\"" << szUpdateCode << "\"" << std::endl;

		if (!mapSubstitution.empty())
		{
			std::cout 
				<< "Variable: " << mapSubstitution.begin()->first
				<< " Value: " << mapSubstitution.begin()->second 
				<< std::endl;
		}

		return jazzyk::OK;
	}
};

//! KR module query/update interface manifest
/*!
 * KR module must publish its query/update interface and so bind the custom
 * query/update routine implementations to the query/update operations used in
 * Jazzyk programs. To do so, macros of the JZMODULE_MANIFEST* family are used.
 *
 * The manifest block starts with the JZMODULE_MANIFEST_BEGIN macro with an
 * argument of the KR module implementation class. It has to be finished by the
 * JZMODULE_MANIFEST_END macro. Between the pair, query and update operations
 * are registered using REGISTER_QUERY and REGISTER_UPDATE registration macros.
 * The format of their arguments is the same: the first is the operation
 * identifier to be used in the Jazzyk programs, while the second is its
 * binding to a custom KR module query/update routine. In a basic case, a
 * module should have at least one query and one update operation.
 *
 * NOTE:
 * 	Only one manifest can be defined in the KR module! Therefore be careful
 * 	about its placement (header files are a bad candidate - the main .cpp
 * 	file is a good one).
 */
JZMODULE_MANIFEST_BEGIN(CMyModule)
	REGISTER_QUERY("query", queryImplementation)
	REGISTER_UPDATE("update", updateImplementation)
JZMODULE_MANIFEST_END