@DATABASE Reference.Guide
$VER: Pure Basic Reference Manual (23.01.2000) © Fantaisie Software & Les Morgan
@NODE Main "Pure Basic Reference Manual"

            ************************************************************
           *                                                           *
           *             @{b}PureBasic Reference Manual V1.30@{ub}              *
           *                                                           *
           *               © 2000 - Fantaisie Software -               *
           *                                                           *
           ************************************************************


                 @{b}General Topics:@{ub}           @{b}External Libraries:@{ub}

            @{"Using the Editor       " LINK Editor          }      @{"Amiga               " LINK "PureBasic:Help/Amiga.guide/Main"}
            @{"Using the CLI compiler " LINK CLI_Compiler    }      @{"App                 " LINK "PureBasic:Help/App.guide/Main"}
            @{"General Syntax Rules   " LINK General_Rules   }      @{"BitMap              " LINK "PureBasic:Help/BitMap.guide/Main"}
            @{"Variables and Types    " LINK Variables       }      @{"Chunky              " LINK "PureBasic:Help/Chunky.guide/Main"}
                                   @{ "" LINK k              }      @{"ClipBoard           " LINK "PureBasic:Help/ClipBoard.guide/Main"}
  @{b}Basic Keywords:@{ub}                  @{ "" LINK k     }      @{"Commodity           " LINK "PureBasic:Help/Commodity.guide/Main"}
                                   @{ "" LINK k              }      @{"Drawing             " LINK "PureBasic:Help/Drawing.guide/Main"}
            @{"For: Next              " LINK For_Next        }      @{"Font                " LINK "PureBasic:Help/Font.guide/Main"}
            @{"Gosub: Return          " LINK Gosub_Return    }      @{"File                " LINK "PureBasic:Help/File.guide/Main"}
            @{"If: EndIf              " LINK If_Endif        }      @{"Gadget              " LINK "PureBasic:Help/Gadget.guide/Main"}
            @{"Repeat: Until          " LINK Repeat_Until    }      @{"Linked List         " LINK "PureBasic:Help/LinkedList.guide/Main"}
            @{"Select: EndSelect      " LINK Select_EndSelect}      @{"Menu                " LINK "PureBasic:Help/Menu.guide/Main"}
            @{"While: Wend            " LINK While_Wend      }      @{"Misc                " LINK "PureBasic:Help/Misc.guide/Main"}
            @{"Others                 " LINK Others          }      @{"OS                  " LINK "PureBasic:Help/OS.guide/Main"}
                                   @{ "" LINK k              }      @{"Palette             " LINK "PureBasic:Help/Palette.guide/Main"}
  @{b}Structure Options:@{ub}               @{ "" LINK k     }      @{"Picture             " LINK "PureBasic:Help/Picture.guide/Main"}
                                   @{ "" LINK k              }      @{"Requester           " LINK "PureBasic:Help/Requester.guide/Main"}
            @{"DefType                " LINK DefType         }      @{"Screen              " LINK "PureBasic:Help/Screen.guide/Main"}
            @{"Dim                    " LINK Dim             }      @{"Sort                " LINK "PureBasic:Help/Sort.guide/Main"}
            @{"NewList                " LINK NewList         }      @{"Sound               " LINK "PureBasic:Help/Sound.guide/Main"}
            @{"Structure: EndStructure" LINK Structures      }      @{"String              " LINK "PureBasic:Help/String.guide/Main"}
                                   @{ "" LINK k              }      @{"TagList             " Link "PureBasic:Help/TagList.guide/Main"}
  @{b}Procedure Support:  @{ub}             @{ "" LINK k     }      @{"ToolType            " Link "PureBasic:Help/ToolType.guide/Main"}
                                   @{ "" LINK k              }      @{"WbStartup           " Link "PureBasic:Help/WbStartup.guide/Main"}
            @{"Global                 " LINK Global          }      @{"Window              " Link "PureBasic:Help/Window.guide/Main"}
            @{"Procedure: EndProcedure" LINK Procedures      }    
            @{"Shared                 " LINK Shared          }    @{b}Commands index:@{ub}
                                   @{ "" LINK k              }
  @{b}Compiler Options:@{ub}                @{ "" LINK k     }      @{"       Index        " Link "PureBasic:Help/Index.guide/Main"}
                                   @{ "" LINK k              }
            @{"'Include' Functions    " LINK Includes        }
            @{"Debugger               " LINK Debugger        }                

