CMB: Component Methods Browser

[Sharidan 5]

CMB is a UI based code documentation browser, that scans any and all components attached to a computer (or robot). Internally CMB automatically detects when components are added and/or removed and forces a refresh of the components list. Yes, this is similar to using the "components" command in the command prompt, however CMB presents the information in browsable sorted lists and presents method usage in nicely formatted Lua pseudo code, including which variable types are expected.
 

Current version: 1.1-i
Release date   : 28 jan 2016

Requirements:
OpenOS v1.5 (built on OC v1.5.22.42 for MC 1.7.10)
384Kb memory at least.
Any graphics card.
Any screen size.
~50Kb disk space.

Download using Internet Card:

pastebin get DnRBZfLb cmb.lua

 
Direct link to PasteBin: http://pastebin.com/DnRBZfLb
 

Sample screenshot:

 

 
 
Change log:

CMB v1.1-i

• Fixed: screen rendering bug in monochrome mode.
• Change: mono mode now has inverse selection bar, similar to color mode.
• Change: Overall screen text rendering has been optimized for faster rendering.
• ListBox control completely rewritten.
• New: mouse navigation & scrolling implemented. Touch activation implemented.
• New: theme handling added. Theme file can be found in /etc/cmb.theme

CMB v1.0-i

• Initial relese.

 
New theme feature:

A simplistic theme manager is now part of CMB, should you wish to change the colors. After running CMB for the first time, you can locate the theme file in: /etc/cmb.theme
 
You can change the color combinations to anything you like. Make sure you only change the color names, between the quotes in the theme file to avoid corrupting the file. Color sets always go in pairs of two: the first color is the text color, the second the background color. Be aware that some color combinations might not translate too well on monochrome (black & white), so you may have to experiment with the color combinations to get it working in both color and monochrome mode.
 
Valid color names are, in Minecraft Wool order:

• white
• orange
• magenta
• lightBlue / light blue
• yellow
• lime
• pink
• gray / grey
• silver / lightGray / lightGrey / light gray / light grey
• cyan
• purple
• blue
• brown
• green
• red
• black

 
Original v1.0-i post

Anyone doing any kind of coding or scripting, knows just how important accessible and updated documentation is. For years I have had Component Methods Browser locked away as one of my personal tools. Then I migrated over to OpenComputers and decided I would start sharing my goodies.
 
CMB is a UI based code documentation browser, that scans any and all components attached to a computer (or robot). Internally CMB automatically detects when components are added and/or removed and forces a refresh of the components list. Yes, this is similar to using the "components" command in the command prompt, however CMB does so much more than simply list all available components and their addresses. Originally I wrote "Methods Browser" for a certain other mod and I've used it for years for in-game quick reference lookups of documentation. CMB for OC was rewritten from scratch based on the original MB. A very small portion of the code was ported while the rest was completely written from scratch.
 
So what makes CMB so much different?
 
CMB organizes the information through a category system, with component types at the top followed by address selection and finally a sorted methods list (which also contains properties). Use arrow keys to move the selection bar, enter to select and the backspace key to return to the previous menu. If in doubt, simply press "H" for help in any menu to get the keys explained. Pressing "Q" anywhere in the program will quit the program and return to OpenOS.
 
I am a bit unsure on the actual memory spendage, however I have done a lot of test runs on 384Kb memory (2x T1 memory sticks).
 
CMB internally handles T1/T2/T3 screen modes and adjusts as needed. On T1 systems 50x16 is assumed and you will notice a difference in the selection bar/marker as it shows up as grainy blocks (see screenshots). On higher systems CMB will force 80x25 in color while running and restore original settings at exit.
 
At the moment CMB only handles components, since the contents of the /lib folder doesnt have documentation calls as such.

Requirements:
OpenOS v1.5
384Kb memory or more
45Kb disk space

CMB is available on pastebin with everything integrated. No additional files are required, beyond what comes stock with OpenOS.
Pastebin link: http://pastebin.com/DnRBZfLb
 
