Pull Requests

[paul doe]

Just my two cents:

...
But before make any decision: I hope that the './fbc-int/*.bi' files can be a way to share fbc internals with users & casual developers. I also hope that we are not required to support this exact API forever, as that could impede development. So I will say this, './fbc-int/*.bi' files will be accurate for the current version of fbc. Users can make use of these includes if they choose. And developers reserve the right to change at any time. Internals may change as needed for development. I think that's fair.
...

Indeed it is. Since the API is meant to expose internals of the compiler, its volatility is to be expected. However, I'd rather prefer to code something like:

Code: Select all

dim as Fb.ArrayDescriptor _
  arrayDescriptorFor( a() )

than resorting to brittle, ugly hacks. Also, abstracting internals such as array descriptors, string descriptors, object vtables and the dispatch mechanism to structures gives developers a nice compromise when exposing them (since you can always resort to unions, pretty much like the Fb.Image descriptor does right now). The API might be volatile, but it nonetheless shields the codebase from change at the low level.

...
1) A while back you asked me about wiki location for the fbc.FBARRAY structure. I didn't really have a good answer or reason that it should only be in developer documentation, or that it should be added to user documentation. We don't really have any rules for what should be considered developer only content. Anyway, you already did the work, so it's OK with me that it is featured in user documentation. If ever find that it causes too much confusion for users, just move it back to developer documentation.
...

Regarding this, I'm of the opinion that documentation should be comprehensive (the FreeBasic Manual is arguably one of the best Open Source documentations out there; just look at the SDL2 docs -which is an industry standard- or the MSDN docs to see what I mean).

Everybody knows (or should know) its limits, so while these pages could be on the 'Developer Only' section, a link should be provided from the relevant, 'standard' pages (such as a link to the array descriptor docs right on the page that explains arrays), under an 'advanced' topic of sorts.

[Juergen Kuehlwein]

Jeff,

With this set of operators, you can do almost everything i can think of. #REDEF could be dropped. Should i try to code this, or would you like to proceed as outlined in your last post?

Referring to post #8 and #9, what should i do?
In the meantime i have running code for a pp syntax like this: #<pp operator># or #<pp operator>(<literal string>)#,
e.g.: #count#, #leftof(x)#, #is(any)#


JK

[Juergen Kuehlwein]

Jeff,

i closed PR #191 in favour of PR #211, which takes a more generic approach as requested. This set of new pp operators makes a lot of new things possible and it is expandable.


- #ucase#: "stringize uppercase" which makes case insensitive comparisons (#if #ucase#p = "ABC") inside the preprocessor statements possible.

- #count#: count number of arguments in a variadic parameter by counting commas. The returned number is the number of commas + 1. Even an empty paramter counts as 1.

- #join#: concatenate spaces separated parts of a parameter, i.e. remove all spaces

- #split#: insert a comma between space(s) separated parts of a parameter. Preserve space(s) in literal strings and in expressions enclosed in brackets. This may change the number of parameters. In case there are no spaces, the original paramter is returned.

- #left_of("token")#: return everything to the left of "token", where "token" must be a literal string (without enclosing quotes). In other words, cut before "token".

- #rigth_of("token")#: return everything after "token", where "token" must be a literal string (without enclosing quotes). In other words, cut after "token".

- #is("token")#: return 1, if parameter = "token", where "token" must be a literal string (without enclosing quotes). The original parameter is returned otherwise.

All comparisons ("token") are case insensitive, because BASIC is a case insensitive language


JK

[Juergen Kuehlwein]

Regarding "POKE ANY"

i asked for adding POKE ANY in order to have a high level syntax for filling a block of memory of arbitrary length. POKE ANY seems a natural choice, because POKE already stands for filling memory and "ANY" stands for something undefined. So POKE ANY does not exactly the same, but something similar as the already existing syntax, it requires an additional (length) parameter, which otherwise is implied by the datatype.

@fxm

But if we ever keep it, I wish it had the same type of declaration as the current POKE:
declare sub poke any ( byval pdst as any ptr, byval psrc as any ptr, byval bytes as uinteger )
Consequently 'poke any, pdst, psrc, bytes' would act as 'fb_memmove(byval pdst, byval psrc, bytes)'.

???