@ENDNODE


@NODE Editor

  @{b}Introduction:@{ub}

    The PureBasic editor has been created especially for the PureBasic
    programming language and has many special features especially
    designed for it. It will become more and more powerful and will support
    advanced editing like coloring syntax, word filling, online help...


  @{b}Basic usage:@{ub}

    The PureBasic editor accept any standard ASCII characters, and load
    and save the file in the ASCII format. It use all Amiga standard
    short cut to edit the text:

      Arrows Keys        : Move the cursor in the four ways
      Shift + Arrow Up   : One page up
      Shift + Arrow Down : One page down
      Shift + Arrow Left : Start of the line
      Shift + Arrow Right: End of the line

      Shift + Enter    : Insert a line above the current line
      Shift + Del      : Delete the right part of the line
      Shift + Backspace: Delete the left part of the line

      Help: Bring up the PureBasic manual online help (this document)

    Now, the most important menus shortcuts:

      AmigaRight + S: Save the current source code without any request
      AmigaRight + Q: Quit the PureBasic
      AmigaRight + L: Load a new source code


  @{b}Special features:@{ub}

    There is a menu called 'Compiler' and it's by this way you could
    control the PureBasic. Menu items:

    * Compile/Run: Compile the actual source code and run it.
    * Debugger: Switch which toggle ON/OFF the debugger
    * Options:

      - Output processor: 680x0/PowerPC. Change the format of  the
        generated executable. The PowerPC version is for WarpOS.

      - Code optimizations: Turn on the optimizations while compiling
        in the editor, to have exactly the same executable than the
        final one. Of course the debugger must be turned off, else
        this option is ignored. Better to turn it off while developping,
        as it increase the compile time...

      - Commented ASM output files: Generate a commented asm file when
        you create a final executable. The file is located at
        "PureBasic:Compilers/PureBasic.asm". You can modify this file
        (optimize it) and recompile it with phxass. It slow down a
        lot the executable generation so use it only when you need it.

      - Disable CLI output: Don't display the cli output window, useful
        if your program print nothing to the cli.

      - Create an icon: An icon will be added to the created executable
        The icon is located at "PureBasic:Compilers/Default_Icon.info"
        You can replace it by another one if you want

      - Save: Save theses preferences for the actual file. Each file can
        have their own preferences.

    * CreateExecutable: Create a final executable. The optimizations are
      of course turned on automatically. It use the options defined as
      described above.


    Other options like InsertFile, Print, Find, are classic one like
    on any other editors...

@ENDNODE

@NODE CLI_Compiler "Using the CLI Compiler"

  @{b}Using the CLI compiler:@{ub}

   Type "PureBasic" followed by the source filename to compile. PureBasic will 
   compile and launch the programme.

   Compiler options:

  @{b}FILE@{ub}

   String: This needs a source file name! This argument is needed or the compiler
   will generate an error.

  @{b}TO@{ub}

   String: If specified, you must add the destination path, and the filename, to
   show where the executable must be created. Note: Only the executable is created
   in this case. The programme is not started.

  @{b}NR or NORESIDENT@{ub}

   Switch: If this is set, it will not load the AmigaOS resident file. By default
   the compiler will load this file, thus increasing the compilation time.

  @{b}PPC or POWERPC@{ub}

   Switch: If this is set, the compiler will generate an Amiga PowerPC executable 
   for WarpOS. For the present, the result will read as an error. It can be tested. 
   Please record the asm file, and the generated code, then send us the result!
   All data will be recorded and analysed in our continuous attempts to improve
   this option. Thank you for your assistance.  :)

  @{b}NC or NOCOMMENT@{ub}

    Switch: If this is set, it will produce a non-commented asm output, which is 
    smaller and faster to assemble. This will decrease the compilation time.

  @{b}PRI or PRIORITY@{ub}

    Numeric: A numeric value between -127 and +127, is required. It will determine 
    the priority of the compiler. Example: PureBasic PRI=10 .. will give almost all
    of the cpu time to the compiler.                                               

  @{b}CR or CREATERESIDENT@{ub}

    Switch: This will compile the programme, and create a resident file with all 
    structures and constants. The compiled file is located in "Ram:ResidentFile"
    and "Ram:ResidentFile.struct"

  @{b}STANDBY@{ub}

    Switch: If this is set, the compiler is put into "sleep mode" and waits for 
    on order through its message port. Please do not use it yet, as it is for use
    with the forthcoming editor.

  @{b}DB or DEBUGGER@{ub}                                                              
                                                                                     
    Switch: If this is set, it will compile the programme with debugger support. 
    Shortly the debugger can be used to interrupt the programme. Please use it 
    carefully and run it step by step...                                              

  @{b}OPT or OPTIMIZATIONS@{ub}

    Switch: If this is set, it will enable maximum optimization, and generate fast 
    and small executables.                                                           
     


  Examples:

    PureBasic Sources:MypPog.pb DB PRI=10

    PureBasic Sources:Example.pb TO Ram:Example.exe OPT PRI=10