With an internet card installed, you can fetch CMB directly from pastebin in-game via:

pastebin get DnRBZfLb cmb.lua

CMB is delivered "as is". CMB does not write anything to disk, nor does it manipulate components in any way, except read the already available in-game documentation. Some of the Mighty Pirates tutorial/presentation videos found on YouTube showcases how to retrieve in-game documentation through the Lua prompt. At it's core CMB does the same but presents the information in scrollable selectable listings so you can easier navigate the documentation and retrieve the proper information you need.
I have gone through extensive testing of CMB before this release, however I am just a human being which means there might be bugs hidden inthere somewhere. In case of crashes or bugs, please toss me a screenshot and leave some feedback so I can fix it.
 

 
Screenshots section

Color mode in 80x25
 

Initial startup screen, listing all attached/available components
 

 
 
Component address selection. One address per attached component of this type
 

 
In this case, I chose "filesystem" as the overall component type I wanted to browse. The address selection screen for "filesystem" is somewhat different from all other address selection screens, because it also displays mount information as you can see.
Selecting a volume address and hitting the "M" key, will display mount information for that filesystem address:
 
 
Filesystem mount information sample
 

 
At the moment I don't have more than 2 mounts on the different filesystem addresses, so it only shows these two. If more exist on a single address, they will be shown but might go outside the screen height as there's no maxheight check at the moment.
Hit backspace to return to the address list for further information.
 
 
Filesystem mount information for a read only filesystem:
 

 
In this case, a read-only filesystem is being displayed. If no label has been set on a filesystem, a yellow text displaying that information is shown instead of nothing.
 
 
Method/property listing example on a filesystem component.
 

 
You can again select any one of these to get the final documenation for the selection method / property.
 
 
Initial method display, when entering the method browser:
 

 
Highlighting the method name, will display the overall description of the method and how to use it.
Pressing the arrow down key, switches to parameter mode, so you can browse through any parameters a method might have.
Pressing the arrow up key, will switch back to method mode.
 
 
Parameter selection and details:
 

 
Here the first parameter of the method is selected. Details for the selected parameter will be listed, including which data type might be expected for this parameter. If a parameter is optional, it will be shown.
 
 
Methods requiring tables as parameters:
 

 
Here is an example of a method that requires a table as a parameter. The parameter "stack" is expected to follow a certain format, which is what this an example of.
 
 
Finally an example a parameter with specific values expected:
 

 
In this example, the "direction" parameter is expected to be a string and hold one of the listed values as it's contents.

 
Mono mode in 50x16

Please follow these links for monochrome screenshots. They are listed in the same order as in the color section.

http://www.sharidan.dk/upload/oc/cmb/cmbm1.png

http://www.sharidan.dk/upload/oc/cmb/cmbm2.png

http://www.sharidan.dk/upload/oc/cmb/cmbm3.png

http://www.sharidan.dk/upload/oc/cmb/cmbm4.png

http://www.sharidan.dk/upload/oc/cmb/cmbm5.png

http://www.sharidan.dk/upload/oc/cmb/cmbm6.png

http://www.sharidan.dk/upload/oc/cmb/cmbm7.png

http://www.sharidan.dk/upload/oc/cmb/cmbm8.png

http://www.sharidan.dk/upload/oc/cmb/cmbm9.png

 

In regards to the code...

I'm sure some parts can be done smarter and/or more efficient than I have chosen to do. If when looking through my code you feel I've had my head up my butt, please don't talk down to me - please educate me instead. I'm an old code dog and you know how the saying goes in those regards. I have had my fair share of talking down and being treated as a complete noob on a certain other forum, which I why I for the most part kept away from there and never shared my scripts before.
 
Internally CMB has a few nifty mini-libraries.
 
There's my terminal object, which is basically a wrapper for the gpu component, just to get the fully cross screen/gpu handling I wanted and some easier to use widgets to place something on screen. The term object handles screen clearing, color selection (with mono conversion support) and the titlebar shown in CMB. This wrapper should not be confused with the OC supplied term API! In code, search for "function newTerm".
 
