1.1 First this.
Which version does this apply to?
Always check the line 'using purebasic x.xx for windows' in the upper left corner of this page (just below the words 'PureBasic Survival Guide') to verify for the version this text applies to. PureBasic is an evolving, living language and things may (will!) change!
The Survival Guide is (in)frequently updated... whenever I feel like it :-) I will try to mark all major changes to the previous version of the Survival Guide in red. I'm bound to miss something, or make mistakes. Drop me a line if you spot them. You can also download this guide. If you're puzzled about the 'when' of some pages (the 'why' is impossible to fathom :-)) then have a look at the big number in the top right corner of this page. It's the year in which I made the most recent major change to the page.
On October 5, 2003, the user BluezNL posted the following:
I put most of my stupid mistakes together on a page, a sort of survival guide... :wink:And it's been 10 years since!
Feel the Pure Power!
PureBasic exists in different flavours and versions (Windows, Linux, Mac OS-X, Amiga). In this guide I will limit myself to PureBasic for Windows. (The Windows version is perhaps the most mature, but the Linux and Mac versions are getting better every day.)
These pages help you getting started with the Windows version of PureBasic, which is a programming language. (Duh! I bet you didn't see that one coming!). These pages started as a form of self help, then turned into a sort of tutorial / reference / snippet collection, and now have become... euh... a mess I guess :-) And they have been a mess for the last 10 years...
note that this is not an official guide, and that I am in no way
part of the official PureBasic team. All mistakes are mine (except those
made by others, of course :-)) Consider this work a tribute to the great
work AlphaSound & co did.
It's Basic, Jim. But not as we know it
No. I am not going to tell you how to program, or how to learn Basic (well, perhaps a little). I am only going to point out some things that caused me loads of problems due to misunderstandings. Some of it might be obvious to you, but not to me at the time... (Which was my prime motivation to write this guide.)
This thing called PureBasic is different... But that doesn't mean this is a bad programming language, or that basic itself is a bad programming language. It just depends what you are going to do with it. I switched over to PureBasic (or PB or Pure as it is lovingly called) when my previous language of choice GfaBasic disappeared...
PureBasic does have its own flavour though...
Don't listen to anybody who says any programming in Basic is bad, that any program in basic resembles a plate of spaghetti, and that basic is oh so slow. What counts is not the language a program is written in, but how well a program does what it is supposed to do. (And I would like to invite the sceptics to have a good look at the aspects of any modern 'Basic' language. They might be in for a surprise.)
One word of warning though: PureBasic is a procedural language, not an object oriented language.
are some user created pre-processors, and perhaps one day there will be
a little OOP (though I would not hold my breath as the developers have
said 'no' more than once). Fortunately, it is still very usable.
What it is
PureBasic? Well. A programming language. It's a kind of Basic (check WikiPedia) with it's own deviations from the standard syntax.
PureBasic costs 79 euro (in August 2008 it was 79 euro, and in April 2013 it was still 79 euro!) and can be bought here. You can use a credit card or euro cheque. Buying the official full version includes life time updates. So better be fast before the developer changes his mind regarding the license scheme!
There is also a demo version available so you can try before you buy. Go to purebasic.com for more information, download and try. The demo version has a number of limitations, of which the most obvious is the lack of WinApi support (that's any command ending on an underscore).
Don't worry. I don't get any money for this free plug. So let's hit the road and see what this baby can do...
install simply run the downloaded executable. That's it. You should be
able to install it over any older version, but I'd rather not take chances.
As it's so small, installing is a breeze, and it definitely doesn't hurt
to keep a copy or two around.
In the past I suggested the use of JaPBe, but I guess JaPBe is now a thing of the past, as the included editor (since 4.20 or so) does a fine job. The PB editor has been adopting many features of JaPBe, honoured some user requests, and now includes some functionality that was provided by thirdt party applications in the past (such as my own CodeCaddy).
Planning to do some programming using WinApi calls? Then you'll might find some use for these:
(Note: there are three versions of the win32.hlp file... an old one dating back to 1996 with all images removed (approx. 12 MB), a re-edited one (approx. 24 MB) which includes all images and some additional WinApi descriptions, and somewhere (although I've never seen it) must be the original file... It doesn't matter much which one you use though.)
Keep in mind that the WIN32.HLP file is old... If you need all information on all API's, in particular the newer ones, it's probably better to check on the Internet, and / or download the MicroSoft Platform SDK. You should be able to find most (if not all) of this information online as well, on msdn.microsoft.com. If you still want to use .HLP files on Vista or Windows 7, and they won't open on your machine, try this or this trick.
A similar thing can be done for inline assembly:
If the links above are no longer working then start up your Google and go search. These files are quite common. And if that didn't work, I've included them here as well...
More detailed examples you'll find here.
PureBasic was traditionally a bit lacking in the documentation and tutorials department, but things have improved greatly since 4.00, have a good look at the included help files (F1).
There is some good stuff to be had at purearea.net but be aware, some is in German, and some examples are based on older versions of PureBasic.
But, much better, check out the forum. Feel free to ask stupid questions. I've done that more than enough myself lately :-) Please note that on the forum there may be a lot of older code floating around, as there were quite a few improvements over time.
was so kind to offer his PureBasic Beginner's Guide for free. It
may not be entirely up-to-date with the latest version of PureBasic, but
it's a very good source of information. I've added a copy here.
Additional tools, documentations, references
A great source of information is the CodeArchive, which you will find at purearea.net as well.
Perhaps the best source for additonal tools is the forum. (Oh yes, I'm going to mention that PureBasic forum a lot, it's simply great!)
Of course, there's Kale's book again. (I guess the best spot to check for an eventual updated version would be the forum as well.)
it's pretty much inspired by JaPBe (which itself was based upon an earlier
version of the standard PB editor itself) and though at one time it was
rather limited it has become my editor of choice.
Fold and unfold
To fold or unfold use the plus or minus boxes behind the line number, or use F4.
the IDE you can specify what can be folded, this is a great way
to be able to fold enumeration or data section blocks! See the menu item
File / Preferences / Editor / Folding.
the IDE can now format your code 'on the fly', as well as upon your request.
Highlight a section of your code and hit Ctrl+I.
Online syntax check
Sorry GfaBasic users. No such thing.
here is a list of PB IDE vs. JaPBe shortcuts... You can change all the
PB IDE shortcuts though. Some functions do not exist in the PB IDE, others
do not exist in jaPBe.
Most of the regular commands are here. If you've been gone for a long time you might notice that PureBasic does not use line numbers... just kidding, you already knew that :-) If you didn't, better start with the Primer first... (This page is about to get somewhat dense.) I am even considering a 'total beginners guide to basic' but that's not there yet, and may never be...
Okay, some characteristics so you know what you can expect...
Pure compiles top to bottom. In other words, if you want to use something you got to define it first. The following will compile:
; survival guide 1_4_100 code orderAnd this will not compile:
test1() ; can't compile as test1() is not yet defined... unless you tell the compiler that something is coming up by using Declare().
; survival guide 1_4_101 code order
Procedures and functions
Functions and procedures are treated the same way.
Call a procedure :
Procedure test3()Call a procedure (function) and retrieve the return value:
Procedure.l test4() ; tell the compiler what type of variable will be returnedCall a procedure with a value:
Procedure.l test5(a.l) ; what goes out and what goes in...
Procedure parameters and the stack
PureBasic uses the same approach as C for passing parameters on to a procedure. Parameters are pushed on the stack from right to left. In most cases it doesn't matter, but it is something to be aware of:
Procedure.l test6(x.l)Here's another example, this one illustrates the difference between expression evaluation (left to right) and parameter passing (right to left):
Procedure.l d(x.l)It will list 1, 2, 3, then 3, 2, 1.
During development, the Debug command comes in handy... It will display text or variables in a dedicated debug window.
Debug "test message"(Follow this link for more ifnormation on the debugger.)
For console applications (Dos prompt stuff or simple things that don't need a real 'Windows window', you can use the console. To generate a real 'console' application, you have to set under compiler options the executable format to 'console'. The Print() command only works on a console.
OpenConsole()Obviously, 'normal' Windows applications have to open a window first to display any output. Obviously there are commands in PureBasic to do so. See all stuff on windows and gadgets.
Before digging in: if you're a beginner then stick to three variations: .a for bytes from memory, .d for floating point calculation (antything with fractions) and .i for everything else.
When used the first time, you tell the compiler what type a variable is. Most numeric types are 'signed' but as of 4.40b1 two new unsigned types have shown up.
; survival guide 1_5_100 variables and expressionsWhen you reuse a variable, you don't have to specify its type again.
a.l = 1 ; the first time, so say what it isThe default type is .i or 'integer'. The size of .i depends on the platform / compiler version!
a = 1 ; no type defined so it's an integerYou cannot use the same name for different variable types. In most other basics you could say:
a$ = "appel"Not so in PureBasic:
a.s = "appel"But this does:
a$ = "appel" ; the $ is considered part of the name AND turns 'a$' into a string variableNote that * and $ are the exception. (Think of them as being part of the variable name AS WELL AS type definition if that makes you happier :-))
a.s = "appel"Most numeric variables are signed! This can cause some surprises if you don't pay attention.
; survival guide 1_5_101 signed and unsigned(Don't forget, to use PrintN() we need a console to be open!)
has a different way of dealing with type conversion and expression evaluation,
which is described in more detail here.
In non-Unicode mode, all regular strings are zero terminated and cannot contain a null character (asci code 0). If they contain a zero, they will be truncated! If you are in a habit of using strings as buffers for binary content (that could contain one or more zero's) you will have to use so called 'fixed length strings' or do the right thing and just allocate memory...
In Unicode mode, all characters in memory occupy TWO bytes each, but although the memory where the strings reside can (and will!) contain $00 the string itself can still NOT contain the NULL character. Hmm. If you're a fresh starter, just forget I wrote this, and continue :-)
As of v4.00 there is a new type of string, the fixed length string, as well as a sort of 'string companion / byte alternative' called char. Fixed length strings can be great little beasts in structures!
a.s = "this is a test" ; variable size, zero terminated, cannot contain null characters
There is no boolean type. Instead, use an integer: 0 is false, <> 0 is true.
As of 5.11 there's the new command Bool(). It returns #True or #False, depending on the expression:
; survival guide 1_5_102 booleansLife wouldn't be great if we couldn't say no :-) So there's NOT and it's boolean brethern to help us out.
If you're a beginner you shouldn't be here at all! Please continue with the primer first and do not hang around here!
a = (a = b) does not work. Don't even try or ask for it. Don't. Please. Don't. Ask. Ever. PureBasic is not C or C++. It just won't work. Don't ask for it. Please.
Still here? Well, you've asked for it...
If a regular string is a member of a structure, then the structure itself does not contain the actual string but a pointer to that string. If you want the string to be part of the structure, you have to use fixed length strings.
; survival guide 1_5_103 structuresIf you want to have a 'fixed length' string as part of a struct, you either create an array of bytes (that sounds a little like c++), and array of char (to make it universal for Unicode and non-Unicode) or use a fixed length string.
Here's how to do it with an array of bytes, try the next example with Unicode off...
; survival guide 1_5_104 array of bytesAnd here's how to do it with an array of chars:
; survival guide 1_5_105 array of charsFor the experts: run the above in Unicode as well as non-Unicode mode (toggle Compiler / Compiler Options / Create Unicode Executable), play with the PokeS() lines above, and check the hex output.
Sometimes Pure does things in its own way. One of these things is the way expressions are evaluated, for example...
a.l = 2/3 + 2/3Surprised? Find out in detail what happens right here...
Make life easier
This is advanced stuff. Skip it if you're not into this (yet)...
A lot of standard windows functions are declared. Use the windows function name, add an underscore at the end of the name and try it!
If PureBasic knows the function, it will automatically open the appropriate dll and you don't have to use the OpenLibrary() function. (Even if the editor or jaPBe doesn't recognize the api, the compiler often does. Try to use it, and if there's an error then open the library (DLL) yourself.
demo version does not support Winapi calls!
In PureBasic on 32bit windows you don't have to force the type when calling a Winapi function. (In fact, you cannot even force the type in PureBasic.) So, when the function in WIN32.HLP tells you that the first parameter is a word, you don't bother and just pass it an integer (aka quad, long, word, or byte) as you feel fit. Same goes for returning values, although obviously they have to fit...
A DLL that is not defined by PureBasic has to be opened by hand. Here's what you do:
1. Open the library using OpenLibrary().
ws_winsock_h.i = OpenLibrary(ws_winsock_pbh,"WSOCK32.DLL") ; load the DLL and get back the DLL handle2. Look for the function you need with GetFunction()...
*ws_wsastartup = GetFunction(ws_winsock_pbh,"WSAStartup") ; find the address of the function3. GetFunction() returned an address. Use that address as a parameter for CallFunctionFast() and pass the appropriate parameters.
ws_retval.i = CallFunctionFast(*ws_wsastartup,$101,@ws_wsadata)The code above is only to illustrate the approach. Don't forget to close the library before ending your program. An alternative way is using CallFunction() or by using function pointers / prototypes. See here for more details.
Former GfaBasic users look here... some of those things might be of interest to people used to other dialects as well.
Over time I have asked some (stupid) questions regarding PureBasic... or witnessed those of others :-) Here are some of the answers that *might* be useful to you...
Q. I've seen a cheaper version on the internet!
A. Quite possible. PureBasic was available in other (boxed) versions as well, but only the 'expensive' version gets the lifetime free updates. All the 'boxed' 'editions' are worthy of some suspicion, so check on purebasic.com and the forums before buying anything! (In fact, there's no reason whatsoever to buy such a box, as those are old versions without a right to upgrade.)Q. Where can I find a list of all PB constants?
A.Open the structure viewer (from the tools menu in the editor) and select the constants tab.Q. And Windows constants?
A. Look around on the internet, there should be enough lists and utilities floating around... The Windows SDK is one option.Q. Nice, those files with all the constants, but they are very large and load slowly. Or I can't even read them...
A. Go to the Total Commander site and download lister.exe. In the standard editor as well as jaPBe you can add your own tools / config tools. Use path+lister.exe in the command line and path+filename for the file you want to view. Lister is fast and smart. And, while you are on the Total Commander site... register it. It's worth it. This shameless plug doesn't make me any money... (No money again? Damn!) As an alternative you could download CodeCaddy. (And that's another shameless plug that doesn't make me any money, I have to get smarter...)Q. So, PureBasic has loads of constants pre-defined... and structures too... or not?
A. How right you are. Browse through those files with constants, and you'll run into the structures as well. But, PureBasic offers you a nice boon. Hit alt + s and you can browse through all predefined structures, including their fields. That will save you quite some time. (There were a few errors in the default structs though so check them before using them.)Q. What's an unsigned short?
A. A word. (Yes, I know, this is not entirely true. Don't bother.)Q. Why can't I find EventWParam() in the help file?
A. It's a command that's Windows specific and might disappear one day. Although it's not very likely it will disappear anytime soon so don't worry too much :-)Q. How can I check if a file exists?
A. Use the FileSize() function (it was listed in the newbies faq, and I still asked the question, yes, I'm thick too)...Q. Why does <whatever> not work?
A. Check out the FAQ on the forum, and do a search there.Q. Why does a = (a = b) not work?
A. PureBasic isn't C++. It just doesn't work. Don't even try or ask for it.
There are tons of questions and answers to be found on the forum... Make sure you read the faq and do a search on that forum before posting a question! (Fortunately, it's a very understanding community, hum :-) Just remember, the best answers are those you found yourself... Also the Primer may just address that one stupid question you were always afraid to ask...
samples can be found on the PureBasic forum,
and some more in the code archiv at purearea.net.
please make sure you use the right version of PureBasic, or be prepared
for some decent DIY as some of those samples may be quite old!
to all the people I forgot to mention, and... AlphaSnd / Fred, Fr34k /
Freak, GPI, Inner, Pupil, Rings, Saboteur, TerryHough, TheFool, WolfgangS,