make-escaped-string

Arguments: string &key (escape #\%) (passed (function alphanumericp)) escaped

If the argument string does not contain any characters that need to be escaped (as described below), then the value returned is the input argument string.

Otherwise, this function returns a new string in which some characters are replaces with the character triples %hh where % is the escape character (as specified by the escape keyword argument) and hh is the two-digit hexadecimal representation of the character code.

This function only handles characters with a char-code values under 256 (255 is the largest value that can be represented by a two-digit hex value).

Strings of this form are useful as companion arguments to the -ee command line argument. (See Command line argumentsand Further description of the -e and -ee command-line arguments, both in startup.htm.)

A character is replaced with the escaped sequence if any of the following is true:

• it is the escape character (default %)
• it satisfies the escaped argument (default nil, meaning no test)
• it fails the passed argument (default #'alphanumericp)

The escaped and passed arguments may be

• a single character; this case is satisfied only by an eql character
• a sequence of characters; this case is satisfied by any character that appears in the argument
• nil; this case is never satisfied (the default for escaped is nil, so in the default no characters are converted because of the value of escaped)
• t or :all; this case is satisfied by any character
• a predicate; this case is satisfied if the predicate returns nil when applied to the character (the default for passed is #'alphanumericp, so all numbers and letters except the value os escape but no other characters pass)

For example, suppose you want to evaluate the form (foo:bar #\a "efg") on startup. Constructing the correct comapnion argument to -e is difficult (we won't even try). But we can find the escaped string with this function (not we double the backslash and escape the double-quotes):

cl-user(34): (make-escaped-string "(foo:bar #\\a \"efg\")")
"%28foo%3abar%20%23%5ca%20%22efg%22%29"
cl-user(35): 

And use -ee %28foo%3abar%20%23%5ca%20%22efg%22%29.

The argument -ee %28foo%3abar%20%23%5ca%20%22efg%22%29, while obscure, conveys the desired expression with no trouble at all (and it can be decoded by hand if necessary).

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.