As an add-on for my term wrapper, there is also the statusBar renderer, which for the most part handles the help texts at the bottom of the screen. statusBar accepts any number of parameters. Each parameter can either be a single string value using ambersand (&) to denote the highlighted letter or a pair of number, string where the number is either 14 for "BckSpc" or 28 for "Enter" which will be rendered in brackets preceeding the text in the string.
 
Then there is the list box control which handles all the major selection screens. It is a fully integrated single column listbox with keyboard interfacing only. In code, search for "function newList".
 
If you find any parts of my code useful, feel free to snip a copy of the code but please give credit where credit is due. A simple comment inthere with my name and maybe which script you got the code from will be appreciated

 

I'm fully open to suggestions, ideas, improvements, code optimizations etc., so let me know what you think.
 
I hope you will find this tool as useful as I do
 
Sharidan

[jhagrid77 4]

This seems very useful, will check it out later on the weekend.

[Sharidan 5]

I wrote the original version for CC a couple of years ago and right up to when I switched over to OC, I used it frequently. Remembering all the methods of all the blocks and machines is impossible, so having a nicely packaged documentation lookup tool like this is golden.

CMB will most likely become the first script I go to update when APIs and things change, so you can expect that I will keep this tool alive and updated

[jhagrid77 4]

A question, will this allow you to set primary components?

[Sharidan 5]

Short answer: no.

 

CMB is meant as a documentation assistance tool where you can look up the addresses of attached components, their associated libraries / APIs and each individual method and property of a chosen library. Any non-OpenComputers peripherals that you attach through adapters and that OpenComputers can see as components, can also be browsed through CMB so you can check out the different functions external machines have. For example the functions of a JABBA barrel or a Thermal Expansion machine.

 

I do have plans for a suite of system utilities that could easily include a tool to choose/set primaries, however this is still in the planning stages.

[jhagrid77 4]

Ahh I understand, I would like to say (although I haven't tried it) that you make a folder (or what ever it is) and try to get your scripts included in OPPM as this could be really useful.

[Sharidan 5]

If people find CMB useful I might try that

[Sharidan 5]

CMB v1.1-i released.

 

Please see changelog in original post for changes and new features.

[jhagrid77 4]

Threw it into a file I'm going to download to download OC files this weekend.

[mpmxyz 27]

Your program is nice. Processing the component documentation to make it more readable is a nice idea.

I read through your code and noticed one thing:

string.find(methodDoc, "[--]")

When writing this you probably thought that this matches the two minus signs within a documentation string.

But the square brackets indicate a set of possibilities for one character only. "%-%-" matches two minus signs.

Since you adjusted the indices in the following string.sub calls there is no noticeable effect on your program. (So if you "correct" that string.find, you have to change the indices again.)

 

What about a generic documentation for libraries?

debug.getinfo can get you a lot of useful information. (Another reason to use good parameter names when writing your library. ;-))

 

PS: Have you tried my component/library program? While it is able to display unmodified method documentation via tostring(method), it has a much larger focus on working with/trying out things. A split screen with both programs running in parallel would be perfect. (A multi-term-implementation is coming soon but built-in multitasking is still missing.)

[Sharidan 5]

I've never really been on good terms with regular expressions. Thank you mpmxyz, for explaining and pointing out my mistake with the double minuses. That is certainly something I will correct. I tried out a number of different setups before I settled on that setup because it was the only one that appeared to be working.

 

I have in fact been thinking about what other kind of documentation I could add to CMB. I will definately dig into debug.getinfo and see what kind of information I can dig up. Ultimately the goal of CMB is to be able to present what ever documentation is available, which of course also includes libraries. Thank you for pointing me in the right direction for library documentation.

 

Yes, I did look at cbrowse, but figured it was more suited for actual debugging and variable testing. Like you said yourself it's more focused on trying things out. I chose not to implement such features in mine, out of respect for you and your application.