;
; *** BEFORE USING - MAKE A FILE CALLED 'TEXT.TXT' ON THE C DRIVE AND WRITE A FEW RANDOM LINES OF TEXT WITH NOTEPAD ***

; TYPES OF VARIALBES
; Global means it can be used anywhere - omiting this means it's local
; the main variable types you will need are .a .s .i ('i' is automatic if not specified)
; **YOU ALWAYS DEFINE YOUR GLOBAL VARIABLES AT THE TOP TO AVOID CONFUSION**
; EXAMPLES

; NOTE: We won't use all of these variables in our code below - some are just examples.

#THE_FILENAME = "C:\text.txt" ; this is a constant text string - constants are described later
Global TheNumber = 1000 ; this is automatically an integer (for big numbers) by default because there's no '.i' period after it
Global PushedButton.a = #False ; '.a' after means this uses 1 byte (either for true/false or for numbers 0 - 255). it's the smallest unit available
Global TheText.s = "This is some text" ; you use '.s' to denote a text string variable

; AN ARRAY
Global Dim TheTextLines.s(10, 10) ; this defines a 2D matrix (a.k.a. array) 10 by 10 of text strings
; how to use it
TheTextLines(1, 1) = "thing" ; now position 1 by 1 equals 'thing'. you can also use 0 by 0 if you want. most things start at zero.
Global Dim RealLines.s(0) ; this one is also an array, but with one dimension. it's zero because the size will be defined later - we don't know how much space we need yet

; LOCALS
; if you write a var without using global in front, it'll automatically be local
TheTest.a = #True
HappyFrank.s = "happy to be"

; EXAMPLES OF PROCEDURES
; these get called in your code below to use them - like 'LoadSomeText()'. it's used as if it's a built in command in the language.
Procedure LoadSomeText()
	This_Is_A_Variable.a = 50 ; a local variable with a size of 1 byte - can store 0 to 255. it can't be used outside this procedure.
														; you may use underscore or capitalization in your variable names, just NO SPACES.
	TheText = "this is some new text" ; this one we can access/change in here cause it's Global. we couldn't use HappyFrank in here though (we 'could', but it would be a new var that's cleared.)
	; put whatever code you want in here
EndProcedure

; these procs don't return anything. if it were to return something, you'd write 'Procedure.i' or 'Procedure.a' for example. SEE BELOW at the next procedure.
Procedure AnotherProc()
	; more stuff would go in here
EndProcedure

; this proc will count the number of lines in a text file
; we need to use this below, you'll see
; FileNumber is a default '.i' that we pass into the procedure like a command parameter.
Procedure.i CountFileLines(FileNumber) ; on a procedure '.i' should be defined if the proc is to return a value. it means this proc will return an integer number, but it could be any of the types.
	Lines = 0 ; automagically an integer cause no '.' after it
	Repeat
		Lines + 1 ; in PB (unlike other langs), we don't say 'Lines = Lines + 1' or 'Lines++' - it's more clear IMO.
		ReadString(FileNumber)
	Until Eof(FileNumber) = #True ; Eof means 'End Of File', so this loop repeats until the end of file has been reached.
	Lines - 1 ; we get one extra blank line at the bottom of the file, so -1 to ignore it
	FileSeek(FileNumber, 0) ; this sets our reading pointer back to the top of the file, so we can later start reading from the begining again.
	ProcedureReturn Lines
EndProcedure

; MACROS
; macros are simply procs that are basically pasted in place of your code (where ever you write its name)
; whereas procs actually get referenced and the code jumps into it
; so if you use a long macro too often, it will bloat your code because it's pasting copies of it everywhere - in that case, use a procedure
; they are generally used to just make your code look better and more understandable below
Macro BeginingOfFile()
	FileSeek(0, 0)
EndMacro

; ANYTHING OUTSIDE OF/BELOW YOUR PROCS AND VARIABLE DECLARATIONS, IS THE MAIN ENTRY POINT OF YOUR PROGRAM
; so this is where the program starts executing.
; For example: This_Is_A_Variable - will not work here because it is local to the procedure called LoadSomeText()

If ReadFile(0, #THE_FILENAME) ; opens this text file as file number zero. if you were to open more files, you'd put one, etc. if you are done and CloseFile(0), then you can re-use zero again.
	
	; we count the number of lines in the file so that we know how big to make the array (1D matrix)
	Lines = CountFileLines(0) ; Lines = the integer returned by using our procedure above
	Dim RealLines.s(Lines) ; this is the array we defined above as 'Global' with a size of zero. we are now re-dimensioning it to the size in the variable 'Lines'
	For CurrentLine = 0 To Lines
		RealLines(CurrentLine) = ReadString(0) ; we read each line from the file and assign it to its proper position in the array
	Next
	BeginingOfFile() ; go back to the begining so we can do it again with a different example. the macro code is pasted here behind the scenes.
	
	#GOODLY_FILE = 0 ; this is an example of a constant. it's denoted with a hashtag. it's a pre-defined variable that can never change at run-time.
									 ; you could use this constant instead of writing '0' for your file number everywhere. it's just to make your code more readable.
										; Example: OpenFile(#GOODLY_FILE, "B:\text.txt") .... Lines = CountFileLines(#GOODLY_FILE)
	#ANOTHER_FILE = 1	; if you know your numbers will always be in order... (in some instances you want constants with numbers out of order)
										; you can use an Enumeration and that will automatically number them in order
	Enumeration ; enumerations are convenient because sometimes, you might want to remove an item from the list and not have to change all the following numbers to be in order.
		#FIRST_FILE ; they don't need to be capitalized, but this is the main convention
		#SECOND_FILE
		#THIRD_FILE
	EndEnumeration ; enumerations are very important when dealing with windows and their containing objects (gadgets in PB)...
								; so you don't have to remember the object numbers AND can also insert more objects without changing all the subsequent ones.
	
	; here is another way to read the lines that's much simpler and doesn't use a procedure like CountFileLines, but it's far slower
	Lines = 0
	Repeat
		RealLines(Lines) = ReadString(#GOODLY_FILE)
		Lines + 1
		ReDim RealLines.s(Lines) ; we are using ReDim here, instead of Dim. ReDim resizes the array and preserves its contents.
														 ; so instead of counting the file lines first, we just resize the array once on each loop - slower and junky. to resize and preserve, the system...
														 ; has to reallocate a new slightly larger chunk of ram and then copy the contents from the old array into the new larger memory space.
														 ; use it sparingly and only when there is absolutely no way to determine the size of something beforehand like we did above.
	Until Eof(#GOODLY_FILE) = #True
	Lines - 1
	
	CloseFile(#GOODLY_FILE)
	
	; display the lines
	For DisplayLine = 0 To Lines
		MessageRequester(TheText, RealLines(DisplayLine)) ; this shows each line of the array we read in a MessageBox (the term used in mainstream languages).
	Next
	
Else
	MessageRequester(HappyFrank, "The file '" + #THE_FILENAME + "' could not be opened!", #PB_MessageRequester_Error) ; this is the same as MessageBox in VB.
EndIf