Grokbase Groups Ant user June 2011
FAQ

[Ant-user] Syntax for Names: target, property, macrodef, etc.

Steve Amerige
Jun 30, 2011 at 11:52 am
I'm looking for the authoritative specification within Ant for the value of the name attribute as in:

<property name="xxx" .../>
<macrodef name="xxx" ...>
<target name="xxx" ...>

and so forth. I can't find within the Ant manual any BNF that defines what a valid name is allowed to be.

I do see:

http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/datatypes.html#NMTOKEN

However, without the Ant manual explicitly telling me that this is something that applies to the name value for property, macrodef,
target, etc., I can't be 100% sure. Maybe property allows for one syntax. Maybe macrodef allows for another.

Is there a BNF description of the Ant language anywhere?
Can anyone help me to understand authoritatively what is allowed for name values and where in the Ant manual or specification I can
read more?

Many thanks for any assistance!

Best regards,
Steve Amerige
SAS Institute, Deployment Software Development
reply

Search Discussions

8 responses

  • Dominique Devienne at Jun 30, 2011 at 1:32 pm

    On Thu, Jun 30, 2011 at 6:51 AM, Steve Amerige wrote:
    I'm looking for the authoritative specification within Ant for the value of
    the name attribute as in:

    <property name="xxx" .../>
    <macrodef name="xxx" ...>
    <target name="xxx" ...>

    and so forth.  I can't find within the Ant manual any BNF that defines what
    a valid name is allowed to be.
    Anything goes really, AFAIK. There is no specifications.

    Some names will create issues, for example <target name="-foo"> can't
    be called from the command line because -foo will be interpreted as a
    CLI switch and since not found Ant will error out. This "behavior" is
    relied upon to have "private" targets.

    Also remember this is XML land, so attribute whitespace normalization
    will apply (depending on the parser used possibly) which may result in
    some whitespaces being removed.

    But aside from these quirks, Ant does not put any restrictions on
    names in general. --DD

    PS: Also keep in mind that property expansion does occurs inside these
    names, but I assume you mean the names after expansion.

    ---------------------------------------------------------------------
    To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
    For additional commands, e-mail: user-help@ant.apache.org
  • Steve Amerige at Jun 30, 2011 at 1:52 pm
    Hi Dominique,

    Thanks for the info. And, also thanks for the specific example of the leading "-" character.

    Because Ant has only a global namespace for property names (and other names like macrodef, etc.), and for the case that a particular
    ant script inherits properties from the caller, I'm adopting a convention that will help us know whether a particular name is local
    to the being-called ant script. In particular, I'm favoring the convention that "local" names begin with a dot. We guarantee that
    the caller never has defined any names that begin with a dot, so there is never a problem with conflicts. I had considered both the
    "-" and the "." as a leading character to indicate the name is local. But, you've given a good reason to avoid "-". Thanks!

    Enjoy,
    Steve Amerige
    SAS Institute, Deployment Software Developer
    On 6/30/2011 9:31 AM, Dominique Devienne wrote:
    On Thu, Jun 30, 2011 at 6:51 AM, Steve Amerigewrote:
    I'm looking for the authoritative specification within Ant for the value of
    the name attribute as in:

    <property name="xxx" .../>
    <macrodef name="xxx" ...>
    <target name="xxx" ...>

    and so forth. I can't find within the Ant manual any BNF that defines what
    a valid name is allowed to be.
    Anything goes really, AFAIK. There is no specifications.

    Some names will create issues, for example<target name="-foo"> can't
    be called from the command line because -foo will be interpreted as a
    CLI switch and since not found Ant will error out. This "behavior" is
    relied upon to have "private" targets.

    Also remember this is XML land, so attribute whitespace normalization
    will apply (depending on the parser used possibly) which may result in
    some whitespaces being removed.

    But aside from these quirks, Ant does not put any restrictions on
    names in general. --DD

    PS: Also keep in mind that property expansion does occurs inside these
    names, but I assume you mean the names after expansion.

    ---------------------------------------------------------------------
    To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
    For additional commands, e-mail: user-help@ant.apache.org



    ---------------------------------------------------------------------
    To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
    For additional commands, e-mail: user-help@ant.apache.org
  • Dominique Devienne at Jun 30, 2011 at 3:55 pm

    On Thu, Jun 30, 2011 at 8:31 AM, Dominique Devienne wrote:
    On Thu, Jun 30, 2011 at 6:51 AM, Steve Amerige wrote:
    I'm looking for the authoritative specification within Ant for the value of the name attribute
    PS: Also keep in mind that property expansion does occurs inside these
    names, but I assume you mean the names after expansion.
    Hmmm, I believe that's wrong on second thought.

    Target names are not expanded I now recall, and it's probably the same
    for property and macro names.

    Someone might want to give a more definitive answer on that. --DD

    ---------------------------------------------------------------------
    To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
    For additional commands, e-mail: user-help@ant.apache.org
  • Matt Benson at Jun 30, 2011 at 4:43 pm

    On Thu, Jun 30, 2011 at 10:54 AM, Dominique Devienne wrote:
    On Thu, Jun 30, 2011 at 8:31 AM, Dominique Devienne wrote:
    On Thu, Jun 30, 2011 at 6:51 AM, Steve Amerige wrote:
    I'm looking for the authoritative specification within Ant for the value of the name attribute
    PS: Also keep in mind that property expansion does occurs inside these
    names, but I assume you mean the names after expansion.
    Hmmm, I believe that's wrong on second thought.

    Target names are not expanded I now recall, and it's probably the same
    for property and macro names.
    A property name would be expanded as in <property name="value.${foo}"
    value="bar" />. I never thought about macrodefs, and I don't think we
    have any generic way to call a macro defined in such a fashion (though
    ISTR having played with such at some point long ago), but I think it
    *would* be expanded.

    Matt
    Someone might want to give a more definitive answer on that. --DD

    ---------------------------------------------------------------------
    To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
    For additional commands, e-mail: user-help@ant.apache.org
    ---------------------------------------------------------------------
    To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
    For additional commands, e-mail: user-help@ant.apache.org
  • Steve Amerige at Jun 30, 2011 at 4:51 pm
    Hi Dominique and all,

    After considering that scriptdef, macrodef, and perhaps some other tags do not allow neither the "-" nor the "." as an initial
    character, I'm going to use the "_" character name prefix to indicate that a name is "local" to the current JVM. For example:

    <var name="_i" value="1"/>

    Again, the point of this convention is to workaround the fact that my understanding is that there is no scoping for *property*,
    *var*, and other names in Ant. So, is my understanding incorrect?

    Can one use namespaces to have real local variables, properties, etc.? Is there any notion of scoping? I'd love to hear what Ant
    is capable of doing with respect to var, property, macrodef, scriptdef, etc. scoping for Ant 1.6, 1.7, and 1.8.

    Thanks for your help.... it's very much appreciated!

    Best regards,
    Steve Amerige
    SAS Institute, Deployment Software Developer
    On 6/30/2011 11:54 AM, Dominique Devienne wrote:
    On Thu, Jun 30, 2011 at 8:31 AM, Dominique Deviennewrote:
    On Thu, Jun 30, 2011 at 6:51 AM, Steve Amerigewrote:
    I'm looking for the authoritative specification within Ant for the value of the name attribute
    PS: Also keep in mind that property expansion does occurs inside these
    names, but I assume you mean the names after expansion.
    Hmmm, I believe that's wrong on second thought.

    Target names are not expanded I now recall, and it's probably the same
    for property and macro names.

    Someone might want to give a more definitive answer on that. --DD
  • Matt Benson at Jun 30, 2011 at 5:10 pm

    On Thu, Jun 30, 2011 at 11:50 AM, Steve Amerige wrote:
    Hi Dominique and all,

    After considering that scriptdef, macrodef, and perhaps some other tags do
    not allow neither the "-" nor the "." as an initial character, I'm going to
    use the "_" character name prefix to indicate that a name is "local" to the
    current JVM.  For example:

    <var name="_i" value="1"/>

    Again, the point of this convention is to workaround the fact that my
    understanding is that there is no scoping for *property*, *var*, and other
    names in Ant.  So, is my understanding incorrect?

    Can one use namespaces to have real local variables, properties, etc.?  Is
    there any notion of scoping?  I'd love to hear what Ant is capable of doing
    with respect to var, property, macrodef, scriptdef, etc. scoping for Ant
    1.6, 1.7, and 1.8.
    Certainly there isn't much in the way of scoping for earlier versions
    of Ant, though you can do things with varying degrees of success using
    libraries along the lines of ant-contrib (there are most likely others
    to assist in this). As of Ant 1.8, the <local> task was provided to
    declare a "level of locality" for a named property, i.e. "any changes
    made to property P at or below the current scope are considered local
    to this block." The manual page for this task describes its use in
    what I consider adequate (at least) detail. As it took some doing (by
    Peter O'Reilly as well as myself, if I recall correctly) to get this
    functioning properly, I would heartily recommend its use.

    Matt
    Thanks for your help.... it's very much appreciated!

    Best regards,
    Steve Amerige
    SAS Institute, Deployment Software Developer
    On 6/30/2011 11:54 AM, Dominique Devienne wrote:

    On Thu, Jun 30, 2011 at 8:31 AM, Dominique Devienne<ddevienne@gmail.com>
    wrote:
    On Thu, Jun 30, 2011 at 6:51 AM, Steve Amerige<Steve.Amerige@sas.com>
    wrote:
    I'm looking for the authoritative specification within Ant for the value
    of the name attribute
    PS: Also keep in mind that property expansion does occurs inside these
    names, but I assume you mean the names after expansion.
    Hmmm, I believe that's wrong on second thought.

    Target names are not expanded I now recall, and it's probably the same
    for property and macro names.

    Someone might want to give a more definitive answer on that. --DD
    ---------------------------------------------------------------------
    To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
    For additional commands, e-mail: user-help@ant.apache.org
  • Steve Amerige at Jul 7, 2011 at 2:31 pm
    When I look at the 1.8.2 codebase, I see in:

    ant-1.8.2\src\main\org\apache\tools\ant\taskdefs\MacroDef.java

    /**
    * Check if a character is a valid character for an element or
    * attribute name.
    *
    * @param c the character to check
    * @return true if the character is a letter or digit or '.' or '-'
    * attribute name
    */
    public static boolean isValidNameCharacter(char c) {
    // ? is there an xml api for this ?
    return Character.isLetterOrDigit(c) || c == '.' || c == '-';
    }

    This seems to be at odds with the specification:

    http://www.w3.org/TR/xml/#sec-common-syn


    Names and Tokens

    [4] |NameStartChar| ::= |":" | [A-Z] | "_" | [a-z] | [#xC0-#xD6] | [#xD8-#xF6] | [#xF8-#x2FF] | [#x370-#x37D] | [#x37F-#x1FFF]
    [#x200C-#x200D] | [#x2070-#x218F] | [#x2C00-#x2FEF] | [#x3001-#xD7FF] | [#xF900-#xFDCF] | [#xFDF0-#xFFFD] | [#x10000-#xEFFFF]|
    [4a] |NameChar| ::= |NameStartChar <http://www.w3.org/TR/xml/#NT-NameStartChar> | "-" | "." | [0-9] | #xB7 | [#x0300-#x036F] |
    [#x203F-#x2040]|
    [5] |Name| ::= |NameStartChar <http://www.w3.org/TR/xml/#NT-NameStartChar> (NameChar <http://www.w3.org/TR/xml/#NT-NameChar>)*|
    [6] |Names| ::= |Name <http://www.w3.org/TR/xml/#NT-Name> (#x20 Name <http://www.w3.org/TR/xml/#NT-Name>)*|
    [7] |Nmtoken| ::= |(NameChar <http://www.w3.org/TR/xml/#NT-NameChar>)+|
    [8] |Nmtokens| ::= |Nmtoken <http://www.w3.org/TR/xml/#NT-Nmtoken> (#x20 Nmtoken <http://www.w3.org/TR/xml/#NT-Nmtoken>)*|


    I've also looked at:

    ant-1.8.2\src\main\org\apache\tools\ant\taskdefs\AntStructure.java

    /**
    * Does this String match the XML-NMTOKEN production?
    * @param s the string to test
    * @return true if the string matches the XML-NMTOKEN
    */
    public static final boolean isNmtoken(String s) {
    final int length = s.length();
    for (int i = 0; i < length; i++) {
    char c = s.charAt(i);
    // XXX - we are committing CombiningChar and Extender here
    if (!Character.isLetterOrDigit(c)
    && c != '.' && c != '-' && c != '_' && c != ':') {
    return false;
    }
    }
    return true;
    }

    Maybe I'm looking at the wrong part in the code for where *element* names (such as macrodef and scriptdef) are validated and where
    other names (such as property name="...") are validated. But, the Ant code doesn't match what is specified by the XML BNF. Also,
    the XML BNF doesn't seem to allow spaces in a *Name* object. Is there an Ant BNF specification that reflects the code?

    Is there any formal specification for Ant syntax? Where do I find it?

    Sorry to be a bother! But, I'm just trying to be very clear in understanding Ant and am hoping that a formal specification exists.

    Many thanks!
    Steve Amerige
    SAS Institute, Deployment Software Developer

    On 6/30/2011 9:31 AM, Dominique Devienne wrote:
    On Thu, Jun 30, 2011 at 6:51 AM, Steve Amerigewrote:
    I'm looking for the authoritative specification within Ant for the value of
    the name attribute as in:

    <property name="xxx" .../>
    <macrodef name="xxx" ...>
    <target name="xxx" ...>

    and so forth. I can't find within the Ant manual any BNF that defines what
    a valid name is allowed to be.
    Anything goes really, AFAIK. There is no specifications.

    Some names will create issues, for example<target name="-foo"> can't
    be called from the command line because -foo will be interpreted as a
    CLI switch and since not found Ant will error out. This "behavior" is
    relied upon to have "private" targets.

    Also remember this is XML land, so attribute whitespace normalization
    will apply (depending on the parser used possibly) which may result in
    some whitespaces being removed.

    But aside from these quirks, Ant does not put any restrictions on
    names in general. --DD

    PS: Also keep in mind that property expansion does occurs inside these
    names, but I assume you mean the names after expansion.
  • Stefan Bodewig at Jul 10, 2011 at 4:42 pm

    On 2011-07-07, Steve Amerige wrote:

    When I look at the 1.8.2 codebase, I see in:
    ant-1.8.2\src\main\org\apache\tools\ant\taskdefs\MacroDef.java
    public static boolean isValidNameCharacter(char c) {
    // ? is there an xml api for this ?
    return Character.isLetterOrDigit(c) || c == '.' || c == '-';
    }
    This method is indeed used to validate attribute names and names of
    nested elements of tasks defined as macrodefs (but not for the taks name
    itself which is not formally restricted at all).
    This seems to be at odds with the specification:
    http://www.w3.org/TR/xml/#sec-common-syn
    Quite possible, we never really targeted full conformance but somethign
    I'd call "good enough".
    I've also looked at:
    ant-1.8.2\src\main\org\apache\tools\ant\taskdefs\AntStructure.java
    public static final boolean isNmtoken(String s) {
    AntStructure is a task that has been writen ages ago to write an
    approximation of a DTD for a running Ant instance (each Ant run could in
    fact produce a different DTD because new elements would be added by
    taskdefs). The task has never claimed to be useful 8-)
    Maybe I'm looking at the wrong part in the code for where *element*
    names (such as macrodef and scriptdef) are validated and where other
    names (such as property name="...") are validated.
    You are.

    In the end the XML parser decides what is a valid name and what is not.
    Ant will not stop you from creating tasks with macro/script/taskdef that
    are nor legal XML element names, you will just not be able to use them
    because the parser will bail out. We do have some checks in place but
    they are - as you've found out - incomplete or even wrong.

    For "normal" tasks - tasks written in Java - attribute names and names
    of nested elements are determined by method names and thus are way more
    restricted than their XML counterparts. You can't have a "." or a "-"
    in a method name and thus can't write a task in Java with an attribute
    that would contain such a character.

    I don't think we have any rules on property names at all. Same for
    target names. Beyond the restrictions the XML parser will create, that
    is (obviously you can't contains a 0 character in any XML document).

    Some names will put you into trouble, though. Target names that
    contains commas (quite possible we prohibit it, not sure) would be
    unusable in a depends attribute of a different target for example.
    Properties whose names contain "$" or "}" will be difficult to use as
    well.
    But, the Ant code doesn't match what is specified by the XML BNF.
    This is true. If you feel there is a real problem, feel free to provide
    a patch 8-). The difference between the formal specification and Ant's
    code is likely to be in areas that haven't caused problems in practice
    (or bugs would have been reported).
    Also, the XML BNF doesn't seem to allow spaces in a *Name* object. Is
    there an Ant BNF specification that reflects the code?
    Is there any formal specification for Ant syntax? Where do I find it?
    None that I was aware of.
    Sorry to be a bother! But, I'm just trying to be very clear in
    understanding Ant and am hoping that a formal specification exists.
    I'm afraid there isn't. The various IDE integration projects that
    support writing Ant build files may have something, but even than you
    can't be sure it will contain the full truth or rather "just work in
    practice".

    Sorry

    Stefan

    ---------------------------------------------------------------------
    To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
    For additional commands, e-mail: user-help@ant.apache.org

Related Discussions

Discussion Navigation
viewthread | post