POV-Ray : Newsgroups : povray.pov4.discussion.general : Thoughts on 'keyword_status()' functionality for v4.0. Server Time
29 Mar 2024 03:39:52 EDT (-0400)
  Thoughts on 'keyword_status()' functionality for v4.0. (Message 1 to 7 of 7)  
From: William F Pokorny
Subject: Thoughts on 'keyword_status()' functionality for v4.0.
Date: 26 Mar 2023 01:58:10
Message: <641fdef2$1@news.povray.org>
In working recently with the povr fork to restore v3.7, v3.6 and prior, 
ID only checking behavior with the #ifdef(), #ifndef() and defined() 
keywords, the subject of keyword status checking in SDL came up again.

I've looked at the reserved word warning code in v3.8 and on.

Plus I've been thinking about the bigger picture of actual keywords, 
possible keywords, stand in internal keywords used for other purposes 
and functions. We have too the ini keywords and flags.

As an initial proposal thinking about a new 'keyword_status()' function 
passed strings like "tau". It would return the following values for the 
status of various strings in answer to what meanings are relative to the 
version of code being run.

-5 ==> ini keyword (cmd line flag ?) setting removed.
-4 ==> lower case, shipped function looking like something inbuilt.
-3 ==> deleted inbuilt function formerly defined in functions.inc.
-2 ==> pseudo / hidden keyword removed.
-1 ==> formerly visible and usable keyword removed.
  0 ==> not now and never a keyword. Good to go.
+1 ==> active SDL keyword.
+2 ==> pseudo / hidden keywords active or potentially active on config.
+3 ==> inbuilt function declared in functions.inc or cfunctions.inc.
+4 ==> (povr never fakes inbuilt, lower case keywords with functions)
+5 ==> current ini keyword (cmd line flag?) setting.

(+-5 checking would be case insensitive)

Actual keyword support in SDL is more complex because the meaning of 
keywords changes over time as functionality is added, removed or 
changed. Not thinking to try and document any of that drift in usage 
detail over time with keyword_status().

The central aim is giving users a greater ability to check whether using 
any particular 'word' / 'keyword' in a scene has the potential to cause 
trouble or confusion.

Thoughts?

Bill P.


Post a reply to this message

From: Bald Eagle
Subject: Re: Thoughts on 'keyword_status()' functionality for v4.0.
Date: 26 Mar 2023 15:25:00
Message: <web.64209b8eb21c98d01f9dae3025979125@news.povray.org>
William F Pokorny <ano### [at] anonymousorg> wrote:

> -5 ==> ini keyword (cmd line flag ?) setting removed.
> -4 ==> lower case, shipped function looking like something inbuilt.
> -3 ==> deleted inbuilt function formerly defined in functions.inc.
> -2 ==> pseudo / hidden keyword removed.
> -1 ==> formerly visible and usable keyword removed.
>   0 ==> not now and never a keyword. Good to go.
> +1 ==> active SDL keyword.
> +2 ==> pseudo / hidden keywords active or potentially active on config.
> +3 ==> inbuilt function declared in functions.inc or cfunctions.inc.
> +4 ==> (povr never fakes inbuilt, lower case keywords with functions)
> +5 ==> current ini keyword (cmd line flag?) setting.
>
> (+-5 checking would be case insensitive)
>
> Actual keyword support in SDL is more complex because the meaning of
> keywords changes over time as functionality is added, removed or
> changed. Not thinking to try and document any of that drift in usage
> detail over time with keyword_status().
>
> The central aim is giving users a greater ability to check whether using
> any particular 'word' / 'keyword' in a scene has the potential to cause
> trouble or confusion.
>
> Thoughts?

I don't quite know what a few of those mean, but let me add some ideas here.

> The central aim is giving users a greater ability to check whether using any
particular 'word' / 'keyword' in a scene
 has the potential to cause trouble or confusion.

Yes.   And to that end, I would suggest a sort of stratifying - much like one
might do with memory, line-numbered code, or any other hierarchical structure.
So I don't really get why  -5 is where it is.

I would probably use it (often) if I could run a simple
#if (keyword_status() > Threshold) check.

So one thing to think about would be to space the values out a bit, so that you
can fill in other things that come up as time goes on.


-BW


Post a reply to this message

From: jr
Subject: Re: Thoughts on 'keyword_status()' functionality for v4.0.
Date: 27 Mar 2023 07:15:00
Message: <web.64217a68b21c98d04301edef6cde94f1@news.povray.org>
William F Pokorny <ano### [at] anonymousorg> wrote:
> ...
> Plus I've been thinking about the bigger picture of actual keywords,
> possible keywords, stand in internal keywords used for other purposes
> and functions. We have too the ini keywords and flags.
>
> As an initial proposal thinking about a new 'keyword_status()' function
> passed strings like "tau". It would return the following values for the
> status of various strings in answer to what meanings are relative to the
> version of code being run.
> ...
> Thoughts?

like BE I'm a little bewildered by the .. variety :-)  I think that this whole
issue needs to be tied in with the (proposed) 'versions.inc' and id type
checking/testing; all aspects of the same goal, imo.


regards, jr.


Post a reply to this message

From: William F Pokorny
Subject: Re: Thoughts on 'keyword_status()' functionality for v4.0.
Date: 27 Mar 2023 16:16:29
Message: <6421f99d$1@news.povray.org>
On 3/26/23 15:22, Bald Eagle wrote:
> I would probably use it (often) if I could run a simple
> #if (keyword_status() > Threshold) check.

I'm now leaning toward the function name 'word_is()' because it leaves 
open the possibility for similarly named extensions.

I should perhaps have left the return value detail for later - 
especially given I'm still sorting it out.

