VBCC: building a TextEdit syntax plugin for OS3.2

[phx]

Aaaarrrgh!
Maybe this is a tiny detail which is worth documenting for potential plugin authors?

There is no way you would expect that

init()

is called with register arguments. Also the example code shows a standard

static void init(APTR userData)

. At least the plugin structure should have an entry like

void (*init)(register __a0 APTR userData)

to make that clear - or even better using the portable

__REG__

macro from

clib/compiler-specific.h

.

The best solution, in my opinion, would be to just use standard arguments on the stack and avoid any trouble with compiler-specific register arguments.

[boemann]

But this is the definition of the function i call:


/* Now the real data comes */
void (*init)(APTR userData);

In my understanding this implies standard arguments, so I'm completely surprised it passes via a0 as that is not what i tried to do

[boemann]

ARghh from my makefile:

params=r

[phx]

Det var ikke så godt!

As TextEdit was already released with OS3.2, I guess the interface will not change again and has to be documented with register arguments?

[boemann]

I have specifically not released api info officially. No one should publish plugins before there is an official api.

The whole purpose of doing it like this is so I can get feedback

So I have no problem with changing it for 3.2.1

[phx]

Originally Posted by boemann

The whole purpose of doing it like this is so I can get feedback

So I have no problem with changing it for 3.2.1

Let's see if guy lateur can generate a working plugin now, with that knowledge.

[boemann]

he should just be aware that he needs to do it for all the settings gui functions too

And obviously be prepared for a rebuild when 3.2.1 is out

[bebbo]

Originally Posted by phx

Aaaarrrgh!
The best solution, in my opinion, would be to just use standard arguments on the stack and avoid any trouble with compiler-specific register arguments.

The Amiga loves register arguments and there is no argument against that^^

[alkis]

It might be beneficial to keep the params=r in the makefile and declare the plugin functions prefixed with __stdargs ?

[guy lateur]

Originally Posted by phx

Let's see if guy lateur can generate a working plugin now, with that knowledge.

Yep, he sure can! Finally it's working! Thank you all for your time and energy you put into getting this to work, I greatly appreciate this! I can finally start concentrating on the highlighting itself.

Here's my

init()

function:

static void init(__reg("a0") APTR userData)
{
    struct Filetype *fType = (struct Filetype *)userData;
    struct Hook *hook      = NULL;
    
    if(!openLibs())
    {
        terminate(fType);
        return;
    }

    hook             = (struct Hook *)AllocVec(sizeof(struct Hook), MEMF_CLEAR);
    hook->h_Entry    = (ULONG (*)()) highlightBlock;
    hook->h_SubEntry = NULL;
    hook->h_Data     = 1234567;
    
    fType->highlighterHook    = hook;
    
    // any number or pointer of our choosing
    // does this have to be equal to hook->h_Data?
    fType->pluginData         = (ULONG)1234567;
    
    fType->name               = "ExampleName";
    fType->typeName           = "ExampleTypeName";
    fType->autoFileTypes      = "ExampleAFT"; // example? eg (*.s;*.i)?
    
    fType->terminate          = terminate;
    fType->settingsTitle      = settingsTitle;
    fType->settingsGadget     = settingsGadget;
    fType->processGadgetUp    = processGadgetUp;
    fType->setSettingsFromGUI = setSettingsFromGUI;
    fType->setGUIFromSettings = setGUIFromSettings;
    fType->applySettings      = applySettings;
    fType->saveSettings       = saveHighlightSettings;
    fType->loadSettings       = loadHighlightSettings;
    fType->disposeGadgets     = disposeGadgets;
}

For completeness, here's

highlightBlock()

:

ULONG __saveds highlightBlock(__reg("a0") struct Hook *h, __reg("a2") VOID *o, __reg("a1") VOID *msg)
{
    struct HighlightMessage *hm = (struct HighlightMessage *)msg;
    STRPTR text = hm->Text;
    UWORD state = hm->StatusOfPrevBlock;
    UWORD start = 0;
    UWORD end = strlen(text);

    // if line is longer than 10 chars we paint the entire line with color 3
    if (end > 10)
        HighlightSetFormat(o, start, end, (3<<8)|TBSTYLE_SETCOLOR);

    return (ULONG)state + 1L;
}

Here are my latest sources, including the binaries: master-20210629.zip

Originally Posted by boemann

he should just be aware that he needs to do it for all the settings gui functions too

Well to be brutally honest, I was kinda hoping you would release a more fleshed out example when 3.2.1 comes out and you release this officially. Eg, if you could release the code that handles the GUI for the highlighting as it is for the built-in types, I think that would be really beneficial for the community. If people can select the part type (eg label, instruction, literal, comment, ..) and set the color and the standard font properties (bold, italic, underline) for each one of those, that would already go a long way for most plugins, IMHO.

Also, a little more explanation would be welcome, but I'm sure you already knew that. Eg, does fType->pluginData need to be equal to hook->h_Data? How to specify the file types this highlighting automatically applies to (eg, .s and .i files)?

Originally Posted by boemann

And obviously be prepared for a rebuild when 3.2.1 is out

