After doing initial design work on some piece of code, I often find that the first task is to write a set of interfaces that I’ve designed by writing things out on paper. When there are a lot of interfaces with a lot of methods, I find it tedious to type them all in, taking into account formatting and phpdoc-style documentation. Although a good text editor helps, I wanted to go one step further.
So, I designed an Excel spreadsheet that would allow me to type in the interface information in a tabular form and would then generate the PHP code for me. This does not use any script, but you have to do two text replaces afterwards that can be a little difficult depending on your text editor (UltraEdit, not free, makes it a snap).
Caveats
I’ll admit up-front that this is quite a hack job and probably not useful in most circumstances, but if you have a lot of interfaces (and trivial classes) to create at once, this could save you some time. And, it’s an example of fun with formulas in Excel. I didn’t use any script–all formulas.
In particular, it doesn’t handle descriptions for return values (only types) or visibility modifiers for methods (that’s one reason why it works best for interfaces). These could be added without too much work with some more formula hacking.
How It Works
I’ve uploaded a sample here. This is a simple set of interfaces for graphs and directed graphs. There’s also a class. You’ll want to start with this file. When you’re ready to do your own, you can delete rows 3-43, and clear A2:E2 to begin your work (you want to preserve the formulas in row 2 starting at column F).
You start each interface or class with a “Type” line, specifying “class” or “interface”, the name, the one-line description, and the class/interface that it extends, if any. Then, if you have further description of the class/interface, you can include Comment lines. The Description column uses a fixed-width font and is sized to indicate the amount of room you have for these comments. If you go too long (assumes an 80-character line limit), the field turns red.
Next, specify your methods. For each method, start with a “Method” line, specifying the return type (omit for void), method name, and one-line description. Then, you may include Comment lines. Finally, add Parameter lines for each parameter, specifying the type, name, description, and default value. The Description line will turn red if you go too long, and it adjusts for indentation and the like.
Make sure your file ends with a footer line that simply has the word Type in the first column. Then, fill all columns after the first thick vertical border (the column “Final” and those to the right) down from row 2 to the row just above the footer row. Copy and paste the contents of the Final column to a text editor, and you are almost there.
In the text editor:
- Remove all blank lines
- Replace all instances of “\n” followed by an end-of-line with just the end-of-line (using the end-of-line of your choice)
- Replace all instances of “\n” with the end-of-line of your choice
If you are using Excel in Windows and UltraEdit and want Unix end-of-lines, you would replace:
- ^p^p with ^p until there are no more
- \n^p with ^n
- \n with ^n
Possible Improvements
One might be able to cut out the text editor step by replacing instances of \n in the formulas with the proper Excel formula to actual put the newline character in. I think the formula is CHR?
One could add a separate “Return” line type that would allow for a return description. Then, you could use the “Type” column for the method to be the visiblity modifier instead of the return type.
