The Pawn language

Skip to main content (skip navigation menu)
Letterhead logo






pawn

 
This product is made in the EU

Pawn's icon

An embedded scripting language

pawn is a simple, typeless, 32-bit extension language with a C-like syntax. A pawn "source" program is compiled to a binary file for optimal execution speed. The pawn compiler outputs P-code (or bytecode) that subsequently runs on an abstract machine. Execution speed, stability, simplicity and a small footprint were essential design criteria for both the language and the abstract machine.

At a glance


Current version 4.0.4733 (2012-06-22)
View the history of recent changes.
Downloads Microsoft Windows: a self-extracting setup.
Linux & Unix: "autopackage" archive.
More downloads: ZIP files/tar-balls, pre-compiled binaries, auxiliary files, ....
License Apache License 2.0, plus an exception clause to explicitly permit static linking of the library to commercial applications.
Installation Microsoft Windows: download the self-extracting setup and run it.
Linux: download the installation archive, extract the "autopackage" file (a shell script) and run it.
All other operating systems: download a source archive as a compressed tar-ball or as a ZIP file and read the README.TXT file after unpacking. (See also the "Getting started" section below).
Support pawn is hosted on Google Code. The project has a discussion board and an issue tracker.
For support on a commercial basis, please contact us by e-mail. We can build speed-optimized versions of the abstract machine (also known as "virtual machine" or VM) or JITs, add special language constructs, port the product to different microcontrollers, and write native function libraries for particular tasks.
Documentation All documentation is in "Adobe Acrobat" format (PDF), readable with Adobe Acrobat and Ghostscript. The main two books are the "Language Guide" and the "Implementer's Guide". Several extension modules are documented separately.
Screen shots pawn is a compiler and an abstract machine. The compiler is a console utility (i.e. you run it in a "DOS box" or a terminal), and the abstract machine is basically a library. As such, there isn't really something like a representative a screen shot. I have tried a few anyway...
Click on the pictures for a detailed view.

Terminal emulation

Terminal emulation under Windows, showing Unicode support

XML documentation

Documentation (XML) extracted from the source code comments and compiler reports

MP3 Controller

The "H0420" Programmable MP3 Controller uses pawn for scripting

Console debugger

pawn console debugger

Quincy IDE

The Quincy IDE with editor and debugger, adapted for pawn

Pawn GTK calculator

pawn calculator with a user interface in GTK, via gkt-server

Projects A list of projects and products that use pawn as a scripting language is on the page Where is pawn used?.

For any information not in this list, please browse through this page. Hopefully you will find what you are looking for.

section separator

Introduction

An introduction to the pawn language and abstract machine from a programmer's perspective was published in the October 1999 issue of Dr. Dobb's Journal —but at the time, the language was called Small. More verbose than the article, and more appropriate for non-expert programmers, is the manual. The manual contains a brief (tutorial) overview of the language, a language reference, programming notes on the abstract machine, casual notes about the why and how of many language features, and reference material.

Why pawn now that there is Java, Lua, REXX, and countless others? Well, when I needed a language toolkit whose executable code can be embedded in resource files or animation file formats, that had a good interface to native functions, that added little overhead to the main application and could run on platforms and microcontrollers with (very) little RAM, and that was pretty fast, I could not really find an existing toolkit that fitted my needs. See also a list of language features.

Unlike many languages, pawn is not intended to write complete full-scale applications in. pawn's purpose is to script the functionality provided by an application or by a device. It is in purpose similar to Microsoft's "Visual Basic for Applications", only quicker and smaller (and without the installation hassle).

pawn has been publicly available since 1998, and it has been steadily improving: more error checking, several bugs slashed, new features, and an increase in performance. There are still regular updates and patches: to fix bugs, to add features, or simply to enhance the ease-of-use.

A couple of other points are worth mentioning:

section separator
Pawn's icon

Getting started


The first question is: what do you need? If you are using Microsoft Windows, download the pawn toolkit as a self-extracting setup file; this gives everything that you need to get started:

Linux users get essentially the same files when installing the "autopackage" archive, but with a different (reduced functionality) version of the Quincy IDE. Users of other operating systems should download either the "pawnkit-xxx.zip" or the "pawnkit-xxx.tgz" files (where -xxx stands for a version number of the toolkit; see the "pawn toolkit" archives), which contain the source code only. The difference between the "ZIP" file and the "TGZ" file is, apart from the different archiving tool used, that the source file in the ZIP file has DOS/Windows line endings (CR/LF) and the "TGZ" file has Unix line endings (LF only). When "unpacking" these archives, make sure that the directory structure in the ZIP/TGZ files is retained.

