Skip to content

Commit 1b29541

Browse files
jayrmjayrm
committed
fbdocs: wiki snapshot 2023.05.06
1 parent f188162 commit 1b29541

19 files changed

+2516
-1482
lines changed

‎doc/manual/cache/CatPgOpIndex.wakka‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ List of operators used in FreeBASIC.
7676
- {{fbdoc item="keyword" value="KeyPgOpAt|@ (Address of)"}}
7777
- {{fbdoc item="keyword" value="KeyPgOpValueOf|* (Value of)"}}
7878
- {{fbdoc item="keyword" value="KeyPgOpVarptr|VARPTR (Variable pointer)"}}
79-
- {{fbdoc item="keyword" value="KeyPgOpProcptr|PROCPTR (Procedure pointer)"}}
79+
- {{fbdoc item="keyword" value="KeyPgOpProcptr|PROCPTR (Procedure pointer and vtable index)"}}
8080

8181
{{fbdoc item="section" value="Type or Class Operators"}}
8282
- {{fbdoc item="keyword" value="KeyPgOpMemberAccess|. (Member access)"}}

‎doc/manual/cache/CatPgOpPoint.wakka‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ The pointer operators provide the ability to retrieve the addresses in memory of
77
Returns the memory address of a variable.
88
=={{fbdoc item="keyword" value="KeyPgOpStrptr|Operator Strptr (String pointer)"}}==
99
Returns the memory address of a string's character data.
10-
=={{fbdoc item="keyword" value="KeyPgOpProcptr|Operator Procptr (Procedure pointer)"}}==
10+
=={{fbdoc item="keyword" value="KeyPgOpProcptr|Operator Procptr (Procedure pointer and vtable index)"}}==
1111
Returns the memory address of a procedure.
1212
<<>>=={{fbdoc item="keyword" value="KeyPgOpAt|Operator @ (Address of)"}}==
1313
Returns the memory address of a variable, object or procedure.

‎doc/manual/cache/CatPgProgrammer.wakka‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -117,16 +117,6 @@
117117
{{fbdoc item="keyword" value="ProPgConditionalCompilation|Conditional Compilation"}}
118118
{{fbdoc item="keyword" value="ProPgMacros|Macros"}}
119119

120-
{{fbdoc item="section" value="Technical Articles"}}
121-
{{fbdoc item="keyword" value="KeyPgAsm|Inline ASM"}}
122-
{{fbdoc item="keyword" value="ProPgCruntime|C Standard Library Functions"}}
123-
{{fbdoc item="keyword" value="ProPgFileIO|File I/O with FreeBASIC"}}
124-
{{fbdoc item="keyword" value="ProPgDynamicMemory|Dynamic memory management with FreeBASIC"}}
125-
{{fbdoc item="keyword" value="ProPgRecursionIteration|Replace Recursion with Iteration"}}
126-
{{fbdoc item="keyword" value="ProPgObjectRtti|OBJECT built-in and RTTI info"}}
127-
{{fbdoc item="keyword" value="ProPgDataExecutable|Embed and Access binary Data in Executable"}}
128-
{{fbdoc item="keyword" value="ProPgUseNewDelete|Use Implicit / Overload New([]) and Delete([]) Operators with Inheritance Polymorphism"}}
129-
130120
{{fbdoc item="section" value="Other Topics"}}
131121
(And topics that need to get placed elsewhere)
132122
{{fbdoc item="keyword" value="CptAscii|ASCII"}}
@@ -137,6 +127,17 @@
137127
{{fbdoc item="keyword" value="CatPgDddefines|Intrinsic Defines"}}
138128
{{fbdoc item="keyword" value="ProPgIdentifierLookup|Identifier Look-ups in namespaces and types"}}
139129

