diff options
author | Alexander Kriegisch <Alexander@Kriegisch.name> | 2021-04-10 19:19:39 +0700 |
---|---|---|
committer | Alexander Kriegisch <Alexander@Kriegisch.name> | 2021-04-10 19:19:39 +0700 |
commit | 92edca3ea7a482d59a9086b1cb61413ed8604b67 (patch) | |
tree | d709ab2fd24a563cf626fb5ff354a0972a1dc6a9 /docs/adk15ProgGuideDB/varargs.xml | |
parent | 79c272eb9c158a976b7b3313c50759dd87b1b5fd (diff) | |
download | aspectj-92edca3ea7a482d59a9086b1cb61413ed8604b67.tar.gz aspectj-92edca3ea7a482d59a9086b1cb61413ed8604b67.zip |
Remove indentation from <programlisting> blocks in docs
Many dozens (hundreds?) of documentation code blocks were indented to
match the surrounding XML or just arbitrarily. The thing is: Inside
<programlisting> tags, similar to <pre> tags, line feeds and leading
whitespace are being preserved, which looked very awkward in the HTML
documentation. While a few files were mostly correct in this respect,
which shows that it was meant to be like that, many others were not.
This was tedious, stupid work to fix, but it had to be done.
Please note that the documentation was in no way updated content-wise.
This is also overdue, but not my focus here.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Diffstat (limited to 'docs/adk15ProgGuideDB/varargs.xml')
-rw-r--r-- | docs/adk15ProgGuideDB/varargs.xml | 143 |
1 files changed, 71 insertions, 72 deletions
diff --git a/docs/adk15ProgGuideDB/varargs.xml b/docs/adk15ProgGuideDB/varargs.xml index 487a8c01d..31dddde80 100644 --- a/docs/adk15ProgGuideDB/varargs.xml +++ b/docs/adk15ProgGuideDB/varargs.xml @@ -1,21 +1,21 @@ <chapter id="varargs" xreflabel="Varargs"> <title>Varargs</title> - + <sect1 id="varargs-inJava5" xreflabel="Varargs in Java 5"> <title>Variable-length Argument Lists in Java 5</title> - + <para> - Java 5 (and hence AspectJ 5) allows you to specify methods that take a + Java 5 (and hence AspectJ 5) allows you to specify methods that take a variable number of arguments of a specified type. This is achieved using - an ellipsis (...) in the method signature as shown: + an ellipsis (...) in the method signature as shown: </para> <programlisting><![CDATA[ - public void foo(int i, String... strings) { - } - ]]></programlisting> - +public void foo(int i, String... strings) { +} +]]></programlisting> + <para> A method or constructor may take at most one variable length argument, and this must always be the last declared argument in the signature. @@ -23,82 +23,81 @@ <sect2 id="calling-methods-and-constructors-with-variable-length-arguments" xreflabel="calling-methods-and-constructors-with-variable-length-arguments"> <title>Calling Methods and Constructors with variable-length arguments</title> - + <para> A <emphasis>varargs</emphasis> method may be called with zero or more arguments - in the variable argument position. For example, given the definition of + in the variable argument position. For example, given the definition of <literal>foo</literal> above, the following calls are all legal: </para> <programlisting><![CDATA[ - foo(5); - foo(5,"One String"); - foo(7,"One String","Two Strings"); - foo(3,"One String","Two Strings","Three Strings"); - ]]></programlisting> +foo(5); +foo(5,"One String"); +foo(7,"One String","Two Strings"); +foo(3,"One String","Two Strings","Three Strings"); +]]></programlisting> - <para>A <emphasis>varargs</emphasis> parameter is treated as an array within the + <para>A <emphasis>varargs</emphasis> parameter is treated as an array within the defining member. So in the body of <literal>foo</literal> we could write for example: </para> <programlisting><![CDATA[ - public void foo(int i, String... strings) { - String[] someStrings = strings; - // rest of method body - } - ]]></programlisting> +public void foo(int i, String... strings) { + String[] someStrings = strings; + // rest of method body +} +]]></programlisting> <para>One consequence of this treatment of a varargs parameter as an array is that you can also call a varargs method with an array:</para> <programlisting><![CDATA[ - foo(7,new String[] {"One String","Two Strings"}); - ]]></programlisting> - +foo(7,new String[] {"One String","Two Strings"}); +]]></programlisting> + </sect2> - + </sect1> <sect1 id="varargs-in-pcds"> <title>Using Variable-length arguments in advice and pointcut expressions</title> - + <para>AspectJ 5 allows variable-length arguments to be used for methods declared within aspects, and for inter-type declared methods and constructors, in accordance with the rules outlined in the previous section.</para> - + <para> AspectJ 5 also allows variable length arguments to be matched by pointcut expressions and bound as formals in advice. </para> - + <sect2 id="matching-signatures-based-on-variable-length-argument-types" xreflabel="matching-signatures-based-on-variable-length-argument-types"> <title>Matching signatures based on variable length argument types</title> - + <para> Recall from the definition of signature patterns given in the chapter on annotations (<xref linkend="signaturePatterns"/>), that <literal>MethodPattern</literal> and <literal>ConstructorPattern</literal> are extended to allow a <literal>varargs</literal> pattern in the last argument position of a method or constructor signature. </para> - - <programlisting><![CDATA[ - FormalsPattern := '..' (',' FormalsPatternAfterDotDot)? | - OptionalParensTypePattern (',' FormalsPattern)* | - TypePattern '...' - - FormalsPatternAfterDotDot := - OptionalParensTypePattern (',' FormalsPatternAfterDotDot)* | - TypePattern '...' - - ]]></programlisting> - + + <programlisting><![CDATA[ +FormalsPattern := '..' (',' FormalsPatternAfterDotDot)? | + OptionalParensTypePattern (',' FormalsPattern)* | + TypePattern '...' + +FormalsPatternAfterDotDot := + OptionalParensTypePattern (',' FormalsPatternAfterDotDot)* | + TypePattern '...' +]]></programlisting> + <para> Method and constructor patterns are used in the <literal>call</literal>, <literal>execution</literal>, <literal>initialization</literal>, <literal>preinitialization</literal>, and <literal>withincode</literal> pointcut designators. Some examples of usage follow: - </para> - + </para> + <variablelist> <varlistentry> @@ -121,7 +120,7 @@ </para> </listitem> </varlistentry> - + <varlistentry> <term>initialization(org.xyz.*.new((Foo || Goo)...))</term> <listitem> @@ -134,30 +133,30 @@ </para> </listitem> </varlistentry> - + </variablelist> - + <para>A variable argument parameter and an array parameter are treated as distinct signature elements, so given the method definitions: </para> <programlisting><![CDATA[ - void foo(String...); - void bar(String[]); - ]]></programlisting> - +void foo(String...); +void bar(String[]); +]]></programlisting> + <para> The pointcut <literal>execution(* *.*(String...))</literal> matches the execution join point - for <literal>foo</literal>, but not <literal>bar</literal>. The pointcut + for <literal>foo</literal>, but not <literal>bar</literal>. The pointcut <literal>execution(* *.*(String[]))</literal> matches the execution join point for <literal>bar</literal> but not <literal>foo</literal>. </para> - + </sect2> - + <sect2 id="exposing-variable-length-arguments-as-context-in-pointcuts-and-advice" xreflabel="exposing-variable-length-arguments-as-context-in-pointcuts-and-advice"> <title>Exposing variable-length arguments as context in pointcuts and advice</title> - + <para> When a varargs parameter is used within the body of a method, it has an array type, as discussed in the introduction to this section. We follow the @@ -166,9 +165,9 @@ </para> <programlisting><![CDATA[ - public void foo(int i, String... strings) { - } - ]]></programlisting> +public void foo(int i, String... strings) { +} +]]></programlisting> <para> The call or execution join points for <literal>foo</literal> will be matched @@ -176,34 +175,34 @@ to use the varargs syntax within an args pointcut designator - so you <emphasis>cannot</emphasis> write <literal>args(int,String...)</literal>. </para> - + <para> Binding of a varargs parameter in an advice statement is straightforward: </para> - + <programlisting><![CDATA[ - before(int i, String[] ss) : call(* foo(int,String...)) && args(i,ss) { - // varargs String... argument is accessible in advice body through ss - // ... - } - ]]></programlisting> - +before(int i, String[] ss) : call(* foo(int,String...)) && args(i,ss) { + // varargs String... argument is accessible in advice body through ss + // ... +} +]]></programlisting> + <para>Since you cannot use the varargs syntax in the <literal>args</literal> pointcut designator, you also cannot use the varargs syntax to declare - advice parameters.</para> - - <para>Note: the proposal in this section does not allow you to + advice parameters.</para> + + <para>Note: the proposal in this section does not allow you to distinguish between a join point with a signature (int, String...) - and a join point with a signature (int, String[]) based + and a join point with a signature (int, String[]) based <emphasis>solely</emphasis> on the use of the <literal>args</literal> pointcut designator. If this distinction is required, <literal>args</literal> - can always be coupled with <literal>call</literal> or + can always be coupled with <literal>call</literal> or <literal>execution</literal>.</para> </sect2> - + </sect1> - + </chapter> |