The "README.TXT" file in the source code archives contains a section for building binaries from the source code, by using the CMake makefile generator. You should also download the two documentation files "Language Guide" and "Implementer's guide". The "Implementers Guide" will inform you about the options and configurations that you have in building the binaries, and the "Language guide" will teach you the pawn language. If you are new to programming, the thin guide "A Gentle Introduction to Programming" aims at helping you with the first steps.

Assuming that you have obtained (somehow) an executable version of the pawn compiler and the pawn run-time, you should put it in a directory. However, the pawn compiler also needs to locate "include files". On many operating systems, the pawn compiler is able to automatically read these header files from the directory "include" that is below the directory that the compiler is in itself. Thus, if the pawn compiler is in directory "C:\WhatEver\Pawn", I suggest that you also create directory "C:\WhatEver\Pawn\include" and copy the ".inc" files there. If your operating system is not compatible with Win32 or Linux, the pawn compiler may not know how to locate the "include" directory and you have to specify it yourself with the "-i" command line option (when running the compiler).

That behind your back, locate one of the example scripts (e.g. "hello.p") and compile it with:

pawncc hello
This should produce "hello.amx", which you can then run with:
pawnrun hello

Many applications that use pawn, run the pawn compiler as a child process; that is, the pawn compiler is often a separate, self-contained program. The abstract machine, however, is almost never a separate process: typically you want the abstract machine to be integrated in the application so that scripts can call into the application. In other words, you might be using "pawncc" as is, but you won't be using "pawnrun" as is. This is why pawnrun is kept short and dumb, "pawnrun" is a program that is mostly developed in the pawn manual to show you what you should do at a minimum to embed pawn into a program.

section separator
Pawn's icon

Support


Please visit the discussion board for any questions that you have about pawn. If you are using pawn as part of some product, you may get more response if you ask your questions on the forum of that product. (See also the page Where is pawn used?).

pawn is a free product that is maintained primarily in spare time. We make no money from the product, neither from the software, nor from the manual, nor from support. I therefore need to ask you for patience when we are slow in responding to your questions or. Obviously, if you really need support or a custom version of pawn, you can always hire us.

section separator
Pawn's icon

Downloads


If you want to find out more, you will need to download at least one or both manuals. The book "The Language" contains the syntax of the pawn language, and "Implementer's Guide" covers the interface functions of the abstract machine and various reference materials. If you are new to programming, first read the "Introduction to Programming" booklet (just 12 pages). You need to be able to view or print Adobe Acrobat ("PDF") files for example via Acrobat Reader.

Full install, Microsoft Windows
  • setup file icon The pawn toolkit for Microsoft Windows in a self-extracting setup, version 4.0.4733 (4.3 MiB; 2012-06-22).
    This setup puts the tools in the appropriate directories.
    It includes precompiled binaries, the Quincy IDE, all documentation, all source code, codepage files and the AMX DLLs.
    Macintosh-specific project files and the JIT for Windows CE are not included in this self-extracting setup; download the appropriate source code archive (in a .TGZ file) instead.
Full install, Linux
  • setup file icon The pawn toolkit for Linux as an autopackage archive, version 4.0.4733 (3.3 MiB; 2012-06-22).
    This setup puts the tools in the appropriate directories. See the Instructions for installing an autopackage file if you are new to autopackage distributions. It includes precompiled binaries, all documentation and all source code.
    Macintosh-specific project files (and files specific for Microsoft Windows) are not included in this package; download the appropriate source code archive (in a .TGZ file) instead.
Source code archives
Documentation