130+
{{fbdoc item="section" value="Technical Articles"}}
131+
{{fbdoc item="keyword" value="KeyPgAsm|Inline ASM"}}
132+
{{fbdoc item="keyword" value="ProPgCruntime|C Standard Library Functions"}}
133+
{{fbdoc item="keyword" value="ProPgFileIO|File I/O with FreeBASIC"}}
134+
{{fbdoc item="keyword" value="ProPgDynamicMemory|Dynamic memory management with FreeBASIC"}}
135+
{{fbdoc item="keyword" value="ProPgRecursionIteration|Replace Recursion with Iteration"}}
136+
{{fbdoc item="keyword" value="ProPgObjectRtti|OBJECT built-in and RTTI info"}}
137+
{{fbdoc item="keyword" value="ProPgDataExecutable|Embed and Access binary Data in Executable"}}
138+
{{fbdoc item="keyword" value="ProPgUseNewDelete|Use Implicit / Overload New([]) and Delete([]) Operators with Inheritance Polymorphism"}}
139+
{{fbdoc item="keyword" value="ProPgEmulateTlsTp|Emulate a TLS (Thread Local Storage) and a TP (Thread Pooling) feature"}}
140+
140141
NOTE: Existing ""CatPg"" pages should be recreated as ""ProPg"" pages providing a general overview to the grouping of keywords.
141142
>>::c::
142143

