Wiki improvements

[fxm]

No problem, thanks. I see now that it is good again.
(I thought maybe it was a backup in progress)

[fxm]

Referring to viewtopic.php?p=274317#p274317:

Remaining articles or parts of articles from the above post not integrated in the Programmer's Guide (or elsewhere in the Wiki)

• 11. How to Manage FB Reusable Procedures by Including Source Modules (vs. compiled modules):
  - not integrated at all.
• 13. How and Why to make Abstraction by Object Encapsulation, with FB Syntax in UDTs (basics):
  - not integrated, but new and elementary paragraph 'Encapsulation' added to 'Programmer's Guide / User Defined Types / Member Access Rights' becoming 'Programmer's Guide / User Defined Types / Member Access Rights and Encapsulation'.
• 17. How to Replace Any Recursion with Simple Iteration or Unlimited Iteration with its Own Stack, in FB:
  - only not integrated paragraph: '2) Replace Recursion with Iteration'.
• 18. How FB supports Sub-Type Polymorphism, demonstrated by Emulation very Close to Real Operating:
  - only not integrated paragraphs: '4) Sub-type polymorphism mechanism demonstrated by emulation very close to real operating' and '5) Same example, with the true code and emulation code, but both nested in a single code for easier comparison'.
• 19. How using RTTI from FB built-in OBJECT to extract Typename and those of all Bases of an instance:
  - not integrated except paragraph: '1) How are chained the entities: object instance, vptr, vtabl (vtable), and RTTI info'.

I think those above topics do not have to be integrated into the Programmer's Guide, other than maybe the substance (implementation under the hood of vptr, vtbl, rtti info, ...) of the articles 18. How FB supports Sub-Type Polymorphism, demonstrated by Emulation very Close to Real Operating and 19. How using RTTI from FB built-in OBJECT to extract Typename and those of all Bases of an instance which could perhaps feed a new page (OBJECT built-in and RTTI info) in Hacking on FreeBASIC / Compiler internals.