I'll be more than happy to do that when the time comes!

[alkis]

Well done for the working plugin.

Just curious here, does it work if you remove __saveds from highlightBlock?

[guy lateur]

Originally Posted by alkis

Just curious here, does it work if you remove __saveds from highlightBlock?

Yep, apparently it does.

[alkis]

It should work. You are not referencing any plugin variables, just locals (or parameter's passed).
Anyways __saveds is there if you need to access any global plugin variable(s) I guess.

[guy lateur]

Originally Posted by alkis

It should work. You are not referencing any plugin variables, just locals (or parameter's passed).
Anyways __saveds is there if you need to access any global plugin variable(s) I guess.

Ok, thanks for elaborating on this. TBH, I only have a vague idea what these qualifiers really mean ATM..

[boemann]

Originally Posted by alkis

It might be beneficial to keep the params=r in the makefile and declare the plugin functions prefixed with __stdargs ?

yes

[boemann]

Originally Posted by guy lateur

Well to be brutally honest, I was kinda hoping you would release a more fleshed out example when 3.2.1 comes out and you release this officially. Eg, if you could release the code that handles the GUI for the highlighting as it is for the built-in types, I think that would be really beneficial for the community. If people can select the part type (eg label, instruction, literal, comment, ..) and set the color and the standard font properties (bold, italic, underline) for each one of those, that would already go a long way for most plugins, IMHO.

Also, a little more explanation would be welcome, but I'm sure you already knew that. Eg, does fType->pluginData need to be equal to hook->h_Data? How to specify the file types this highlighting automatically applies to (eg, .s and .i files)?

hook data and pluginData are both totally up to you to define, and does not have to be the same

the fType->autoFileTypes is the one that specieds the file to automatically apply to: for you that would be: "asm\ni"
This refers to asm and i defticons typenames

As for a more elaborate example, I'll have to see if it can be released, but apart from getting approval, I'm also not that proud of how the default plugins are coded. They do their job but were never intended to be top of the line - so using them as examples for others to learn from is maybe not so great. This means I should spend more time on making an example. Time I'd like to spend on other things too. We'll see

[guy lateur]

Originally Posted by boemann

hook data and pluginData are both totally up to you to define, and does not have to be the same

the fType->autoFileTypes is the one that specieds the file to automatically apply to: for you that would be: "asm\ni"
This refers to asm and i defticons typenames

Ok, thanks for the info.

Originally Posted by boemann

As for a more elaborate example, I'll have to see if it can be released, but apart from getting approval, I'm also not that proud of how the default plugins are coded. They do their job but were never intended to be top of the line - so using them as examples for others to learn from is maybe not so great. This means I should spend more time on making an example. Time I'd like to spend on other things too. We'll see

Sure, no worries, it's just an idea, something I would like to see.

[bebbo]

Originally Posted by alkis

It should work. You are not referencing any plugin variables, just locals (or parameter's passed).
Anyways __saveds is there if you need to access any global plugin variable(s) I guess.

__saveds is not useful here - it's simply stupid.


And refering to the task's userdata pointer: How many plugins can store it's a4 register in the same location? And what happens if the main program uses that field too??


No baserel stuff in these plugins!

And if the same plugin is used by many instances: use only the allocated memory - pointer to stored in fType->pluginData - for everything. No global stuff. none at all.

[phx]

Originally Posted by bebbo

__saveds is not useful here - it's simply stupid.

At least it is not necessary, as long as the plugin is not compiled with small data.

And refering to the task's userdata pointer: How many plugins can store it's a4 register in the same location? And what happens if the main program uses that field too??

No baserel stuff in these plugins!

Sounds as if you are quite certain that a TextEdit plugin must be reentrant? Is that really the case? I didn't get this impression from existing example code. Maybe Camilla can make it clear.

And if the same plugin is used by many instances:

This would be another open question. Does that happen? I could imagine that when you start TextEdit for a second time it will also load the plugins for a second time into memory. Camilla already confirmed that TextEdit is not reentrant (pure) itself.

use only the allocated memory - pointer to stored in fType->pluginData - for everything. No global stuff. none at all.

I agree this is generally a good idea for reentrant programs. Maybe even for normal ones. But it usually forces you to write compiler-specific code when doing OS-calls, which depend on a static library base.

[boemann]

Originally Posted by phx

Sounds as if you are quite certain that a TextEdit plugin must be reentrant? Is that really the case? I didn't get this impression from existing example code. Maybe Camilla can make it clear.

This would be another open question. Does that happen? I could imagine that when you start TextEdit for a second time it will also load the plugins for a second time into memory. Camilla already confirmed that TextEdit is not reentrant (pure) itself.

I agree this is generally a good idea for reentrant programs. Maybe even for normal ones. But it usually forces you to write compiler-specific code when doing OS-calls, which depend on a static library base.

TextEdit Plugins does not have to be reentrant/pure

A new instance of TextEdit will load the plugins again.

The default plugins use global vars for storing library bases as well as the settings for the plugin. (colors, softstyle for the various types)

The hook stores a pointer to the statemachine in it's data member, which is allocated and generated on init