All,
Tried solution from @SaintAnne but doing multiple languages and calling from another Haxe source file somehow prevented any insertion of Comments.
For now I am working on other features and will hopefully in the next month give more detailed reply or ask for more help then.
THANKS !
It may be because while macro is executing you have the “macro” variable/constant/something defined, which takes priority over other platform defines. This disallows you to do #if cpp/js etc. So if you use, say, #if js inside a macro function then you typically will not have any output even if you compile to js. You have to use Context.defined( “js” ) for that.
@SaintAnne, All,
Your insight and advice was essential to get Comment insertion to work!
Thanks to all of you!
Below is Haxe source file that should allow anyone to insert Comments.
NOTE: I did not test all the target languages. The languages looked for is not a full list.
Tested for: cppia, cpp, cs, java, js, python
@Haxe Team
I think I read that
untyped __cpp__
syntax (for example) would be Deprecated sometime.
Perhaps below source is a test case so that when the new cpp.Syntax.code syntax happens there can be a way to let the community what to change going forward. Thanks!
And Yes, I put comments in the Comments.hx file so that not only experienced Haxians
but also people new to Haxe or even programming could still make sense of what was happening in the code.
package;
// Above: Use the same package name as where this code is used. Change to fit your needs
/*
* Comments.hx This supports Haxe inserting Comments in various output target programming languages.
*
* THANKS to Haxe Forum members
*
* Information here is correct about Haxe up to 4.0 rc1
*
* GOAL:
* Allow Haxe source code to have a way to put Comments in the generated programming language.
*
* Some generated language sources are not useful for inserting Comments.
* CppIA, HashLink and Neko are examples.
*
* BACKGROUND:
* Haxe compiler (as of 4.0 rc1) does Not support placing Comments from Haxe into target languages.
* There is some support of Comments for some target languages, but not all.
* And where you see actual Comments the support seems to be mostly to enable Debugging at Haxe source level.
* So actually where you see Comments seem to also be limited to inside code and Not anywhere in the source file.
*
* For more background see:
* https://community.haxe.org/t/how-to-have-comments-in-haxe-be-in-target-languages/1501
*
* LIMITATION:
* Because the Haxe macro approach is used to insert a Comment:
* Comments can ONLY be inserted from places where a Haxe macro may be used.
* So Comments are ONLY allowed within code and not other places in the target language source files.
*
* SOLUTION:
* Approach is noted in detail below.
*/
/**
* @author Haxe Forum members
*/
import haxe.macro.Expr;
import haxe.macro.Context;
class Comments
{
// Insert a Comment OR multiple lines of Comments into a Haxe target programming language.
//
// Example:
// comment( "Describe What is going on", "", " Alternate approaches to What is going on" );
// The second line will look like a blank line.
//
// Output looks like:
// Describe What is going on ;
// ;
// Alternate approaches to What is going on ;
//
// You may use as many quoted strings as you want, each quoted string will be on a separate line.
//
macro public static function comment( first : Expr, rest : Array< Expr > ) : Expr
{
// create a Default Warning as an array of just 1 macro Expression
// idea from https://code.haxe.org/category/macros/build-arrays.html
//
// NOTE: the Default is of the format style for C family of Comments.
// May produce a Compiler Error if target language has different format style of Comments.
var cmts = [ macro $v{ '/* Target programming language not checked for in Comments class ! */' } ];
// Languages checked for in Alphabetical order
// Approach: All the below use the Single Line comment style of the given target programming language
// Haxe adds a semicolon ( ; ) after inserting the macro Expression(s), (may not be true for all languages).
// As Single Line comment style was used, the ending semicolon is included as part of the inserted comment.
// This allows Haxe to tell that this is really a Comment.
//
// Looking at above Example the only visual clutter seems to be a vertical line of semicolons spaced out to the right.
// This approach successfully supports READABLE Comments in various Haxe target programming languages.
if ( Context.defined( "cppia" ) ) // C++ Instructions Assembly extension, set to be empty
cmts = [ first ].concat( rest ).map( extract ).map( x -> macro untyped __cppia__( '' ) );
else
if ( Context.defined( "cpp" ) ) // C++
cmts = [ first ].concat( rest ).map( extract ).map( x -> macro untyped __cpp__( '// $x ' ) );
else
if ( Context.defined( "cs" ) ) // C# ( CSharp )
cmts = [ first ].concat( rest ).map( extract ).map( x -> macro untyped __cs__( '// $x ' ) );
else
if ( Context.defined( "fl" ) ) // Flash
cmts = [ first ].concat( rest ).map( extract ).map( x -> macro untyped __fl__( '// $x ' ) );
else
if ( Context.defined( "hl" ) ) // HashLink set to be empty return
cmts = [ first ].concat( rest ).map( extract ).map( x -> macro untyped __hl__( '' ) );
else
if ( Context.defined( "java" ) )
cmts = [ first ].concat( rest ).map( extract ).map( x -> macro untyped __java__( '// $x ' ) );
else
if ( Context.defined( "js" ) ) // JavaScript
cmts = [ first ].concat( rest ).map( extract ).map( x -> macro untyped __js__( '// $x ' ) );
else
if ( Context.defined( "lua" ) )
cmts = [ first ].concat( rest ).map( extract ).map( x -> macro untyped __lua__( '-- $x ' ) );
else
if ( Context.defined( "neko" ) ) // Neko set to be empty return
cmts = [ first ].concat( rest ).map( extract ).map( x -> macro untyped __neko__( '' ) );
else
if ( Context.defined( "python" ) )
cmts = [ first ].concat( rest ).map( extract ).map( x -> macro untyped __python__( '# $x ' ) );
else
{
// Default already assigned.
}
return macro $b{ cmts };
}
// Check that a simple string is used as input.
// The string is padded on the right to a width of 80 with Blank spaces.
// The padding supports better READABILITY of the inserted Comment(s).
static function extract( e : Expr ) return
switch e.expr {
case EConst( CString( v ) ):
var temp = v;
if ( temp.length < 80 )
{
var str80 = " ";
temp = temp + str80.substr( 0, str80.length - temp.length );
}
temp;
case _: "not a proper comment";
}
}
All,
I was wrong saying I tested with Python. Exception when I run Python Interpreter:
... NameError("name '__python__' is not defined",)
Workaround is to delete all instances of the string
__python__("
from the main.py file (or whatever you call it).
This allows the next character # which is the start of a Single Line Comment.
Python runs without the Exception then.
@Haxe Team
To me, it looks like
untyped __python__
at least for a macro output to Python is actually Disabled and not just Deprecated. Please advise.
Thanks!
I also would like such a feature. Would be useful when writing a cross-platform library and you want to keep the javadoc in generated code for all your targets.
src/Comments.hx:93: characters 75-81 : Unbound identifier hl
HL target
src/Comments.hx:60: characters 12-14 : Type not found : hl.Syntax
src/Comments.hx:62: characters 12-14 : Type not found : hl.Syntax
I think some of the Haxe target languages do NOT have a Comment feature in the language.
I think HashLink, Neko, and CppIA targets do not allow comments.
I did NOT test any builds with HL, Neko or CppIA.
I put in handling for these and also other target languages anyway (like Lua) as a matter of completeness.
The idea was that someone (me? perhaps this year) would do more tests and add to Haxe docs an article about Comments in various targets. There is a difference between haxe 3.x and haxe 4.0 rc4 or rc5 that the actual API calls are different. So part of getting this code more friendly to Haxe developers is to ALSO have code that calls the correct API based on Haxe version. Hope this helps!
Those three aren’t even languages, they’re bytecode targets. So keeping the comments doesn’t make much sense.
© 2018-2020 Haxe Foundation - Powered by Discourse