File: m4.info,  Node: Changequote,  Next: Changecom,  Prev: Dnl,  Up: Input Control

8.2 Changing the quote characters
=================================

The default quote delimiters can be changed with the builtin
‘changequote’:

 -- Builtin: changequote([START = `], [END = '])
     This sets START as the new begin-quote delimiter and END as the new
     end-quote delimiter.  If both arguments are missing, the default
     quotes (‘`’ and ‘'’) are used.  If START is void, then quoting is
     disabled.  Otherwise, if END is missing or void, the default
     end-quote delimiter (‘'’) is used.  The quote delimiters can be of
     any length.

     The expansion of ‘changequote’ is void.

     changequote(`[', `]')
     ⇒
     define([foo], [Macro [foo].])
     ⇒
     foo
     ⇒Macro foo.

   The quotation strings can safely contain non-ASCII characters.

     define(`a', `b')
     ⇒
     «a»
     ⇒«b»
     changequote(`«', `»')
     ⇒
     «a»
     ⇒a

   If no single character is appropriate, START and END can be of any
length.  Other implementations cap the delimiter length to five
characters, but GNU has no inherent limit.

     changequote(`[[[', `]]]')
     ⇒
     define([[[foo]]], [[[Macro [[[[[foo]]]]].]]])
     ⇒
     foo
     ⇒Macro [[foo]].

   Calling ‘changequote’ with START as the empty string will effectively
disable the quoting mechanism, leaving no way to quote text.  However,
using an empty string is not portable, as some other implementations of
‘m4’ revert to the default quoting, while others preserve the prior
non-empty delimiter.  If START is not empty, then an empty END will use
the default end-quote delimiter of ‘'’, as otherwise, it would be
impossible to end a quoted string.  Again, this is not portable, as some
other ‘m4’ implementations reuse START as the end-quote delimiter, while
others preserve the previous non-empty value.  Omitting both arguments
restores the default begin-quote and end-quote delimiters; fortunately
this behavior is portable to all implementations of ‘m4’.

     define(`foo', `Macro `FOO'.')
     ⇒
     changequote(`', `')
     ⇒
     foo
     ⇒Macro `FOO'.
     `foo'
     ⇒`Macro `FOO'.'
     changequote(`,)
     ⇒
     foo
     ⇒Macro FOO.

   There is no way in ‘m4’ to quote a string containing an unmatched
begin-quote, except using ‘changequote’ to change the current quotes.

   If the quotes should be changed from, say, ‘[’ to ‘[[’, temporary
quote characters have to be defined.  To achieve this, two calls of
‘changequote’ must be made, one for the temporary quotes and one for the
new quotes.

   The following is an example of how to use ‘changequote’ to output
what would normally be an unmatched quote string:

 -- Composite: lquo(IGNORED...)
 -- Composite: rquo(IGNORED...)
     Output the normal left or right quote string.

     define(`lquo', `ifelse(`$#', `0', ``$0'', `changequote(`[', `]')`dnl'
     changequote([`], ['])')')
     ⇒
     define(`rquo', `ifelse(`$#', `0', ``$0'', `changequote(`[', `]')dnl`
     'changequote([`], ['])')')
     ⇒
     Quotes in reverse: rquo:rquo() lquo:lquo()
     ⇒Quotes in reverse: rquo:' lquo:`
     define(`hi', `HELLO')dnl
     lquo()hi`'rquo()
     ⇒`HELLO'
     substr(`-hi-', 1, 2) substr(`-`hi'-', `1', `4')
     ⇒HELLO hi
     substr(`-'lquo()`hi'rquo()`-', `1', `4')
     ⇒hi
     substr(`-'lquo()hi`'rquo()`-', `1', `2')rquo()'
     ⇒Hrquo()

   The example chose to require an ignored parameter so that ‘lquo’ or
‘rquo’ are not recognized without ‘()’; but the use of ‘ifelse’ to make
the macros blind is not strictly needed.  On the other hand, the use of
‘dnl’ in the macro bodies was essential for proper quote nesting during
the ‘define’.  Note that the output of these macros do not directly
behave as quote strings; however, any context where expanded text is
rescanned back in the normal choice of quote strings does not care if
the quotes were supplied literally or via these macros.

   Macros are recognized in preference to the begin-quote string, so if
a prefix of START can be recognized as part of a potential macro name,
the quoting mechanism is effectively disabled.  Unless you use
‘changeword’ (*note Changeword::), this means that START should not
begin with a letter, digit, or ‘_’ (underscore).  However, even though
quoted strings are not recognized, the quote characters can still be
discerned in macro expansion and in trace output.

     define(`echo', `$@')
     ⇒
     define(`hi', `HI')
     ⇒
     changequote(`q', `Q')
     ⇒
     q hi Q hi
     ⇒q HI Q HI
     echo(hi)
     ⇒qHIQ
     changequote
     ⇒
     changequote(`-', `EOF')
     ⇒
     - hi EOF hi
     ⇒ hi  HI
     changequote
     ⇒
     changequote(`1', `2')
     ⇒
     hi1hi2
     ⇒hi1hi2
     hi 1hi2
     ⇒HI hi

   Quotes are recognized in preference to argument collection.  In
particular, if START is a single ‘(’, then argument collection is
effectively disabled.  For portability with other implementations, it is
a good idea to avoid ‘(’, ‘,’, and ‘)’ as the first character in START.

     define(`echo', `$#:$@:')
     ⇒
     define(`hi', `HI')
     ⇒
     changequote(`(',`)')
     ⇒
     echo(hi)
     ⇒0::hi
     changequote
     ⇒
     changequote(`((', `))')
     ⇒
     echo(hi)
     ⇒1:HI:
     echo((hi))
     ⇒0::hi
     changequote
     ⇒
     changequote(`,', `)')
     ⇒
     echo(hi,hi)bye)
     ⇒1:HIhibye:

   However, if you are not worried about portability, using ‘(’ and ‘)’
as quoting characters has an interesting property--you can use it to
compute a quoted string containing the expansion of any quoted text, as
long as the expansion results in both balanced quotes and balanced
parentheses.  The trick is realizing ‘expand’ uses ‘$1’ unquoted, to
trigger its expansion using the normal quoting characters, but uses
extra parentheses to group unquoted commas that occur in the expansion
without consuming whitespace following those commas.  Then ‘_expand’
uses ‘changequote’ to convert the extra parentheses back into quoting
characters.  Note that it takes two more ‘changequote’ invocations to
restore the original quotes.  Contrast the behavior on whitespace when
using ‘$*’, via ‘quote’, to attempt the same task.

     changequote(`[', `]')dnl
     define([a], [1, (b)])dnl
     define([b], [2])dnl
     define([quote], [[$*]])dnl
     define([expand], [_$0(($1))])dnl
     define([_expand],
       [changequote([(], [)])$1changequote`'changequote(`[', `]')])dnl
     expand([a, a, [a, a], [[a, a]]])
     ⇒1, (2), 1, (2), a, a, [a, a]
     quote(a, a, [a, a], [[a, a]])
     ⇒1,(2),1,(2),a, a,[a, a]

   If END is a prefix of START, the end-quote will be recognized in
preference to a nested begin-quote.  In particular, changing the quotes
to have the same string for START and END disables nesting of quotes.
When quote nesting is disabled, it is impossible to double-quote strings
across macro expansions, so using the same string is not done very
often.

     define(`hi', `HI')
     ⇒
     changequote(`""', `"')
     ⇒
     ""hi"""hi"
     ⇒hihi
     ""hi" ""hi"
     ⇒hi hi
     ""hi"" "hi"
     ⇒hi" "HI"
     changequote
     ⇒
     `hi`hi'hi'
     ⇒hi`hi'hi
     changequote(`"', `"')
     ⇒
     "hi"hi"hi"
     ⇒hiHIhi

   It is an error if the end of file occurs within a quoted string.

     `hello world'
     ⇒hello world
     `dangling quote
     ^D
     error→m4:stdin:2: ERROR: end of file in string

     ifelse(`dangling quote
     ^D
     error→m4:stdin:1: ERROR: end of file in string