@ENDNODE

@NODE General_Rules

    @{b}General Rules@{ub}

  PureBasic has established rules which never change.
  These are:------

  * Comments are marked by @{b} ; @{ub}. All text entered after ; is ignored by the compiler.

   Example:

    If a = 10; This is a comment to indicate something.

  * All functions must be followed by ( or else it will not be considered as a 
    function, (even for null parameter functions).

   Example: @{b}WindowID()@{ub} is a function.
             @{b}WindowID@{ub} is a variable.

  * All constants are preceded by @{b} # @{ub}

   Example:

      @{b}#Hello = 10@{ub} is a constant.
      @{b} Hello = 10@{ub} is a variable.

  * All labels must be followed by @{b} : @{ub}

   Example:

      I_am_a_label:

  * An expression is something which can be evaluated. An expression can mix any 
    variables, constants, or functions, of the same type.

    Examples of valid expressions:

      a+1+(12*3)
      a+WindowHeight()+b/2+#MyConstant
      a <> 12+2
      b+2 >= c+3

  * Any number of commands can be added to the same line by using the @{b} : @{ub} option.
  

    Example:

      If OpenScreen(0,320,200,8,0) : PrintN("Ok") : Else : PrintN("Failed") : EndIf

  * Words used in this guide:

    <variable>  : a basic variable.
    <expression>: an expression as explained above.
    <constant>  : a numeric constant.
    <label>     : a programme label.
    <type>      : any type, (standard or structured).

  * In this guide, all topics are listed in alphabetical order to decrease any
    search time.

@ENDNODE


@NODE Variables

  @{b}Variables declaration:@{ub}

    To declare a variable in PureBasic type its name, or the type you want this 
    variable to be. Variables do not need to be explicitly declared, as they can
    be used as "variables on-the-fly."
    The "DefType" keyword can be used to declare mass variables.

    Example:

      a.b   ; Declare some variables.
      c.l   ;

      c = a*d.w ; "d" is declared here within the expression!


    To use a pointer, put * before the variable name. A pointer is a long variable 
    which stores an address. It is generally associated with a structured type. 
    So, you can access the structure via the pointer.

    Example:

      *MyScreen.Screen = OpenScreen(0,320,200,8,0)

      mouseX = *MyScreen\MouseX


  @{b}Basic types@{ub}

    PureBasic allows type variables. It now supports signed variables. Unsigned 
    variables can be used, but this can result in an error, as this option is 
    still in it's early stages.

    Types:

    Byte: .b, take 1 byte  in memory. Range: -128 to +127.
    Word: .w, take 2 bytes in memory. Range: -32768 to +32767
    Long: .l, take 4 bytes in memory. Range: -2147483648 to +2147483647

    Unsigned Byte: .ub, take 1 byte  in memory. Range: 0 to 255
    Unsigned Word: .uw, take 2 bytes in memory. Range: 0 to 65535
    Unsigned Long: .ul, take 4 bytes in memory. Range: 0 to 4294967295

    String: .s, take the string length into memory.


  @{b}Structured types@{ub}

    Build structured types, via the Structures option. More information can be 
    located in the "structures chapter."

@ENDNODE


@NODE For_Next "For : Next"

  @{b}Syntax:@{ub}

    For <variable> = <expression1> To <expression2> [Step <constant>]

       ... Loop content

    Next [<variable>]

  @{b}Description:@{ub}

    The "For/Next" function is used to cause a loop within a programme within 
    given parameters. At each loop the <variable> is increased by a factor of 1, 
    (or of the "Step value" if a Step value is specified), when the <variable> 
    value equals the <expression2> loop stop.

    Example 1:

      For k=0 To 10
        ...
      Next

      In this example, the programme will loop 11, time (0 to 10), then quit.


    Example 2:

      a = 2
      b = 3

      For k=a+2 To b+7 Step 2
        ...
      Next k

      Here, the programme will loop 4 times before quitting, (k is increased by a
      value of 2 at each loop, so the k value is: 4-6-8-10). The "k" after the
      "Next" indicates that "Next" is ending the "For k" loop. If another variable, 
      is used the compiler will generate an error. It is useful when nesting some 
      "For/Next" expressions.

    Example 3:

      For x=0 To 320
        For y=0 To 200
          Plot(x,y)
        Next y
      Next x


@ENDNODE


@NODE Gosub_Return

  @{b}Syntax:@{ub}

    Gosub <label>

    <label>:

      ... Sub routine code

    Return


  @{b}Description:@{ub}

    "Gosub" stands for "Go to sub routine." A label has to be specified after 
    "Gosub" then the programme will continue at the label position until it 
    encounters a "Return." When a return is reached, the programme is transferred 
    below the Gosub.

    "Gosub" is very useful when building fast structured code.

    Example:

      a = 1
      b = 2

      Gosub ComplexOperation

      PrintNum(a)
      End


      ComplexOperation:

        a=b*2+a*3+(a+b)
        a=a+a*a

      Return



  @{b}Syntax:@{ub}

    FakeReturn

  @{b}Description:@{ub}

    When you want to jump from a sub routine (with the command 'Goto')
    to another part in the code outside of this sub routine, you need
    to use a FakeReturn which simulate a return without do it really.
    If you don't use it, your program will crash.

    This function should be useless because a well constructed program
    don't use Goto. But sometimes, for speed reason, it could help
    a bit.

    Example:

        Main_Loop:
            ...

        SubRoutine1:
            ...
            If a = 10
              FakeReturn
              Goto Main_Loop
            Endif

        Return

@ENDNODE


@NODE If_Endif

  @{b}Syntax:@{ub}

    If <expression>
      ...
    [Else]
      ...
    EndIf


  @{b}Description:@{ub}

    The "If" structure is used to achieve tests, and/or change the programmes 
    direction, if the test is true or false. The "Else" optional command is used 
    to execute a part of code, if the test is false.

    Any number of "If" structures can be nested together.

    Example 1:

      If a=10
        Nprint ("a=10")
      Else
        Nprint ("a<>10")
      EndIf


    Example 2:

      If a=10 and b>=10 or c=20
        If b=15
          nprint("ok")
        Else
          nprint("ok2")
        Endif
      Else
        nprint("test failure")
      Endif

@ENDNODE


@NODE Repeat_Until "Repeat : Until"

  @{b}Syntax:@{ub}

    Repeat

      ... Programme ...

    Until <expression>
[or Forever]


  @{b}Description:@{ub}

    This function will loop until the <expression> becomes true. Any number can be
    repeated. If an endless loop is needed then use the "Forever" keyword instead 
    of "Until."

    Example:

      a=0
      Repeat
        a=a+1
      Until a>100

    This will loop until "a" takes a value > to 100, (it will loop 101 times).

@ENDNODE


@NODE Select_EndSelect "Select : EndSelect

    @{b}Syntax:@{ub}

      Select <expression1>

      Case <expression2>

        ...Code...

      [Case <expression3>....]

        ...Code...

      [Default]

        ...Code...

      EndSelect


  @{b}Description:@{ub}

    "Select" allows a quick choice. The programme will execute the <expression1> 
    and keep its value in memory. It will compare this value to all of the "Case 
    <expression> values," and if true it will execute the corresponding code and 
    quit the "Select" structure. If none of the "Case" values are true, then the 
    Default code, (if specified), will be executed.

    Example:

      a = 2

      Select a

        Case 1
          PrintN("Case a = 1")

        Case 2
          PrintN("Case a = 2")

        Case 20
          PrintN("Case a = 20")

        Default
          PrintN("I don't know")

      End Select



  @{b}Syntax:@{ub}

    FakeEndSelect

  @{b}Description:@{ub}

    When you want to jump from a select part (with the command 'Goto')
    to another part in the code outside of the Select, you need
    to use a FakeEndSelect which simulate an EndSelect without do it really.
    If you don't use it, your program will crash.


    Example:

        Main_Loop:
          ...
          Select a

            Case 10
              ...

            Case 20
              FakeEndSelect
              Goto Main_Loop

          EndSelect


@ENDNODE


@NODE While_Wend "While : Wend"

  @{b}Syntax:@{ub}

    While <expression>

      ... Programme ..

    Wend


  @{b}Description:@{ub}

    "Wend" will loop until the <expression> becomes false. A good point to keep in 
    mind with a "While" test is that if the first test is false, then the programme
    will never enter the loop and will skip this part. A "Repeat" loop is executed 
    at least once, (as the test is performed after each loop).

    Example:

      b = 0
      a = 10
      While a = 10
        b = b+1
        If b=10
          a=11
        Endif
      Wend

    This programme loops until the "a" value is <> 10. A change here when b=10,
    the programme will loop 10 time.

@ENDNODE


@NODE Others

  A list of other commands:

  @{b}Goto@{ub}

    Goto <label>

    This command is used to transfer the programme directly to the labels position. 
    Be cautious when using this function, as incorrect use could cause a programme
    to crash...

@ENDNODE


@NODE Deftype

  @{b}Syntax:@{ub}

    Deftype.<type> [<variable>, <variable>,...]


  @{b}Description:@{ub}

    If no <variables> are specified, "DefType" is used to change the "Default type" 
    for future untyped variables.

    Example:

      DefType.l

      a = b+c

      a, b and c will be signed long typed (.l) as no type is specified.


    If variables are specified, "DefType" only declares these variables as
    "defined type" and will not change the default type.

      Example:

      DefType.b a,b,c,d

      a,b,c,d will be signed byte typed (.b)

@ENDNODE


@NODE Dim

  @{b}Syntax:@{ub}

    Dim name.<type>(<expression>)


  @{b}Description:@{ub}

    "Dim" is used to "size" the new arrays. An array in PureBasic can be of any 
    types, including structured, and user defined types.
    Once an array is "dim" it cannot change it's time and another array cannot be 
    classed as "dim" with the same name.

    Example:

      Dim MyArray.l(41)

      MyArray(0) = 1
      MyArray(1) = 2


@ENDNODE


@NODE NewList "NewList"

  @{b}Syntax:@{ub}

    NewList name.<type>()


  @{b}Description:@{ub}

    "NewList" allows managed dynamic linked lists in PureBasic. Each element of
    the list is allocated dynamically. There are no element limits, so there can 
    be as many as needed. A list can have any standard or structured type.

    To view all commands used to manage lists, please click @{" here " LINK "PureBasic:Help/LinkedList.guide/Main"}

    Example:

    NewList mylist.l()

    AddElem(mylist())

    mylist() = 10


@ENDNODE

@NODE Structures

  @{b}Syntax:@{ub}

    Structure <name of structure>

       ... Structure content

    EndStructure


  @{b}Description:@{ub}

    "Structure" is useful to define user type, and access some OS memory areas. 
    Structures can be used to enable faster and easier handling of big data files. 
    Structures are accessed with the "\" option.
    Structures can be nested.

    Example:

      Structure Info
        Name.s
        ForName.s
        Age.l
        Birthday.l
      EndStructure

      Dim myfriends.Info(100)

      myfriends(0)\Name = "Andersson"
      myfriends(0)\Forname = "Richard"
      ...

@ENDNODE


@NODE Global

  @{b}Syntax:@{ub}

    Global <variable> [,<variable>,...]


  @{b}Description:@{ub}

    "Global" allows the variables to be used as Global, ie: they can be accessed 
     inside a procedure.

    Example:

      Global a.l, b.b, c, d


@ENDNODE


@NODE Shared

  @{b}Syntax:@{ub}

      Shared <variable> [,<variable>,...]


  @{b}Description:@{ub}

      "Shared" allows a variable to share, or to be accessed, within a procedure.


      Example:

        a.l = 10

        Procedure myproc()
          Shared a

          a = 20

        EndProcedure

        myproc()

        PrintN(Str(a)) ; Will print 20, as the varaible has been shared.


@ENDNODE


@NODE Procedures

  @{b}Syntax:@{ub}

      Procedure[.<type>] name(<variable1>[,<variable2>,...])

        ... Procedure code

        [ProcedureReturn value]

      EndProcedure


  @{b}Description:@{ub}

      A "Procedure" is a part of code independent from the main code which can
      have any parameters and it's own variables. In PureBasic, a recurrence is 
      fully supported for the "Procedures" and any procedure can call it itself.
      To access main code variables, they have to be shared them by using
      "Shared" or "Global" keywords.

      A procedure can return a result if necessary. You have to set the type
      after 'Procedure' and use the 'ProcedureReturn' keyword at any moment
      inside the Procedure.

      Example:


        Procedure.l Maximum(nb1.l, nb2.l)

          If nb1>nb2
            Result = nb1
          Else
            Result = nb2
          Endif

          ProcedureReturn Result

        EndProcedure

        Result.l = Maximum(15,30)

        PrintNumberN(Result)

        End

@ENDNODE


@NODE Includes

  @{b}Syntax:@{ub}

     IncludeFile "filename"
    XIncludeFile "filename"

  @{b}Description:@{ub}

    "IncludeFile" will include any named source file, at the current place in the 
    code. "XIncludeFile" is exactly the same except it avoids having to include 
    the same file many times.

    Example:

      XInclude "Sources:myfile.pb" ; This will be inserted.
      XInclude "Sources:myfile.pb" ; This will be ignored along with all subsequent 
      calls..


  @{b}Syntax:@{ub}

    IncludeBinary "filename"

  @{b}Description:@{ub}

    "IncludeBinary" will include the named file at the current place in the
    code.

    Example:

      IncludeBinary "Sources:myfile.data"



  @{b}Syntax:@{ub}

    IncludePath "path"

  @{b}Description:@{ub}

    "IncludePath" will specify a default path for all files included after the call of
    this command. This can be very handy when you include many files which are in the
    same directory:


    Example:

      IncludePath "Sources:Data/"

       IncludeFile "Sprite.pb"
      XIncludeFile "Music.pb"
      ...

@ENDNODE

@NODE Debugger

  @{b}The PureBasic Debugger@{ub}

    The debugger is an external program which can control the execution of a 
    programme. The provided debugger is limited and has few functions. Nevertheless 
    it is enough to debug a programme correctly. It will be regulary updated and 
    bettered. If anyone wants to do their own debug utility, please contact us. The
    debugger is 100% OS friendly and does not use interrupts or trap vectors.

    A programme's execution can be stopped, and an analysis made to locate any
    faults! This can be very useful in case a programme falls into an endless loop.

    Functions:

      @{b}Stop@{ub}

    This will halt the execution then display the current code position.

      @{b}Cont@{ub}

    This will continue a previously stopped programme.

      @{b}Step@{ub}

    This button allows code to be inserted step by step, ie: line after line. It is 
    very handy to locate any faults.

      @{b}Trace@{ub}

    This button allows the user to read the code as the programme lines are 
    displayed.

      @{b}Exit@{ub}

    Exit: This quits the debugger; the compiler; and any programme in case of any
    problems or if an "endless loop" cannot be stopped in any other way.


  @{b}The debugger's keywords in PureBasic:@{ub}

    @{b}STOP:@{ub} 
     
    Stop: This invokes the "debugger" and freezes the programme immediately.

    Example:

      If a=10
        Stop   ; The debugger will be invoked.
      Else
        Ok=1
      Endif


@ENDNODE