Does anyone have any references for building a full Object/Class reflection system in C++ ?
Ive seen some crazy macro / template solutions however ive never found a system which solves everything to a level im comfortable with.
Thanks!
Using templates and macros to automatically, or semi-automatically, define everything is pretty much the only option in C++. C++ has very weak reflection/introspection abilities. However, if what you want to do is mainly serialization and storage, this has already been implemented in the Boost Serialization libraries. You can do this by either implementing a serializer method on the class, or have an external function if you don't want to modify the class.
This doesn't seem to be what you were asking though. I'm guessing you want something like automatic serialization which requires no extra effort on the part of the class implementer. They have this in Python, and Java, and many other languages, but not C++. In order to get what you want, you would need to implement your own object system like, perhaps, the meta-object system that IgKh mentioned in his answer.
If you want to do that, I'd suggest looking at how JavaScript implements objects. JavaScript uses a prototype based object system, which is reasonably simple, yet fairly powerful. I recommend this because it seems to me like it would be easier to implement if you had to do it yourself. If you are in the mood for reading a VERY long-winded explanation on the benefits and elegance of prototypes, you can find an essay on the subject at Steve Yegge's blog. He is a very experienced programmer, so I give his opinions some credence, but I have never done this myself so I can only point to what others have said.
If you wanted to remain with the more C++ style of classes and instances instead of the less familiar prototypes, look at how Python objects and serialization work. Python also use a "properties" approach to implementing its objects, but the properties are used to implement classes and inheritance instead of a prototype based system, so it may be a little more familiar.
Sorry that I don't have a simpler answer to your question! But hopefully this will help.
I'm not entirely sure that I understood you intention, however the Qt framework contains a powerful meta object system that lets you do most operation expected from a reflection a system: Getting the class name as string, checking if a object is a instance of a given type, listing and invoking methods, etc.
I've used ROOT's Reflex library with good results. Rather than using crazy macro / template solutions like you described, it processes your C++ header files at build time to create reflection dictionaries then operates off of those.
Related
I am working on documenting a new and expanded Lua API for the game Bitfighter (http://bitfighter.org). Our Lua object model is a subset of the C++ object model, and the methods exposed to Lua that I need to document are a subset of the methods available in C++. I want to document only the items relevant to Lua, and ignore the rest.
For example, the object BfObject is the root of all the Lua objects, but is itself in the middle of the C++ object tree. BfObject has about 40 C++ methods, of which about 10 are relevant to Lua scripters. I wish to have our documentation show BfObject as the root object, and show only those 10 relevant methods. We would also need to show its children objects in a way that made the inheritance of methods clear.
For the moment we can assume that all the code is written in C++.
One idea would be to somehow mark the objects we want to document in a way that a system such as doxygen would know what to look at and ignore the rest. Another would be to preprocess the C++ code in such a way as to delete all the non-relevant bits, and document what remains with something like doxygen. (I actually got pretty far with this approach using luadoc, but could not find a way to make luadoc show object hierarchy.)
One thing that might prove helpful is that every Lua object class is registered in a consistent manner, along with its parent class.
There are a growing number of games out there that use Lua for scripting, and many of them have decent documentation. Does anyone have a good suggestion on how to produce it?
PS To clarify, I'm happy to use any tool that will do the job -- doxygen and luadoc are just examples that I am somewhat familiar with.
I have found a solution, which, while not ideal, works pretty well. I cobbled together a Perl script which rips through all the Bitfighter source code and produces a second set of "fake" source that contains only the elements I want. I can then run this secondary source through Doxygen and get a result that is 95% of what I'm looking for.
I'm declaring victory.
One advantage of this approach is that I can document the code in a "natural" way, and don't need to worry about marking what's in and what's out. The script is smart enough to figure it out from the code structure.
If anyone is interested, the Perl script is available in the Bitfighter source archive at https://code.google.com/p/bitfighter/source/browse/luadoc.pl. It is only about 80% complete, and is missing a few very important items (such as properly displaying function args), but the structure is there, and I am satisfied the process will work. The script will improve with time.
The (very preliminary) results of the process can be seen at http://bitfighter.org/luadocs/index.html. The templates have hardly been modified, so it has a very "stock" look, but it shows that things more-or-less work.
Since some commenters have suggested that it is impossible to generate good documentation with Doxygen, I should note that almost none of our inline docs have been added yet. To get a sense of what they will look like, see the Teleporter class. It's not super good, but I think it does refute the notion that Doxygen always produces useless docs.
My major regret at this point is that my solution is really a one-off and does not address what I think is a growing need in the community. Perhaps at some point we'll standardize on a way of merging C++ and Lua and the task of creating a generalized documentation tool will be more manageable.
PS You can see what the markup in the original source files looks like... see https://code.google.com/p/bitfighter/source/browse/zap/teleporter.cpp, and search for #luaclass
Exclude either by namespace (could be class as well) of your C++ code, but not the lua code
EXCLUDE_SYMBOLS = myhier_cpp::*
in the doxygen config file or cherry pick what to exclude by using
/// #cond
class aaa {
...
...
}
/// #endcond
in your c++ code.
I personally think that separating by namespace is better since it reflects the separation in code + documentation, which leads to a namespace based scheme for separation of pure c++ from lua bindings.
Separating via exclusion is probably the most targeted approach but that would involve an extra tool to parse the code, mark up relevant lua parts and add the exclusion to the code. (Additionally you could also render special info like graphs separately with this markup and add them via an Image to your documentation, at least that's easy to do with Doxygen.). Since there has to be some kind of indication of lua code, the markup is probably not too difficult to derive.
Another solution is to use LDoc. It also allows you to write C++ comments, which will be parsed by LDoc and included into the documentation.
An advantage is that you can just the same tool to document your lua code as well. A drawback is that the project seems to be unmaintained. It may also not be possible to document complex object hierarchies, like the questioner mentioned.
I forked it myself for some small adjustments regarding c++. Have a look here.
I've found a few methods online on how to implement property-like functionality in c++. There seems to be some sound work-arounds for getting it to work well.
My question is, with the prevalence of properties in managed langues, should I spend the effort and the possibilty of code-breakage (or whatever) to implement properties in my code?
Say I'm going to dev up a library of calls for someone else to use, would properties be desired enough to validate the extra code?
What can you gain from doing this that you can't get from just using accessor functions?
It seems to me that while coding you ought to play to a language's strengths instead of getting it to emulate another language. So I'd vote no on this one. However, if you are writing in MANAGED C++ and are going to be using this code to interface with C# on a regular basis, and if for some reason you wanted to make the backend more usable by a native C# programmer, it might be worthwhile.
Unless you add reflection to the mix (being able to identify at runtime what properties exist on an object), properties are nothing more than syntactic sugar for getters and setters. Might as well just use getters and setters, in that case.
Properties with reflection can indeed be useful for C++ programs, though. Qt handles this quite nicely.
Properties are not idiomatic Standard C++ - as evidenced by the fact that there's no single "property-like" library in widespread use. The complexity of properly implementing them in conformant C++ is significant, while the benefits compared to direct invocation of accessor methods are small, and mostly stylistic. In my opinion, it's not worth the bother.
Properties actually prevent code breakage if done properly. It allows you to change the implementation of the property underneath without the caller having to change his code or even worry about it.
For instance, say you have a Socket class that takes a socket number. Implement as a property to just take an int and store it.
However your boss says that you should not accept socket numbers lower than 1024. Your property can change to scan for that and not accept the value.
No change to caller code.
Edit: A slight mis-understanding of the question...I took properties to mean normal accessor functions.
I have once tried to implement something similar to Matlab structures in C++, i. e. structures to which one can add named fields. After that I became a firm believer in the "Do Not Fight the Language" principle.
Efforts to make one programming language behave like another are often a special case of the inner platform effect.
I agree with others - just use getters and setters.
If you really need properties in C++, perhaps you already have them as a language extension. I think Visual C++ does - almost certainly for managed C++, but maybe for unmanaged too. Personally, the only reason I'd use them is in managed C++ to fit with .NET conventions.
Outside of that, creating an inner platform for this will almost certainly cause more problems than it solves.
I'm creating a design document for a security subsystem, to be written in C++. I've created a class diagram and sequence diagrams for the major use cases. I've also specified the public attributes, associations and methods for each of the classes. But, I haven't drilled the method definitions down to the C++ level yet. Since I'm new to C++ , as is the other developer, I wonder if it might not make sense go ahead and specify to this level. Thoughts?
edit: Wow - completely against, unanimous. I was thinking about, for example, the whole business about specifying const vs. non-const, passing references, handling default constructor and assigns, and so forth. I do believe it's been quite helpful to spec this out to this level of detail so far. I definitely have gotten a clearer idea of how the system will work. Maybe if I just do a few methods, as an example, before diving into the code?
I wouldn't recommend going to this level, but then again you've already gone past where I would go in a design specification. My personal feeling is that putting a lot of effort into detailed design up-front is going to be wasted as you find out in developing code that your guesses as to how the code will work are wrong. I would stick with a high-level design and think about using TDD (test driven development) to guide the low-level design and implementation.
I would say it makes no sense at all, and that you have gone too far already. If you are new to C++ you are in no position to write a detailed design document for a C++ project. I would recommend you try to implement what you already have in C++, learn by the inevitable mistakes (like public attributes) and then go back and revise it.
Since you're new, it probably makes sense not to drill down.
Reason: You're still figuring out the language and how things are best structured. That means you'll make mistakes initially and you'll want to correct them without constantly updating the documentation.
It really depends on who the design document is targeted at. If it's for a boss who is non-technical, then you are good with what you have.
If it's for yourself, then you are using the tool to help you, so you decide. I create method level design docs when I am creating a project, but it's at a high level so I can figure out what the features of the various classes should be. I've found that across languages, the primary functionalities of a class have little to do with the programming language we are working in. Some of the internal details and functions required certainly vary due to the chosen language, but those are implementation details that I don't bother with during the design phase.
It certainly helps me to know that for instance an authorization class might have an authenticate function that takes a User object as a parameter. I don't really care during design that I might need an internal string md5 function wrapper to accomplish some specific goal. I find out about that while coding.
The goal of initial design is to get organized so you can make progress with clarity and forethought rather than tearing out and reimplementing the same function 4 times because you forgot some scenario due to not planning.
EDIT: I work in PHP a lot, and I actually use PhpDoc to do some of the design docs, by simply writing the method signature with no implementation, then putting a detailed description of what the method should do in the method header comments. This helps anyone that is using my class in the future, because the design IS the documentation. I can also change the documentation if I do need to make some alterations while coding.
I work in php4 a lot, so I don't get to use interfaces. In php5, I create the interface, then implement it elsewhere.
The best way to specify how the code should actually fit together is in code. The design document is for other things that are not easily expressed in code. You should use it for describing the actual need the program fills, How it interacts with users, what the constraints are in terms of hardware and operating systems. Certainly describe the overall architecture of your application in a design document, but, for instance, the API should actually be described in the code that exposes the API.
You have already gone far enough with the documentation part. As you still a beginner in C++, when you would understand the language, you might want to change the structure of your program. Then you would have to do changes in the documentation. I would suggest that you have already gone too far with the documentation. No need to drill more into it
Like everyone else says, you've gone way past where you need to go with the design. Do you have a good set of requirements to the simple true/false statement level that you derived that design from? You can design all day long, but if you don't have requirements that simply say WHAT you're going to do, it doesn't matter how good your design is.
After switching from C++ to C++ w/boost, do you think your OOD skills improved?
Do you notice patterns in "Normal" C++ code that you wouldn't consider that you've switched, or do you find that it enables a more abstract design?
I guess I'm really wondering if you just use it as a tool, or if you change your entire approach to OO design to make more efficient use of objects when using boost pointers.
Edit:summary
This question was kind of strange--I was asking because I've run into so much C++ code that was not at all OO. I'm fairly sure (with that and my work on it before moving to a managed language) that it's harder to think in OO in C++ than a managed language.
From looking at these posts, I'm guessing that you learn the value of OO before finding a need for a better way to manage memory, so by the time you start looking for something like Boost, you're already using OO methodologies pretty heavily.
I was kind of expecting a bunch of answers saying that it helped them think in OO, but now that I think about it, if you aren't using OO, boost pointers are not very helpful, and you wouldn't see the need for them (so you wouldn't have replied).
In a project in C++ I was doing about six years ago, we implemented our own boost-like automatic pointer scheme. It worked pretty well, except for the various bugs in it. (Sure wish we had used boost...)
Nonetheless, it really didn't change how we developed code. Object oriented design, with or without managed pointers, is very similar. There's times when you need to return objects, or times when pointers to objects are more important. The nice thing about smart pointers has only a small amount to do with how you design your application. Instead of passing a potentially dangerous memory leak around, you can pass that same data and be fairly certain that it's not going to leak.
In that respect, there are some things you can tend to do more with smart pointers: simplify your code. Instead of returning integers or basic structures every where, you can more freely pass complicated data structures or classes without worry. You can build more complex apps, faster, without having to worry so much. It lets you have the raw power of C and C++ when you need it (why would you be using C or C++ if you didn't need it?) and have the ease of memory management that's such an amazing productivity boost. If automatically managed memory wasn't useful, it wouldn't be in almost every other language on the planet!
STL/Boost is a tool for the job. They help me implement my ideas not the other way around. Clarification: Boost did not boost up my OOD skills.
It has deeply changed my way of coding, and i'm spreading the word. Through the use of Boost.Graph and Boost.PropertyMap in particular, i realized that i could write "true" algorithms in a simple class, not (yet) knowing how to access information, not even knowing (or caring) what sub-actions might be done while executing the algorithm.
My team is now designing complex computing functionality using a graphical tool.
One might argue that templates are really the base of this change, but Boost clearly paved the way. To me, discovering new Boost libraries is very often a great opportunity to learn important stuff that can be applied to our everyday work !
Once I discovered boost::bind (and boost::function) I found instead of thinking in terms of inheritance and abstract base classes ("interfaces" in java/c#-speak) I started seeing everything as a functor.
For example, pre-boost I'd have built a menu system where the menus were containers of IActionable* items and anything which wanted to be hooked into the menu system would have to inherit IActionable and provide an action method. Post-boost and I'm implementing menus containing boost::function<void()> objects and just throwing anything I want into them using boost::bind.
Another thing: just looking at the way in which boost successfully employs templates really made me raise my expectations of what was possible with them and make the effort to make better use of them in my own code, so I'm writing a lot more "generic" and less "OOP" code.
The smart pointers are certainly useful and get a lot of coverage, but apart from cleaning up some explicit deletes they're hardly a paradigm shift.
For me, it didn't change the way I do design, but Boost does give me additional tools so that certain things are easier. For example, with "smart" pointers, I no longer have to think about making sure certain object creations have to destroyed at the proper time (mostly in the exceptional case). But like any tool, I have to understand when to use them and when NOT to.
Do you use Luabind, toLua++, or some other library (if so, which one) or none at all?
For each approach, what are the pro's and con's?
I can't really agree with the 'roll your own' vote, binding basic types and static C functions to Lua is trivial, yes, but the picture changes the moment you start dealing with tables and metatables; things go trickier very quickly.
LuaBind seems to do the job, but I have a philosophical issue with it. For me it seems like if your types are already complicated the fact that Luabind is heavily templated is not going to make your code any easier to follow, as a friend of mine said "you'll need Herb Shutter to figure out the compilation messages". Plus it depends on Boost, plus compilation times get a serious hit, etc.
After trying a few bindings, Tolua++ seems the best. Tolua doesn't seem to be very much in development, where as Tolua++ seems to work fine (plus half the 'Tolua' tutorials out there are, in fact, 'Tolua++' tutorials, trust me on that:) Tolua does generate the right stuff, the source can be modified and it seems to deal with complicated cases (like templates, unions, nameless structs, etc, etc)
The biggest issue with Tolua++ seems to be the lack of proper tutorials, pre-set Visual Studio projects, or the fact that the command line is a bit tricky to follow (you path/files can't have white spaces -in Windows at least- and so on) Still, for me it is the winner.
To answer my own question in part:
Luabind: once you know how to bind methods and classes via this awkward template syntax, it's pretty straightforward and easy to add new bindings. However, luabind has a significant performance impact and shouldn't be used for realtime applications. About 5-20 times more overhead than calling C functions that manipulate the stack directly.
I don't use any library. I have used SWIG to expose a C library some time ago, but there was too much overhead, and I stop using it.
The pros are better performance and more control, but its takes more time to write.
Use raw Lua API for your bindings -- and keep them simple. Take inspiration in the API itself (AUX library) and libraries by Lua authors.
With some practice raw API is the best option -- maximum flexibility and minimum of unneeded overhead. You've got what you want and no more, the way you need it to be.
If you must bind large third-party libraries use automated generators like tolua, tolua++ (or even roll your own for the specific case). It would free you from manual work.
I would not recommend using Luabind. At the moment it's development stalled (however starting to come back to life), and if you would meet some corner case, you may be on your own. Also Luabind heavily uses template metaprogramming. This may (and may not) be unacceptable, depending on the point of view.