Skip to content
Bushmills edited this page Feb 9, 2022 · 10 revisions

Help is of course appreciated, especially in the fields where yoda is lacking.

Documentation

For immediate help, not requiring a lot of preparations, a word to aid documenting yet undocumented words has been provided.
Assuming that yoda can be run, its documentation directory exists and has been populated, and a suitable editor can be found, executing

yoda undoc (note: all core words documented, this will now not find any more words)

will look for another yet undocumented word, create a partly filled in template file and opens that file in the editor. All it takes now is filling the gaps, especially stack effects and description, of the words under description. Save the edited files, eventually commit and push those to your remote clone, and issue a pull request. As many words match their Forth counterparts, even without detailed knowledge of yoda is it possible to create a valuable contribution this way.
Words picked for documenting are apparently in random order, reducing boredom.
Also, while I try to keep the misc informative bits about yoda in sync with changes to yoda, I may have missed to update some, which then still give already outdated information. Should you find a piece of documentation which clearly doesn't correspond with how yoda is behaving, I am of course very interested to learn about those, the sooner the better.

Testing

The importance of testing is obvious. As far exist only a few tests, using words expected and check from the check library. There is therefore plenty of space in this field to contribute eradicating all the little quirks and bugs which as far went undetected of which yoda is undoubtedly still likely to suffer from.
Especially in need of testing are signed and unsigned operations of all kinds. Anything which can cause a wrap around of number ranges by overflow or sign change is under scrutiny, from a simple 1+, signed and unsigned comparison, to loop, +loop, next, along with any arithmetic operation. Yoda employs the strategy of trying to make sure that no out-of-range numbers are pushed or stored after generated, and let operations taking those as input assume they're not out of range. "Out of range" meaning here "no number with any bit above msb set stored in memory or on stack", though there exist still words which sanitise their input by ANDing with maxuint, unnecessarily in most cases.

Extending

adding useful libs to teach yoda new tricks is of course also desirable, though not the highest level of importance at this time. It is however still good to know what yoda is supposed to eventually execute, as this may have to be taken into account in the current first implementation stages yoda is still going through.
Currently missing, needing to be added eventually, are:

  • file I/O
    • handle based files
    • legacy blocks file system

Cleaning up, getting rid of unnecessary and useless stuff

String stack operations where modifying strings is concerned are a hodgepodge of sometimes useful and sometimes not that useful functions. Some streamlining may the needed there, eliminating the words with limited usefulness and instead focusing on implementing or enhancing the general and more versatile words from which the others can be derived easily.

Clone this wiki locally