Code Organization

[JaxMusic]

Good evening. As I explore Pure Basic I am trying to get a handle on code organization. I see we can have multiple code files in a program and can access them in the IDE, or even organize them in a project. What I don’t see is how you can reference functions in other code (.pb ) files. For example, I would like to write a series of related functions and keep them in a code file separate from the main code file. How are the references to those functions in the other file declared? Is there something equivalent to #include x.pb to use in your main flow?

Thanks

[BarryG]

there something equivalent to #include x.pb to use in your main flow?

Sure is:

https://www.purebasic.com/documentation ... ludes.html

So you can create all the common reusable code in such a PB file, and then include them in any source at the point of the IncludeFile() command.

[skywalk]

2 schools.
Use IncludeFiles of your xxx_something.pbi code or use Modules.
I prefer the former method.
This does demand a prefixed naming convention for large projects, but there is no additional syntax burdens.
You can also use both methods when the community provides libraries in module or includefile format.

[TI-994A]

...how you can reference functions in other code (.pb ) files. For example, I would like to write a series of related functions and keep them in a code file separate from the main code file. How are the references to those functions in the other file declared?

Quite simple, actually. Consider this example:

example 1:

Code: Select all

Procedure add(a, b)
  ProcedureReturn a + b
EndProcedure

Procedure subtract(a, b)
  ProcedureReturn a - b
EndProcedure

Debug add(1, 2)
Debug subtract(6, 3)

To save the two procedures (add & subtract) separately, simply paste them into another code file, save them as myFunctions.pb, for example, and then call them from any other code file.

myFunctions.pb:

Code: Select all

Procedure add(a, b)
  ProcedureReturn a + b
EndProcedure

Procedure subtract(a, b)
  ProcedureReturn a - b
EndProcedure

Now, to use these functions, simply include them into any code file, and call them as usual, like so:

myCode.pb:

Code: Select all

IncludeFile "myFunctions.pb"

Debug add(1, 2)
Debug subtract(6, 3)

Multiple files can be included in this manner. Let's add another:

myFunctions2.pb:

Code: Select all

Procedure multiply(a, b)
  ProcedureReturn a * b
EndProcedure

Procedure divide(a, b)
  ProcedureReturn a / b
EndProcedure

Then simply add it to the code file to use its functions:

Code: Select all

IncludeFile "myFunctions.pb"
IncludeFile "myFunctions2.pb"

Debug add(1, 2)
Debug subtract(6, 3)

Debug multiply(2, 3)
Debug divide(12, 2)

The IncludeFile function simply inserts the referenced code file directly where it is called. Technically, when expanded by the compiler, the code in myCode.pb would look exactly as the code in example 1.

It should be noted, however, that if a file is included further down the code list, any preceding calls to any functions within that file will not work. This is because all definitions for arrays, variables, structures, procedures, etc., must precede their reference (see Question 2 in this post for a more detailed explanation).

This sequence will fail with exception:

Code: Select all

; the compiler will throw an error > add() is not a function...

Debug add(1, 2)
Debug subtract(6, 3)

IncludeFile "myFunctions.pb"

This can be remedied by simply declaring the required functions prior to their calls, though it may not be practical for lengthy includes.

Code: Select all

Declare add(a, b)
Declare subtract(a, b)

Debug add(1, 2)
Debug subtract(6, 3)

IncludeFile "myFunctions.pb"

[Tenaja]

I prefer XIncludeFile, because of you have a large project with multiple shared files, you don't accidentally send up with duplicates.

For instance, if both library A and library B require library C to work, in a project that requires both A&B, using normal IncludeFile in each could cause errors due to the duplicate includes. But XIncludeFile avoid/prevents that issue.

[JaxMusic]

Excellent, thanks everyone.

[JaxMusic]

[quote="TI-994A"][/quote] thanks for the excellent example TI-994A

[eck49]

Include / XInclude

If you want or need to make your eventual executable small, keep your individual Included files small - any code in them which is not actually used in the current context is still compiled and included in the executable.

Naming convention

Think about this early on. I name anything in a file-to-be-included which has external exposure (procedures, constants, variables) using a prefix unique to that file which is related to the file name (I use a trigraph of capital letters). If it is within the scope of the IDE editor, auto-complete then prompts with a list of possible completions, and the IDE knows procedure parameters just as with PB-native names.

Trying out snippets

Do you want to try out a self-contained bit of code, a demo of something you may want to use, before incorporating it into your project? Perhaps there is more than one possibility and you don't want to touch your already working good stuff before deciding between them. Click on File > New in the IDE and paste in what you want to try out. As long as it is truly self-contained - meaning it has a main loop, as most example code does - you can run it without affecting the main project you are coding so you can see what it does. Very useful when venturing into unknown territory.