Nearly all documentation is in print Adobe Acrobat ("PDF") format. You can open PDF files with GhostScript or with the Acrobat Reader. With the exception of the application note on the debugger interface (by Greg Garner), all documents are also contained in self-extracting setup for Microsoft Windows.

  • PDF file icon A Gentle introduction to Programming (324 KiB; 2011-08-01)
    A very tiny booklet (just 11 pages) introducing the craft of programming to those who are new to it.
  • PDF file icon The pawn booklet 1. Language Guide (1.3 MiB; 2011-08-01)
    The syntax and semantics of the scripting language. The manual is updated for version 3.3 of the toolkit.
  • PDF file icon The pawn booklet 2. Implementer's Guide (860 KiB; 2011-08-01)
    Compiling instructions; embedding the pawn toolkit in your application; opcode reference. The manual is updated for version 3.3 of the toolkit.
  • PDF file icon The Application Note Fixed Point Support Library (133 KiB; 2011-08-01)
    Documentation for the optional extension module that adds fixed point decimal arithmetic to the pawn language. The source code for this library is in one of the source code archives (see above) and in the self-extracting setup for Microsoft Windows.
  • PDF file icon The Application Note FLoating Point Support Library (127 KiB; 2011-08-01)
    Documentation for the optional extension module that adds floating point arithmetic to the pawn language. The source code for this library is in one of the source code archives (see above) and in the self-extracting setup for Microsoft Windows.
  • PDF file icon The Application Note File I/O Support Library (195 KiB; 2011-08-01)
    Documentation for the optional extension module that adds general purpose support for reading and writing text and binary files. The library supports plain text files and UTF-8 encoded files. The source code for this library is in one of the source code archives (see above) and in the self-extracting setup for Microsoft Windows.
  • PDF file icon The Application Note Datagram Exchange Module (101 KiB; 2011-08-01)
    Documentation for the optional extension module that allows messages or packets to be exchanged over a network link, using the UDP protocol (from the TCP/IP protocol suite). The source code for this library is in one of the source code archives (see above) and in the self-extracting setup for Microsoft Windows.
  • PDF file icon The Application Note Process control and Foreign Function Interface (98 KiB; 2011-08-01)
    Documentation for the optional extension module that provides the ability to launch and control external applications and to call into DLL and shared libraries. The source code for this library is in one of the source code archives (see above) and in the self-extracting setup for Microsoft Windows.
  • PDF file icon The Application Note String Manipulation Library (132 KiB; 2011-08-01)
    Documentation for the optional extension module that adds general purpose string manipulation functions, for both packed and unpacked strings (or mixed). The source code for this library is in one of the source code archives (see above) and in the self-extracting setup for Microsoft Windows.
  • PDF file icon The Application Note Time Functions Library (102 KiB; 2011-08-01)
    Documentation for the optional extension module for time/date functions and for time events. The source code for this library is in one of the source code archives (see above) and in the self-extracting setup for Microsoft Windows.
  • ZIP file icon An application note that describes the debug hook interface for the Small language is also available. This document relates to version 1.8.4 of the toolkit; the debug hook and the debug information in the binary files has changed in pawn. This paper was also written by Greg Garner and it is provided in Microsoft Word and ASCII formats. (1999-11-11)
Regression test
  • ZIP file icon A regression test suite for the pawn compiler and the abstract machine is available (31 KiB; 2011-08-01).
    The test suite requires a "REXX" interpreter to run. The test script works on Microsoft Windows systems, and it probably works on other systems with only minor modifications (I am using the Regina REXX interpreter, which runs on many platforms). You may want to run your compiler/abstract machine through this if you have modified anything. There are now 100 tests in the regression test suite, each of which checks for a particular idiom.
section separator
Pawn's icon

Exception clause to the Apache License version 2.0


As a special exception to the Apache License 2.0 (and referring to the definitions in Section 1 of that license), you may link, statically or dynamically, the "Work" to other modules to produce an executable file containing portions of the "Work", and distribute that executable file in "Object" form under the terms of your choice, without any of the additional requirements listed in Section 4 of the Apache License 2.0. This exception applies only to redistributions in "Object" form (not "Source" form) and only if no modifications have been made to the "Work".

section separator
Pawn's icon

Help requested


  1. As I said, my first priority is getting the bugs out. If you come across bad code generation problems or other errors, send me the shortest program that illustrates the bug. I will be grateful for it.
  2. pawn is reported to run under Microsoft DOS, all versions of Microsoft Windows (including Windows CE), Linux, MacOS, FreeBSD, XBox, PlayStation, FreeRTOS (on an ARM7-architecture), and µC/OS-II. If you have been able to port pawn to other environments, please send me the changes. Others will be grateful for it.
  3. The documentation is getting better, I think, but I am not a good critic of my own work. Comments on my writing (especially errors and obscure paragraphs) are appreciated.

To contact me, send e-mail to thiadmer @ compuphase.com. Note, however, that I am regularly abroad and sometimes need 8 days to answer an e-mail.