Example of adding custom C functions

[guberathome]

One short demonstration how to compile custom code with PForth for the "unix" build.
Custom code resides in separate "custom" folder.
Setup, compilation and cleanup are handled by one shell script.

Tested with MSYS2-Cygwin, Linux, FreeBSD and NetBSD.

Edit: Changes from #184 seem to have crept in here, these still need to be fixed. Apologies.

[philburk]

Changes from #184 seem to have crept in here,

there have been several recent changes. You will need to rebase to clear the merge conflicts.

[guberathome]

there have been several recent changes. You will need to rebase to clear the merge conflicts.

Done, changes are merged.

[philburk]

The "custom" folder should be in an "examples" folder.

[guberathome]

done:

• The "custom" folder should be in an "examples" folder.
• in cf_helpers.h: We should not encourage calling exit() or assert() in production code.
• in Makefile: CF_ is a bit cryptic. We should use CUSTOM_SOURCES
• in cf_demo1.c: Deleting files is a bit dangerous for a demo
  replaced BE-GONE with FILE-INFO
• go-v1.sh: Why v0 and v1?
• in go-v0.sh: Why overwrite the file?
  removed since we changed the Makefile

open:

• in demo.fth: Just need one "passing"
  Sorry to disagree: passing more than just one value helps to ensure proper function.
  Also you can guess (by inductive reasoning) what F4711 and FILE-INFO are meant to do just by looking at the output (not the source):

---------------------------
show that custom code works
---------------------------
f4711( 0, 1, 10, 100, 1000 ) = ( 11 , 58 , 481 , 4711 , 47011 )
FILE-INFO:
   file{ size=5459, path='Makefile' }
   directory{ path='../../examples' }
   error{ id=2, desc='No such file or directory', path='fileNotHere' }

[guberathome]

Just need one "passing"

Please consider if these changes are relevant to be merged (discussion on #188 contains my pitch in favour).
My preference would be to contribute to this repo rather than putting example elsewhere.

I can removed the last offending passages from custom/01-be-gone/demo.fth if that settles it.

[philburk]

path is not getting freed.
Can you avoid doing the dangerous memory allocation for the C string? Maybe allocate on the stack.

[guberathome]

added FREE-C word.
Thus deallocation is done in demo.fth.

[philburk]

This does not go through the Forth output path so it will not work over a serial port.

Demonstrating custom C calling does not require calling complex host functions.
It could just be a function that modifies a string.
The user will just replace these custom functions so the simpler the better.

[guberathome]

This does not go through the Forth output path so it will not work over a serial port.

Just to clarify: asprintf() allocates a buffer of correct size into which it sprintf's the formatted output.
Which then gets returned.
I'm not aware of bypassing any PForth functionality here.

Demonstrating custom C calling does not require calling complex host functions. It could just be a function that modifies a string. The user will just replace these custom functions so the simpler the better.

That's what is done here.
Creating a new string (of previously unknown length) requires either hairy assumptions about maximal length or allocating a new buffer. All the fun of programming C.