the current POKE is (as per wiki page: https://www.freebasic.net/wiki/wikka.ph ... =KeyPgPoke):

Syntax:
declare sub Poke ( byval address as any ptr, byref value as ubyte )
declare sub Poke ( datatype, byval address as any ptr, byref value as datatype )

To my understanding the current POKE declares the source parameter BYREF AS datatype, while POKE ANY declares the source parameter BYVAL AS ANY PTR. So in order to make the syntax consistent, POKE ANY should have the source parameter declared BYREF AS datatype. But this declaration doesn´t allow for passing pointers, which is the point of POKE ANY - so the declaration must stay BYVAL AS ANY PTR.


@Jeff

Obviously POKE ANY should not break, when fbc-int/memory.bi is included! I would remove #undef, because having slightly different declarations side by side in fb and fbc namespace might be confusing, but doesn´t break anything. Replacing one declaration by a different one is bound to break code.


JK

[fxm]

@JK

But if we ever keep it, I wish it had the same type of declaration as the current POKE:
declare sub poke any ( byval pdst as any ptr, byval psrc as any ptr, byval bytes as uinteger )
Consequently 'poke any, pdst, psrc, bytes' would act as 'fb_memmove(byval pdst, byval psrc, bytes)'.

???

By specifying the ByVal keyword in front of an argument to a ByRef parameter, an address (usually stored in a pointer) can be passed directly as-is, forcing the ByRef parameter to reference the same memory location which the address pointed to.

Syntax:
declare sub Poke ( byval address as any ptr, byref value as ubyte )
declare sub Poke ( datatype, byval address as any ptr, byref value as datatype )

To my understanding the current POKE declares the source parameter BYREF AS datatype, while POKE ANY declares the source parameter BYVAL AS ANY PTR. So in order to make the syntax consistent, POKE ANY should have the source parameter declared BYREF AS datatype. But this declaration doesn´t allow for passing pointers, which is the point of POKE ANY - so the declaration must stay BYVAL AS ANY PTR.

I do not agree:
The classic Poke declares its address parameter BYVAL, while the new Poke Any currently declares its addresses BYREF.

[Juergen Kuehlwein]

@fxm,

i was talking of the source parameter, but anyway - yes - you are right, current fbc 1.08 declares destination and source parameter BYREF for POKE ANY, which is not, what i intended.

Running tests with my original PR and what has been merged to master, there are differences (Please note that this is not what POKE ANY is intended for, but it demonstrates the problem):

Code: Select all

dim x as long = 10
dim y as long = 22

'original PR:
poke any, @x, @y, 4                                   'works
poke any, byval @x, byval @y, 4                       'doesn´t compile
poke any, x, y, 4                                     'doesn´t work
print y

sleep

Code: Select all

dim x as long = 10
dim y as long = 22

'fbc 1.08:
poke any, @x, @y, 4                                   'doesn´t work
poke any, byval @x, byval @y, 4                       'works
poke any, x, y, 4                                     'works
print y

sleep

So we both agree on the fact, that it should be BYVAL AS ANY PTR for the source and destination parameter. I made a mistake in assuming that the changes to my PR didn´t affect parameter passing. Maybe this should be changed, i wouldn´t drop POKE ANY.


JK

[fxm]

OKAY.
(I think in each of your two examples above, 'print y' should be replaced with 'print x', because '@x' is the destination address and '@y' is the source address)

[MrSwiss]

RE: proposed pp operators:

#split#: insert a comma between space(s) separated parts of a parameter. Preserve space(s) in literal strings and in expressions enclosed in brackets. This may change the number of parameters. In case there are no spaces, the original paramter is returned.

The name (split) implies something different than what's been done by it, in effect.
Then, the way it's explained tells that it is a "hard coded" (aka: single use) operator.

I'd call it #replace(s, f, w)# with 3 parameters, where:
s = source (most likely string), f = search [F]or character, w = replace [W]ith character
this then is far more versatile, than some "hard coded" operator.
(just prepending a comma (without removing space) makes little sense, IMO)

[Juergen Kuehlwein]

@fxm,

shame on me, it must be "print x" (typo ..., not my day today it seems)


@MrSwiss,

i agree, if it were a generic string processing function. In this case it is a preprocessor operator for a specific purpose. The purpose of it is to do the opposite of #join#. We can discuss the naming of course, i wanted to find short names.

Depending on what you would like to do with macros, additional operators like the one you proposed are of course possible with the method i propose in my PR. The set of new operators i would like to add in this PR, is tailored to meet the needs for language extensions i have in mind. Jeff asked for a more generic approach, so i re-coded it in a way it could easily be expanded.


JK

[MrSwiss]

@JK,

We can discuss the naming of course, i wanted to find short names.

I'm also in favour of short names but, they should still be "telling it".
How about #mkparam# or #param#: make single/multiple parameters, from a single string.
If it needs to be static, only.

I'd like to keep "split" as "reserved", for future use (a real splitter, maybe).

[Juergen Kuehlwein]

I admit i´m not to 100% happy with "#split#" myself, but what else would be short and "telling" enough: cut, break, divide, token(ize) ?

[fxm]

#attach# / #detach# ?

[Juergen Kuehlwein]

#attach# / #detach# ?

nice one! I like the combination, one for putting it together and the other one for putting it apart. Let´s see, what Jeff says about all of it.