‎doc/manual/cache/KeyPgAny.wakka‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,9 @@ The ##**Any**## keyword is used as a placeholder for a type or value in various
1616
##//or//##
1717
[[KeyPgOpPlacementNew|New(address)]] [[DataType|DataType]] [//count//] **{ Any }**
1818
##//or//##
19-
[[KeyPgInstr|Instr]]|[[KeyPgInstrrev|InstrRev]] ( //string//, **Any** //substring// )
19+
[[KeyPgInstr|Instr]]|[[KeyPgInstrrev|InstrRev]] ( //identifier//, **Any** //substring// )
20+
##//or//##
21+
[[KeyPgOpProcptr|Procptr]] ( //identifier//, [[[KeyPgVirtual|Virtual]]] **Any** )
2022
##
2123
{{fbdoc item="desc"}}
2224
- Pointers:
@@ -47,6 +49,9 @@ The ##**Any**## keyword is used as a placeholder for a type or value in various
4749

4850
- ""Instr/InstrRev"":
4951
**##Any##** can be used with ##[[KeyPgInstr|Instr]]## or ##[[KeyPgInstrrev|InstrRev]]## as a qualifier for the ##//substring//## parameter, to indicate that any individual character in it may be matched.
52+
53+
- Procptr:
54+
**##Any##**, ie any procedure signature, does not induce any particular selection (compared to its non-use), but just allows for writing ##[[KeyPgOpProcptr|Procptr]]## always with 2 arguments.
5055

5156
{{fbdoc item="ex"}}
5257
{{fbdoc item="filename" value="examples/manual/misc/any.bas"}}%%(freebasic)

‎doc/manual/cache/KeyPgCondWait.wakka‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,14 @@ Stops execution of current thread until some condition becomes true
2222

2323
**Note:** It is a good habit to use ##**Condwait**## in a protected way against eventual spurious wakeups.
2424
For that, ##**Condwait**## is put within a loop for checking that a Boolean predicate is indeed true (predicate set true by another thread just before executing ##[[KeyPgCondSignal|Condsignal]]## or ##[[KeyPgCondBroadcast|Condbroadcast]]##) when the thread has finished waiting:
25-
##While predicate <> true : Condwait(//handle//, //mutex//) : Wend [ : predicate = false ]##
25+
signal-caller:
26+
##predicate = true
27+
Condsignal(//handle//)##
28+
waiting-called:
29+
##While predicate <> true
30+
Condwait(//handle//, //mutex//)
31+
Wend
32+
predicate = false##
2633
the loop can terminate only when the predicate is true.
2734
On the other hand, if the predicate is already true before the thread reaches the loop, ##**Condwait**## is downright skipped (allowing to take into account a case of ##[[KeyPgCondSignal|Condsignal]]## or ##[[KeyPgCondBroadcast|Condbroadcast]]## that would have been lost otherwise, because prematurely executed in a second thread before the first thread is really waiting for this).
2835
See example below for detailed coding.

‎doc/manual/cache/KeyPgOpProcptr.wakka‎

Lines changed: 148 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,40 @@
1-
{{fbdoc item="title" value="Operator PROCPTR (Procedure pointer)"}}----
2-
Returns the address of a procedure
1+
{{fbdoc item="title" value="Operator PROCPTR (Procedure pointer and vtable index)"}}----
2+
Returns the address of any procedure, and the index in the vtable for a virtual/abstract member procedure.
33

44
{{fbdoc item="syntax"}}##
5-
[[KeyPgDeclare|declare]] [[KeyPgOperator|operator]] **Procptr** ( [[KeyPgByref|byref]] //identifier// [[KeyPgAs|as]] //proctype// [, //proctype// ] ) [[KeyPgAs|as]] //proctype// [[KeyPgPtr|ptr]]
5+
[[KeyPgDeclare|declare]] [[KeyPgOperator|operator]] **Procptr** ( [[KeyPgByref|byref]] //identifier// [[KeyPgAs|as]] //proctype// [, [[KeyPgAny|any]]|//user_proctype// ] ) [[KeyPgAs|as]] //internal_proctype// [[KeyPgPtr|ptr]]
6+
[[KeyPgDeclare|declare]] [[KeyPgOperator|operator]] **Procptr** ( [[KeyPgByref|byref]] //identifier// [[KeyPgAs|as]] //proctype//, virtual [ [[KeyPgAny|any]]|//user_proctype// ] ) [[KeyPgAs|as]] [[KeyPgInteger|integer]]
67
##
78
{{fbdoc item="usage"}}##
8-
//result// = **Procptr** ( //identifier// [, //proctype// ] )
9+
//result// = **Procptr** ( //identifier// [, [virtual] [any|//user_proctype//] ] )
910
##
1011
{{fbdoc item="param"}}
1112
##//identifier//##
1213
A procedure identifier.
13-
##//proctype//##
14-
Any type of procedure (sub/function).
14+
##//user_proctype//##
15+
Any user type of procedure (sub/function, static/member, normal/virtual).
16+
(##//internal_proctype//## has a supplementary first parameter ##byref as udt_name## only for the member procedures)
1517

1618
{{fbdoc item="ret"}}
17-
Returns the address of the procedure.
19+
Returns the address of any procedure (first syntax), or the index in the vtable for a virtual/abstract member procedure (second syntax with additional qualifier ##virtual##).
20+
(##any##, ie any procedure signature, does not induce any particular selection (compared to its non-use), but just allows for writing ##**Procptr**## always with 2 arguments)
1821

1922
{{fbdoc item="desc"}}
20-
This operator returns the address of a ##[[KeyPgSub|Sub]]## or ##[[KeyPgFunction|Function]]## procedure.
23+
First syntax:
24+
""-"" This operator returns the address of a ##[[KeyPgSub|Sub]]## or ##[[KeyPgFunction|Function]]## static/member procedure or member operator.
25+
""-"" The type of the return value corresponds to the internal signature of the procedure (user signature, plus a supplementary first parameter ##byref as udt_name## for a member procedure) .
26+
Second syntax (with qualifier ##virtual##):
27+
""-"" This operator returns the zero based index in the vtable for a virtual/abstract member procedure or member operator.
28+
""-"" In case of overridden member procedure (polymorphism), the vtable index allows access, from the vtable of the used instance, to the address of the most derived override member procedure.
29+
30+
When using the ##//user_proctype//## argument, ##**Procptr**## syntax allows of getting procedure pointer or vtable index for based on parameter types (including sub/function type and return type if any).
31+
This makes it possible to explicitly specify the right procedure to resolve procedure overloads, or make a check for parameter types (including sub/function type and return type if any) on non-overloaded procedures.
2132

22-
When using the two arguments ##PROCPTR( //identifier//, //type// )## syntax, this allows of getting procedure pointer for based on parameter types (excluding sub/function type and return type if any).
23-
This makes it possible to explicitly specify the right procedure to resolve procedure overloads, or make a check for parameter types (excluding sub/function type and return type if any) on non-overloaded procedures.
33+
##[[KeyPgOpAt|Operator @ (Address of)]]##, when used with procedures, behaves the same as the first ##**Procptr**## syntax without second argument.
2434

25-
##[[KeyPgOpAt|Operator @ (Address of)]]##, when used with procedures, behaves the same as ##**Procptr**## without its optional argument (the second).
35+
**Note:**
36+
""-"" If the procedure member is abstract, then ## **Procptr** ( //identifier// [, any|//user_proctype// ] ) ## returns a null procedure pointer of the member procedure call signature (##//internal_proctype//##).
37+
""-"" If there is no vtable entry (or no vtable at all) then ## **Procptr** ( //identifier// , virtual [any|//user_proctype//] ) ## returns the special value of ##-1##.
2638

2739
{{fbdoc item="ex"}}
2840
{{fbdoc item="filename" value="examples/manual/operator/procptr.bas"}}%%(freebasic)
@@ -63,12 +75,134 @@ Var s2 = ProcPtr( s, Sub( ByVal i As Integer ) )
6375
's1 = ProcPtr( s )
6476
'Dim s2 As Sub( Byval i As Integer)
6577
's2 = ProcPtr( s )
78+
%%
79+
{{fbdoc item="filename" value="examples/manual/operator/procptr3.bas"}}%%(freebasic)
80+
' Since fbc 1.10.0, ProcPtr supports the member procedures/operators with various syntaxes
81+
82+
Type UDT Extends Object
83+
Dim As String s1
84+
Dim As String s2
85+
Declare Virtual Sub test()
86+
Declare Virtual Operator Cast() As String
87+
End Type
88+
89+
Sub UDT.test()
90+
Print This.s1
91+
End Sub
92+
93+
Operator UDT.Cast() As String
94+
Return This.s2
95+
End operator
96+
97+
Var testPtr1 = Procptr(UDT.test)
98+
Var testPtr2 = Procptr(UDT.test, Any)
99+
Var testPtr3 = Procptr(UDT.test, Sub())
100+
101+
Dim As Function(Byref As UDT) As String castPtr1 = Procptr(UDT.cast)
102+
Dim As Function(Byref As UDT) As String castPtr2 = Procptr(UDT.cast, Any)
103+
Dim As Function(Byref As UDT) As String castPtr3 = Procptr(UDT.cast, Function() As String)
104+
105+
Var testIndex1 = Procptr(UDT.test, Virtual)
106+
Var testIndex2 = Procptr(UDT.test, Virtual Any)
107+
Var testIndex3 = Procptr(UDT.test, Virtual Sub())
108+
109+
Dim As Integer castIndex1 = Procptr(UDT.cast, Virtual)
110+
Dim As Integer castIndex2 = Procptr(UDT.cast, Virtual Any)
111+
Dim As Integer castIndex3 = Procptr(UDT.cast, Virtual Function() As String)
112+
113+
Print testPtr1 '' absolue address value of UDT.test pointer
114+
Print testPtr2 '' absolue address value of UDT.test pointer
115+
Print testPtr3 '' absolue address value of UDT.test pointer
116+
Print
117+
118+
Print castPtr1 '' absolue address value of UDT.Cast pointer
119+
Print castPtr2 '' absolue address value of UDT.Cast pointer
120+
Print castPtr3 '' absolue address value of UDT.Cast pointer
121+
Print
122+
123+
Print testIndex1 '' vtable index of UDT.test
124+
Print testIndex2 '' vtable index of UDT.test
125+
Print testIndex3 '' vtable index of UDT.test
126+
Print
127+
128+
Print castIndex1 '' vtable index of UDT.Cast
129+
Print castIndex2 '' vtable index of UDT.Cast
130+
Print castIndex3 '' vtable index of UDT.Cast
131+
Print
132+
133+
Dim As UDT u
134+
u.s1 = "Virtual Sub test()"
135+
u.s2 = "Virtual Operator Cast() As String"
136+
137+
testPtr1(u) '' execute u.test() through its procedure pointer
138+
testPtr2(u) '' execute u.test() through its procedure pointer
139+
testPtr3(u) '' execute u.test() through its procedure pointer
140+
Print
141+
142+
Print castPtr1(u) '' execute Cast(UDT, u) through its procedure pointer
143+
Print castPtr2(u) '' execute Cast(UDT, u) through its procedure pointer
144+
Print castPtr3(u) '' execute Cast(UDT, u) through its procedure pointer
145+
Print
146+
147+
Cptr(Sub(Byref As UDT), Cptr(Any Ptr Ptr Ptr, @u)[0][testIndex1])(u) '' execute u.test() through its vtable index
148+
Cptr(Sub(Byref As UDT), Cptr(Any Ptr Ptr Ptr, @u)[0][testIndex2])(u) '' execute u.test() through its vtable index
149+
Cptr(Sub(Byref As UDT), Cptr(Any Ptr Ptr Ptr, @u)[0][testIndex3])(u) '' execute u.test() through its vtable index
150+
Print
151+
152+
Print Cptr(Function(Byref As UDT) As String, Cptr(Any Ptr Ptr Ptr, @u)[0][castIndex1])(u) '' execute Cast(UDT, u) through its vtable index
153+
Print Cptr(Function(Byref As UDT) As String, Cptr(Any Ptr Ptr Ptr, @u)[0][castIndex2])(u) '' execute Cast(UDT, u) through its vtable index
154+
Print Cptr(Function(Byref As UDT) As String, Cptr(Any Ptr Ptr Ptr, @u)[0][castIndex3])(u) '' execute Cast(UDT, u) through its vtable index
155+
Print
156+
157+
Sleep
158+
%%
159+
{{fbdoc item="filename" value="examples/manual/operator/procptr4.bas"}}%%(freebasic)
160+
' Since fbc 1.10.0, ProcPtr allows to access the vtable index of a virtual/abstract member procedure/operator
161+
162+
Type Parent Extends Object
163+
Declare Abstract Sub test()
164+
Declare Virtual Operator Cast() As String
165+
End Type
166+
167+
Operator Parent.Cast() As String
168+
Return "Parent.Cast() As String"
169+
End Operator
170+
171+
Type Child Extends Parent
172+
Declare Virtual Sub test() '' or Declare Sub test()
173+
Declare Virtual Operator Cast() As String '' or Declare Operator Cast() As String
174+
End Type
175+
176+
Sub Child.test()
177+
Print "Child.test()"
178+
End Sub
179+
180+
Operator Child.Cast() As String
181+
Return "Child.Ccast() As String"
182+
End Operator
183+
184+
Dim As Parent Ptr p = New Child
185+
p->test()
186+
Print Cast(Parent, *p) '' or Print *p
187+
Print
188+
189+
#define VirtProcPtr(instance, procedure) CPtr(TypeOf(ProcPtr(procedure)), _ '' pointer to virtual procedure
190+
CPtr(Any Ptr Ptr Ptr, @(instance)) _ '' (the most derived override that exists)
191+
[0][ProcPtr(procedure, Virtual)])
192+
193+
VirtProcPtr(*p, Parent.test)(*p) '' execute p->test() through its vtable index
194+
Print VirtProcPtr(*p, Parent.Cast)(*p) '' execute Cast(Parent, *p) through its vtable index
195+
Print
196+
197+
Delete p
198+
Sleep
66199
%%
67200
{{fbdoc item="ver"}}
201+
- Before fbc 1.10.0, the member procedures/operators were not supported.
68202
- Before fbc 1.09.0, the second argument (the optional) was not supported.
69203

70204
{{fbdoc item="lang"}}
71-
- Not available in the //[[CompilerOptlang|-lang qb]]// dialect unless referenced with the alias ##**""__Procptr""**##.
205+
- Not available in the //[[CompilerOptlang|-lang qb]]// dialect unless referenced with the alias ##**""__Procptr""**## (but does not support qualifier ##virtual##).
72206

73207
{{fbdoc item="diff"}}
74208
- New to ""FreeBASIC""
@@ -77,6 +211,8 @@ Var s2 = ProcPtr( s, Sub( ByVal i As Integer ) )
77211
- ##[[KeyPgSub|Sub]]##
78212
- ##[[KeyPgOpVarptr|Varptr]]##
79213
- ##[[KeyPgOpStrptr|Strptr]]##
214+
- ##[[KeyPgAny|Any]]##
215+
- ##[[KeyPgVirtual|Virtual]]
80216
- [[ProPgPointers|Pointers]]
81217

82218
{{fbdoc item="back" value="CatPgOpPoint|Pointer Operators"}}{{fbdoc item="back" value="CatPgOperators|Operators"}}

‎doc/manual/cache/KeyPgOpenCons.wakka‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@ Opens the console's standard input (//stdin//) or output (//stdout//) streams fo
2727

2828
To open both the //stdin// and //stdout// streams for file operations, a process must use multiple //file numbers//.
2929

30+
The normal screen commands, such as ##[[KeyPgColor|Color]]## and ##[[KeyPgLocate|Locate]]##, do not work in this mode, because they do not accept a file number.
31+
The ##[[KeyPgTab|TAB]]## keyword, regardless of the given column number, is always interpreted as a simple comma (##,##) (next output will take place at the next 14 column boundary).
32+
3033
The error code returned by ##**Open Cons**## can be checked using ##[[KeyPgErr|Err]]## in the next line. The function version of ##**Open Cons**## returns directly the error code as a 32 bit ##[[KeyPgLong|Long]]##.
3134

3235
**Warning:** Presently, ##**Open Cons**## does not work as described above. Without any //file mode// specifier, a runtime error 1 (illegal function call) occurs. With the ##[[KeyPgInputfilemode|Input]]## //file mode// specifier, the only input mode is well supported. But with the ##[[KeyPgOutput|Output]]## //file mode// specifier, input and output modes are simultaneously supported.

‎doc/manual/cache/KeyPgOpenErr.wakka‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ Opens both the standard input (//stdin//) and standard error (//stderr//) stream
2424
##stderr## is an output stream different from ##stdout## allowing error messages to be redirected separately from the main console output.
2525

2626
The normal console commands, such as ##[[KeyPgColor|Color]]## and ##[[KeyPgLocate|Locate]]##, do not work in this mode, because they do not accept a file number.
27+
The ##[[KeyPgTab|TAB]]## keyword, regardless of the given column number, is always interpreted as a simple comma (##,##) (next output will take place at the next 14 column boundary).
2728

2829
The ##[For Input|Output]## ##//mode//## is allowed for compatibility, but is ignored.
2930

‎doc/manual/cache/KeyPgOpenScrn.wakka‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{{fbdoc item="title" value="OPEN SCRN"}}----
2-
Opens the console directly for input and output as a file
2+
Opens the screen directly for input and output as a file
33

44
{{fbdoc item="syntax"}}##
55
**[[KeyPgOpen|Open]] Scrn** [for //mode//] [[KeyPgAs|as]] [#]//filenumber// [[KeyPgAs|as]] [[KeyPgLong|long]]
@@ -19,11 +19,11 @@ Opens the console directly for input and output as a file
1919
A 32 bit ##[[KeyPgLong|Long]]##: a zero (##0##) is returned if ##**Open Scrn()**## completed successfully, otherwise a non-zero value is returned to indicate failure.
2020

2121
{{fbdoc item="desc"}}
22-
This command opens the console for both input and output as a file, allowing to read/write from/to it with normal file commands.
22+
This command opens the screen (in text or graphics screen mode) for both input and output as a file, allowing to read/write from/to it with normal file commands.
2323

24-
This command may use direct access to the console for speed in some implementations, so it should not be used when the input / output is required to be redirected or piped with OS commands.
24+
This command may use direct access to the screen for speed in some implementations, so it should not be used when the input / output is required to be redirected or piped with OS commands.
2525

26-
The normal console commands, such as ##[[KeyPgColor|Color]]## and ##[[KeyPgLocate|Locate]]##, do not work in this mode, because they do not accept a file number.
26+
The normal screen commands, such as ##[[KeyPgColor|Color]]## and ##[[KeyPgLocate|Locate]]##, do not work in this mode, because they do not accept a file number.
2727

2828
The ##[For Input|Output]## clause is allowed for compatibility, but is ignored.
2929

0 commit comments

Comments
 (0)