---
Most day to day usage would be simple:

#declare MyStr = "lockandkey"

#if (word_is(MyStr)=0)
    #debug concat("No usage conflicts for '",MyStr,"'.\n")
#end

//--- or

#if (word_is(MyStr)!=0)
    #debug concat("Usage conflicts exist for '",MyStr,"'.\n")
#end

//--- or

#if (word_is(MyStr)>0)
    #debug concat("'",MyStr,"' is a part of this POV-Ray version.\n")
#end

Bill P.


Post a reply to this message

From: William F Pokorny
Subject: Re: Thoughts on 'keyword_status()' functionality for v4.0.
Date: 27 Mar 2023 16:23:46
Message: <6421fb52$1@news.povray.org>
On 3/27/23 07:13, jr wrote:
> like BE I'm a little bewildered by the .. variety 😄  I think that this whole
> issue needs to be tied in with the (proposed) 'versions.inc' and id type
> checking/testing; all aspects of the same goal, imo.

At code bottom there is a lot of detail, but I hope day to day users can 
ignore most of it. :-)

My aim is for this new functionality to be in usable alongside / along 
with the version.inc and setidtypes.inc proposals.

Bill P.


Post a reply to this message

From: Bald Eagle
Subject: Re: Thoughts on 'keyword_status()' functionality for v4.0.
Date: 27 Mar 2023 17:35:00
Message: <web.64220b78b21c98d01f9dae3025979125@news.povray.org>
William F Pokorny <ano### [at] anonymousorg> wrote:

> I'm now leaning toward the function name 'word_is()' because it leaves
> open the possibility for similarly named extensions.
>
> I should perhaps have left the return value detail for later -
> especially given I'm still sorting it out.

I can imagine it will take a bit of sorting.
Speaking of sorting, I'm thinking that it would be a handy thing for devs,
example scenes, documentation, and the kind of oddball experiments that people
like me conduct - to have all the keywords numbered, just like the internal
functions.

That would allow easily iterating through them all to check them by number, and
not be as subject to human error of, "I forgot that one."  I can envision that
depending on the kind of code one is writing, it would be a lot easier and more
compact to simply switch the argument of a master keyword directive that takes
an argument, like keyword (1).  If you had keyword_name (), then you could just
run a loop and do
word_is(keyword_name(keyword(index))).

;)


Post a reply to this message

From: William F Pokorny
Subject: Re: Thoughts on 'keyword_status()' functionality for v4.0.
Date: 30 Mar 2023 16:13:38
Message: <6425ed72@news.povray.org>
On 3/27/23 17:32, Bald Eagle wrote:
> Speaking of sorting, I'm thinking that it would be a handy thing for devs,
> example scenes, documentation, and the kind of oddball experiments that people
> like me conduct - to have all the keywords numbered, just like the internal
> functions.

Given the code base, we currently need to avoid fixed number to keyword 
associations. While the number to inbuilt function name associations are 
more stable than the number to keyword ones, as a soft rule, none of the 
associations are fixed until the code's compile and link is complete.

We can create indirect 'type' to number associations at parse time in 
the form of a dictionary for a particular executable. We do this in povr 
within the shipped setidtypes.inc file.

---

You and jr have both suggested, being able to work with a keyword 
'index' of some kind as a way to, say, maintain documentation in a 
database. A good idea. Today the database keys need to be strings(a).

The next release of povr (R7 v0.6.1) implements two new SDL functions in 
word_is() and word_get(). These access and make use of 18 internal 
arrays of token information relative to the active version of 
POV-Ray(povr). The 18 arrays break down into three categories.

Previous tokens (back to through v3.6) which are out (o prefix); Tokens 
included in the current code (i prefix); Lastly, tokens which are new (n 
prefix) compared to the prior major release (v3.8 beta 2). See the, 
initial, attached text documentation for more detail.

The aim, for me as much as anyone, is to create methods for the 
POV-Ray(povr) executable to provide initial hooks / 'string indexes' for 
creating and maintaining documentation; Methods for doing parse time 
checks for active keywords, directives, functions, etc.

Aside: In doing this work, I turned up that, at povr's v3.8 branch 
point, there was a new keyword called cmap related to ttf text objects. 
On the parser back up for the v3.8 release, 'cmap' got dropped. I need 
to sort out what to do with 'cmap' for povr as it's something new that I 
didn't know was in my povr fork! (It's probably still in the v4.0 code 
base too, but I did not check)

Bill P.

(a) - Even string / token indexing comes with complications.

Directives, for example, still, mostly, come in two forms as with 
'version' and '#version'. Some like #default are not really SDL 
directives and should be coded as default{}.

A new to v3.8 feature like global and local dictionaries, made use of 
the the token 'global' which had been used with photons in earlier 
POV-Ray versions - depending upon compile time options. Knowing there is 
a 'global' token is a good start, but, then there is the detail. We all 
know, quite a few keywords have multiple uses / applications.

Back to v3.6 at least there were functions coded up in various shipped 
include files that, by name, look like lower case inbuilt keywords or 
functions. I've either replaced these with true inbuilt forms - so 
behavior is not dependent on included files - or I've deleted the lower 
case function code and created versions with upper case characters so it 
is clear the functionality is NOT inbuilt, but is being declared 
somewhere. For example, a function 'even()' was long defined in 
math.inc. With povr it is now F_even() and defined in munctions.inc 
calling M_even() if need be. M_even() being a shipped, 'munction', a 
macro defining & compiling a global function, once, on need.

It's simple except where it's complicated. :-)


Post a reply to this message


Attachments:
Download 'word_is__word_get.txt' (5 KB)

Copyright 2003-2023 Persistence of Vision Raytracer Pty. Ltd.