• (in this case, the 'Mechanism under the hood for inheritance polymorphism' paragraph of the Programmer's Guide / User Defined Types / Inheritance Polymorphism would be moved and replaced with a simple link to this Hacking on FreeBASIC / Compiler internals / OBJECT built-in and RTTI info new page more complete)

What do you think, admins and users?

[coderJeff]

fxm, the articles are excellent, detailed, and comprehensive. They deserve to go somewhere....
I feel like some articles are for the advanced user for sure, but don't necessarily need to be hidden in the developer / hacking page.

How about adding a 'Technical Articles' section just before 'Other Topics'?

I think there's a couple of existing 'Other Topics' that could move to a 'Technical Articles' kind of classification.

[fxm]

Good idea.

In this new 'Technical Articles' section, I propose to transfer the following existing pages:
- Inline ASM (which is just a link to KeyPgAsm)
- C Standard Library Functions
- File I/O in FreeBASIC
- Dynamic memory management in FreeBASIC
plus add other new pages like the ones proposed:
+ Manage Reusable Procedures by Including Source vs Compiled Modules (will issued from article 11) -> see [edit] below
+ Replace Recursion with Iteration (will issued from article 17)
+ OBJECT built-in and RTTI info (will issued from article 18 and article 19)

There are still some fairly technical pages like for examples:
- Constructors, '=' Assignment-Operators, and Destructors (advanced, part #1)
- Constructors, '=' Assignment-Operators, and Destructors (advanced, part #2)
- Critical Sections FAQ
which I prefer to leave in their places because they fit well with the section where they are.


[edit]
After some thought, I think the Manage Reusable Procedures by Including Source vs Compiled Modules page would be better at the end of the Programmer's Guide / Source Files section (after Source Files (.bas), Header Files (.bi) and Using Prebuilt Libraries pages)

See now the updated Programmer's Guide page.
(the 3 new 'in progress ...' pages will be filled in one after the other these days)

[dodicat]

fxm.
Regarding the OBJECT built-in RTTI info.
I have been experimenting passing this info to other modules via text file and library file.
Text file of course cannot receive this info or indeed any pointer message.
A lib file can transmit a pointer address and another module which can successfully use this address, e.g. passing the address of an array to be used by the module, but the RTTI info passed is not valid.
It seems to me that the RTTI info is easily lost.
Simple example, method2 fails.

Code: Select all

 

Type shape Extends Object
    As Long x,y
    As Long r
    As Ulong clr
End Type

Type circ Extends shape
    Declare Sub show
End Type

Type square Extends shape
    Declare Sub show
End Type


Sub circ.show
    Circle(x,y),r,clr
End Sub

Sub square.show
    Line(x,y)-(x+r,y+r),clr,b
End Sub


Dim As circ c(1 To 2)
Randomize 1
For n As Long=1 To 2
    With c(n)
        .x=100+Rnd*600
        .y=100+Rnd*400
        .r=20+Rnd*100
        .clr=Rnd*Rgb(0,0,0)
    End With
Next n

Dim As square s(1 To 1)
s(1).x=100+Rnd*600
s(1).y=100+Rnd*400
s(1).r=20+Rnd*100
s(1).clr=Rnd*Rgb(0,0,0)


Dim As shape Ptr x(1 To 3)

x(1)=@c(1)
x(2)=@c(2)
x(3)=@s(1)

Dim As shape save(1 To 3) 'dim as object fails completely
For n As Long=1 To 3
    save(n)=*x(n) '<--- information gets lost?
Next n


Screenres 800,600,32
#macro method1
For n As Long=1 To 3
    If Cast(Object,*x(n)) Is shape Then Print "shape"
    If Cast(Object,*x(n)) Is circ Then Cast(circ Ptr,x(n))->show:Print "circ"
    If Cast(Object,*x(n)) Is square Then Cast(square Ptr,x(n))->show:Print "square"
    Print
Next
#endmacro

#macro method2
For n As Long=1 To 3
    If Cast(Object,save(n)) Is shape Then Print "shape"
    If Cast(Object,save(n)) Is circ Then Cast(circ Ptr,x(n))->show:Print "circ"
    If Cast(Object,save(n)) Is square Then Cast(square Ptr,x(n))->show:Print "square"
    Print
Next
#endmacro

method1
'method2

Sleep

 

I shall remove this post later so not to clutter the thread.

[fxm]

When you assign a derived-object to a base-object:
save(n)=*x(n)
obviously the member data specific to the derived-type are not copied, but the vptr is not copied either (the run-time of this base-object must not be promoted into a derived-object because this object has been allocated in memory for a based-object and not for a derived-object).

In your specific and very simple example, the derived-type does not add any member data, so the above rule could be broken against the vptr copy.
A simple hack could solve this problem:

Code: Select all

Dim As shape save(1 To 3) 'dim as object fails completely
For n As Long=1 To 3
    save(n)=*x(n) '<--- information vptr lost
    Cptr(Any Ptr Ptr, @save(n))[0] = Cptr(Any Ptr Ptr, x(n))[0]  '<--- hacking copy of vptr
Next n

[dodicat]

Thanks, the hack saves the RTTI.
To pass the methods I still have to use *x(n)
I can now pass the OOP across in a static library.
shapes.bas to be compiled -lib

Code: Select all

'shapes.bas
'compile -lib
type pt extends object
    as long x,y
    as long r
    as ulong clr
end type

type circ extends pt
    declare sub show
end type

type square extends pt
    declare sub show
end type

sub circ.show
    circle(x,y),r,clr
end sub

sub square.show
    line(x,y)-(x+r,y+r),clr,b
end sub

sub savefile(file as string,u() as pt)
    var h=freefile
    open file for binary access write as #h
    put #h, ,u()
    close #h
end sub

dim as circ c(1 to 2)
randomize 1
for n as long=1 to 2
    with c(n)
       .x=100+rnd*600
        .y=100+rnd*400
        .r=20+rnd*100
        .clr=rnd*rgb(0,0,0)
    end with
next n

dim as square s(1 to 1)
        s(1).x=100+rnd*600
        s(1).y=100+rnd*400
        s(1).r=20+rnd*100
        s(1).clr=rnd*rgb(0,0,0)

dim shared as pt  ptr x(1 to 3)

x(1)=@c(1)
x(2)=@c(2)
x(3)=@s(1)

dim shared as pt saveRTTI(1 to 3)
dim shared as pt saveSHAPES(1 to 3)

for n as long=1 to 3
    saveSHAPES(n)=*x(n)
    Cptr(Any Ptr Ptr, @saveRTTI(n))[0] = Cptr(Any Ptr Ptr, x(n))[0]
next n


function size() as long
    return ubound(saveRTTI)
end function

function addressRTTI() as pt ptr
    return @saveRTTI(1)
end function

function addressSHAPES() as pt ptr
    return @saveSHAPES(1)
end function

 

and a test file

Code: Select all

#inclib "shapes"

declare function addressRTTI() as any ptr
declare function addressSHAPES() as any ptr
declare function size() as long

type pt extends object
    as long x,y
    as long r
    as ulong clr
end type

type circ extends pt
    declare sub show
end type

type square extends pt
    declare sub show
end type

screenres 800,600,32
dim as pt ptr a=addressRTTI
dim as pt ptr w=addressSHAPES
dim as long L=size()


for n as long=1 to L
    if *cast(object ptr,a) is pt then print "shape"
    if *cast(object ptr,a) is circ then print "circ":cast(circ ptr,w)->show
    if *cast(object ptr,a) is square then print "square":cast(square ptr,w)->show
    a+=1
    w+=1
    print
next

sleep
 

[fxm]

Good idea.

In this new 'Technical Articles' section, I propose to transfer the following existing pages:
- Inline ASM (which is just a link to KeyPgAsm)
- C Standard Library Functions
- File I/O in FreeBASIC
- Dynamic memory management in FreeBASIC
plus add other new pages like the ones proposed:
+ Manage Reusable Procedures by Including Source vs Compiled Modules (will issued from article 11) -> see [edit] below
+ Replace Recursion with Iteration (will issued from article 17)
+ OBJECT built-in and RTTI info (will issued from article 18 and article 19)

There are still some fairly technical pages like for examples:
- Constructors, '=' Assignment-Operators, and Destructors (advanced, part #1)
- Constructors, '=' Assignment-Operators, and Destructors (advanced, part #2)
- Critical Sections FAQ
which I prefer to leave in their places because they fit well with the section where they are.


[edit]
After some thought, I think the Manage Reusable Procedures by Including Source vs Compiled Modules page would be better at the end of the Programmer's Guide / Source Files section (after Source Files (.bas), Header Files (.bi) and Using Prebuilt Libraries pages)

See now the updated Programmer's Guide page.
(the 3 new 'in progress ...' pages will be filled in one after the other these days)

Done.

[fxm]

Regarding the only remaining article not literally integrated in the Programmer's Guide (viewtopic.php?p=274317#p274317):

• 13. How and Why to make Abstraction by Object Encapsulation, with FB Syntax in UDTs (basics)
  - not integrated literally, but new paragraph 'Encapsulation' (introducing also the abstraction notion) added to 'Programmer's Guide / User Defined Types / Member Access Rights' becoming:
  Programmer's Guide / User Defined Types / Member Access Rights and Encapsulation

=> I think it's enough like that.

From my point of view, I have thus finished everything regarding the integration of the 19 articles in the Programmer's Guide.
What new challenge now (in my skills anyway)?

[coderJeff]

Do you feel confident to remove the 'Work in Progress' from the Programmer's Guide? Something I was never able to do.

From my point of view, I have thus finished everything regarding the integration of the 19 articles in the Programmer's Guide.
What new challenge now (in my skills anyway)?

You should be careful with that open invitation. :)

Can you please critique Object lifetime with reference counting?

[fxm]

Do you feel confident to remove the 'Work in Progress' from the Programmer's Guide?

There are still at least 2 pages (outside of my skills) which are problematic:
- Executables (page to be completed): Imortis has promised to do so when he has free time.
- External Graphics File Formats (page to be filled in): recently I cited counting_pine (viewtopic.php?p=274110#p274110) as having no doubt the skills to do it, but without echo from him.

[fxm]

From my point of view, I have thus finished everything regarding the integration of the 19 articles in the Programmer's Guide.
What new challenge now (in my skills anyway)?

You should be careful with that open invitation. :)

In fact, under this is my own questioning:
How can I make myself useful to the community?

[srvaldez]

Hi fxm :-)
your expert advice is more valuable than gold, Richard D. Clark and Ebben Feagan wrote "A Beginner’s Guide to FreeBasic" https://sourceforge.net/projects/fbeginner/ perhaps you might be interested in writing an Advanced version

[coderJeff]

Hey, fxm. Have you seen MissingDocs? Maybe you can sort that out. Or at least put notes on what kind user (expert) is needed to clean it up.

The finishing, in my opinion, is a hard step to complete. It's not for everyone. I think you probably have a very good understanding of the level of completion of the documentation. Next is to make a list of all the things that need to get done next. Either by yourself, or to pass on to another person (because maybe you've had enough of it).

I feel like we're really close to manual milestone. Nothing that I've done of course, as you have brought us all the way the way there I think over last couple years.

[fxm]

Maybe first a little break from the documentation!