help: fix documentation for String-openDocument

[supercollider.git] / HelpSource / Classes / String.schelp

CLASS::String
summary::array of characters
categories:: Collections>Ordered

DESCRIPTION::
String represents an array of characters.

Strings can be written literally using double quotes:
code::
"my string".class
::
A sequence of string literals will be concatenated together:
code::
x = "hel" "lo";
y = "this is a\n"
    "multiline\n"
    "string";
::

CLASSMETHODS::

private::initClass
private::doUnixCmdAction
private::unixCmdActions

method::readNew
Read the entire contents of a link::Classes/File:: and return them as a new String.

method::scDir
Provided for backwards compatibility.
returns::
the value of code::Platform.resourceDir::, which is the base resource directory of SuperCollider.
discussion::
Please use link::Classes/Platform#*resourceDir:: instead.

INSTANCEMETHODS::

private::prUnixCmd, prFormat, prCat, prBounds, hash, species, getSCDir, prDrawInRect, prDrawAtPoint, openTextFile

subsection:: Accessing characters

method::@, at
Strings respond to .at in a manner similar to other indexed collections. Each element is a link::Classes/Char::.
code::
"ABCDEFG".at(2)
::

method::ascii
Returns an Array of asci numbers of the Strings's characters.
code::
"wertvoll".ascii
::

subsection:: Comparing strings

method::compare
Returns a -1, 0, or 1 depending on whether the receiver should be sorted before the argument, is equal to the argument or should be sorted after the argument. This is a case sensitive compare.

method::<
Returns a link::Classes/Boolean:: whether the receiver should be sorted before the argument.
code::
"same" < "samf"
::

method::>
Returns a link::Classes/Boolean:: whether the receiver should be sorted after the argument.
code::
"same" > "samf"
::
method::<=
Returns a link::Classes/Boolean:: whether the receiver should be sorted before the argument, including the same string.
code::
"same" <= "same"
"same" <= "samf"
::

method::>=
Returns a link::Classes/Boolean:: whether the receiver should be sorted after the argument, including the same string.
code::
"same" >= "same"
"same" >= "samf"
::

method::==
Returns a link::Classes/Boolean:: whether the two Strings are equal.
note::
This method is (now) case sensitive!
::
code::
"same" == "same"
"same" == "Same"; // false
::

method::!=
Returns a link::Classes/Boolean:: whether the two Strings are not equal.
code::
"same" != "same"; // false
"same" != "Same"; 
::

subsection:: Posting strings

method::post
Prints the string to the current post window.
code::
"One".post; "Two".post;"";
::

method::postln
Prints the string and a carriage return to the current post window.
code::
"One".postln; "Two".postln;"";
::

method::postc, postcln
As link::#-post:: and link::#-postln::, but formatted as a comment.
code::
"This is a comment.".postcln;
::

method::postf
Prints a formatted string with arguments to the current post window. The % character in the format string is replaced by a string representation of an argument. To print a % character use \\% .
code::
postf("this % a %. pi = %, list = %\n", "is", "test", pi.round(1e-4), (1..4))

this is a test. pi = 3.1416, list = [ 1, 2, 3, 4 ]
::

method::postcs
As link::#-postln::, but posts the link::#-asCompileString#compileString:: of the reciever.
code::
List[1, 2, ["comment", [3, 2]], { 1.0.rand }].postcs;
::

method::error
Prepends an error banner and posts the string.
code::
"Do not press this button again".error;
::

method::warn
Prepends a warning banner and posts the string.
code::
"Do not press this button again".warn;
::

method::inform
Posts the string.
code::
"Do not press this button again".inform;
::

subsection:: Interpreting strings as code

method::compile
Compiles a String containing legal SuperCollider code and returns a Function.
code::
(
var f;
f = "2 + 1".compile.postln;
f.value.postln;
)
::

method::interpret
Compile and execute a String containing legal SuperCollider code, returning the result.
code::
"2 + 1".interpret.postln;
::

method::interpretPrint
Compile, execute and print the result of a String containing legal SuperCollider code.
code::
"2 + 1".interpretPrint;
::

subsection:: Converting strings

method::asCompileString
Returns a String formatted for compiling.
code::
(
var f;
f = "myString";
f.postln;
f.asCompileString.postln;
)
::

method::asSymbol
Return a link::Classes/Symbol:: derived from the String.
code::
(
var z;
z = "myString".asSymbol.postln;
z.class.postln;
)
::

method::asInteger
Return an link::Classes/Integer:: derived from the String. Strings beginning with non-numeric characters return 0.
code::
"4".asInteger.postln;
::

method::asFloat
Return a link::Classes/Float:: derived from the String. Strings beginning with non-numeric characters return 0.
code::
"4.3".asFloat.postln;
::

method::asSecs
Return a link::Classes/Float:: based on converting a time string in format (dd):hh:mm:ss.s. This is the inverse method to link::Classes/SimpleNumber#-asTimeString::.
code::
(45296.asTimeString).asSecs;
"32.1".asSecs;
"62.1".asSecs;          // warns
"0:0:59.9".asSecs;
"1:1:1.1".asSecs;
"-1".asSecs;            // neg sign supported
"-12:34:56".asSecs;
"12:-34:56".asSecs;     // warns
"-23:12.3456".asSecs;   //
"-1:00:00:00".asSecs;   // days too.
::

subsection:: Concatenate strings

method::++
Return a concatenation of the two strings.
code::
"hello" ++ "word"
::

method::+
Return a concatenation of the two strings with a space between them.
code::
"hello" + "word"
::

method::+/+
Path concatenation operator - useful for avoiding doubling-up slashes unnecessarily.
code::"foo"+/+"bar":: returns code::"foo/bar"::

method::catArgs
Concatenate this string with the following args.
code::
"These are some args: ".catArgs(\fish, SinOsc.ar, {4 + 3}).postln;
::

method::scatArgs
Same as link::#-catArgs::, but with spaces in between.
code::
"These are some args: ".scatArgs(\fish, SinOsc.ar, {4 + 3}).postln;
::

method::ccatArgs
Same as link::#-catArgs::, but with commas in between.
code::
"a String".ccatArgs(\fish, SinOsc.ar, {4 + 3}).postln;
::

method::catList, scatList, ccatList
As link::#-catArgs::, link::#-scatArgs:: and link::#-ccatArgs:: above, but takes a Collection (usually a link::Classes/List:: or an link::Classes/Array::) as an argument.
code::
"a String".ccatList([\fish, SinOsc.ar, {4 + 3}]).postln;
::



subsection:: Regular expressions

method::matchRegexp
POSIX regular expression matching. Returns true if the receiver (a regular expression pattern) matches the string passed to it. The strong::start:: is an offset where to start searching in the string (default: 0), strong::end:: where to stop.
code::
"c".matchRegexp("abcdefg", 2, 5); // true
"c".matchRegexp("abcdefg", 4, 5); // false

"behaviou?r".matchRegexp("behavior"); // true
"behaviou?r".matchRegexp("behaviour"); // true
"behaviou?r".matchRegexp("behavir"); // false
"b.h.v.r".matchRegexp("behavor"); // true
"b.h.vi*r".matchRegexp("behaviiiiir"); // true
"(a|u)nd".matchRegexp("und"); // true
"(a|u)nd".matchRegexp("and"); // true
"[a-c]nd".matchRegexp("ind"); // false
"[a-c]nd".matchRegexp("bnd"); // true
::

method::findRegexp
POSIX regular expression search.
code::
"foobar".findRegexp("o*bar");
"32424 334 /**aaaaaa*/".findRegexp("/\\*\\*a*\\*/");
"foobar".findRegexp("(o*)(bar)");
"aaaabaaa".findAllRegexp("a+");
::

method::findAllRegexp
Like link::#-findAll::, but use regular expressions.

subsection:: Searching strings

method::find
Returns the index of the string in the receiver, or nil if not found. If strong::ignoreCase:: is true, find makes no difference between uppercase and lowercase letters. The strong::offset:: is the point in the string where the search begins.
code::
"These are several words".find("are").postln;
"These are several words".find("fish").postln;
::

method::findBackwards
Same like link::#-find::, but starts at the end of the string.
code::
// compare:
"These words are several words".find("words"); // 6
"These words are several words".findBackwards("words"); // 24
::

method::findAll
Returns the indices of the string in the receiver, or nil if not found.
code::
"These are several words which are fish".findAll("are").postln;
"These are several words which are fish".findAll("fish").postln;
::

method::contains
Returns a link::Classes/Boolean:: indicating if the String contains string.
code::
"These are several words".contains("are").postln;
"These are several words".contains("fish").postln;
::

method::containsi
Same as link::#-contains::, but case insensitive.
code::
"These are several words".containsi("ArE").postln;
::

method::containsStringAt
Returns a link::Classes/Boolean:: indicating if the String contains string beginning at the specified index.
code::
"These are several words".containsStringAt(6, "are").postln;
::

method::icontainsStringAt
Same as link::#-containsStringAt::, but case insensitive.

method::beginsWith
method::endsWith
Returns true if this string begins/ends with the specified other string.
argument:: string
The other string
returns::
A link::Classes/Boolean::

subsection:: Manipulating strings

method::rotate
Rotate the string by n steps.
code::
"hello word".rotate(1)
::

method::scramble
Randomize the order of characters in the string.
code::
"hello word".scramble
::


method::replace
Like link::#-tr::, but with strings as arguments.
code::
"Here are several words which are fish".replace("are", "were");
::

method::format
Returns a formatted string with arguments. The % character in the format string is replaced by a string representation of an argument. To print a % character use \\% .
code::
format("this % a %. pi = %, list = %\n", "is", "test", pi.round(1e-4), (1..4))

this is a test. pi = 3.1416, list = [ 1, 2, 3, 4 ]
::

method::escapeChar
Add the escape character (\) before any character of your choice.
code::
// escape spaces:
"This will become a Unix friendly string".escapeChar($ ).postln;
::

method::quote
Return this string enclosed in double-quote ( teletype::":: ) characters.
code::
"tell your" + "friends".quote + "not to tread onto the lawn"
::

method::zeroPad
Return this string enclosed in space characters.
code::
"spaces".zeroPad.postcs;
::

method::underlined
Return this string followed by dashes in the next line ( teletype::-:: ).
code::
"underlined".underlined;
"underlined".underlined($~);
::

method::tr
Transliteration. Replace all instances of strong::from:: with strong::to::.
code::
":-(:-(:-(".tr($(, $)); //turn the frowns upside down
::


method::padLeft
method::padRight
Pad this string with strong::string:: so it fills strong::size:: character.
argument:: size
Number of characters to fill
argument:: string
Padding string
code::
"this sentence has thirty-nine letters".padRight(39, "-+");
"this sentence has thirty-nine letters".padLeft(39, "-+");
"this sentence more than thirteen letters".padRight(13, "-+"); // nothing to pad.
::

method::toUpper
Return this string with uppercase letters.
code::
"Please, don't be impolite".toUpper;
::

method::toLower
Return this string with lowercase letters.
code::
"SINOSC".toLower;
::

method::stripRTF
Returns a new String with all RTF formatting removed.
code::
(
// same as File-readAllStringRTF
g = File("/code/SuperCollider3/build/Help/UGens/Chaos/HenonC.help.rtf","r");
g.readAllString.stripRTF.postln;
g.close;
)
::

method::split
Returns an Array of Strings split at the separator. The separator is a link::Classes/Char::, a link::Classes/String::, or anything that can be converted into a string. It is strong::not:: included in the output array. The default separator is $/, handy for Unix paths.
code::
"This/could/be/a/Unix/path".split;
"These are several words".split($ );
"These are several words".split(" ");
"accgcagcttag".split("gc");
::

subsection:: Stream support

method::printOn
Print the String on stream.
code::
"Print this on Post".printOn(Post);

// equivalent to:
Post << "Print this on Post";
::

method::storeOn
Same as link::#-printOn::, but formatted link::#-asCompileString::.
code::
"Store this on Post".storeOn(Post);

// equivalent to:
Post <<< "Store this on Post";
::



subsection::Unix Support

Where relevant, the current working directory is the same as the location of the SuperCollider app and the shell is the Bourne shell (sh). Note that the cwd, and indeed the shell itself, does not persist:
code::
"echo $0".unixCmd; // print the shell (sh)
"pwd".unixCmd;
"cd Help/".unixCmd;
"pwd".unixCmd;

"export FISH=mackerel".unixCmd;
"echo $FISH".unixCmd;
::
It is however possible to execute complex commands:
code::
"pwd; cd Help/; pwd".unixCmd;
"export FISH=mackerel; echo $FISH".unixCmd;
::
Also on os x applescript can be called via osascript:
code::
"osascript -e 'tell application \"Safari\" to activate'".unixCmd;
::
Should you need an environment variable to persist you can use link::#-setenv::.

note::
Despite the fact that the method is called 'unixCmd', strong::it does work in Windows::. The string must be a DOS command, however: "dir" rather than "ls" for instance.
::

method::unixCmd
Execute a unix command asynchronously using the standard shell (sh).
argument:: action
A link::Classes/Function:: that is called when the process has exited. It is passed two arguments: the exit code and pid of the exited process.
argument:: postOutput
A link::Classes/Boolean:: that controls whether or not the output of the process is displayed in the post window.
returns::
An link::Classes/Integer:: - the pid of the newly created process. Use link::Classes/Integer#-pidRunning:: to test if a process is alive.
discussion::
Example:
code::
"ls Help".unixCmd;
"echo one; sleep 1; echo two; sleep 1".unixCmd { |res, pid| [\done, res, pid].postln };
::

method::unixCmdGetStdOut
Similar to link::#-unixCmd:: except that the stdout of the process is returned (synchronously) rather than sent to the post window.
code::
~listing = "ls Help".unixCmdGetStdOut; // Grab
~listing.reverse.as(Array).stutter.join.postln; // Mangle
::

method::systemCmd
Executes a unix command synchronously using the standard shell (sh).

returns:: Error code of the unix command

method::runInTerminal
Execute the String in a new terminal window (asynchronously).
argument::shell
The shell used to execute the string.
discussion::
note:: On OSX, the string is incorporated into a temporary script file and executed using the shell. ::
Example:
code::
"echo ---------Hello delightful SuperCollider user----------".runInTerminal;
::

method::setenv
Set the environment variable indicated in the string to equal the String strong::value::. This value will persist until it is changed or SC is quit. Note that if strong::value:: is a path you may need to call link::#-standardizePath:: on it.
code::
// all defs in this directory will be loaded when a local server boots
"SC_SYNTHDEF_PATH".setenv("~/scwork/".standardizePath);
"echo $SC_SYNTHDEF_PATH".unixCmd;
::

method::getenv
Returns the value contained in the environment variable indicated by the String.
code::
"USER".getenv;
::

method::unsetenv
Set the environment variable to nil.

method::mkdir
Make a directory from the given path location.

method::pathMatch
Returns an link::Classes/Array:: containing all paths matching this String. Wildcards apply, non-recursive.
code::
Post << "Help/*".pathMatch;
::

method::loadPaths
Perform link::#-pathMatch:: on this String, then load and execute all paths in the resultant link::Classes/Array::.
code::
//first prepare a file with some code...
(
var f = File("/tmp/loadPaths_example.scd", "w");
if(f.isOpen, {
        f.putString("\"This text is the result of a postln command which was loaded and executed by loadPaths\".postln");
}, {
        "test file could not be created - please edit the file's path above".warn;
});
f.close;
)

//then load the file...
"/tmp/loadPaths_example.scd".loadPaths; //This file posts some text
::

method::load
Load and execute the file at the path represented by the receiver.

method::loadRelative
Load and execute the file at the path represented by the receiver, interpreting the path as relative to the current document or text file. Requires that the file has been saved.

method::resolveRelative
Convert the receiver from a relative path to an absolute path, relative to the current document or text file. Requires that the current text file has been saved. Absolute paths are left untransformed.

method::standardizePath
Expand ~ to your home directory, and resolve aliases on OSX. See link::Classes/PathName:: for more complex needs. See link::Classes/File#*realpath:: if you want to resolve symlinks.
code::
"~/".standardizePath; //This will print your home directory
::


method::openOS
Open file, directory or URL via the operating system. On OSX this is implemented via teletype::open::, on Linux via
teletype::xdg-open:: and on Windows via teletype::start::.
code::
Platform.userConfigDir.openOS;
"http://supercollider.sf.net".openOS;
::

subsection::Pathname Support

Also see link::#-+/+:: for path concatenation.

method::shellQuote
Return a new string suitable for use as a filename in a shell command, by enclosing it in single quotes ( teletype::':: ).
If the string contains any single quotes they will be escaped.
discussion::
You should use this method on a path before embedding it in a string executed by link::#-unixCmd:: or link::#-systemCmd::.
code::
unixCmd("ls " + Platform.userExtensionDir.shellQuote)
::
note::
This works well with shells such as strong::bash::, other shells might need different quotation/escaping.
Apart from usage in the construction of shell commands, strong::escaping is not needed:: for paths passed to methods like pathMatch(path) or File.open(path).
::

method::absolutePath
method::asAbsolutePath
Return this path as an absolute path by prefixing it with link::Classes/File#*getcwd:: if necessary.

method::asRelativePath
Return this path as relative to the specified path.
argument::relativeTo
The path to make this path relative to.

method::withTrailingSlash
Return this string with a trailing slash if that was not already the case.

method::withoutTrailingSlash
Return this string without a trailing slash if that was not already the case.

method::basename
Return the filename from a Unix path.
code::
"Imaginary/Directory/fish.rtf".basename;
::

method::dirname
Return the directory name from a Unix path.
code::
"Imaginary/Directory/fish.rtf".dirname;
::

method::splitext
Split off the extension from a filename or path and return both in an link::Classes/Array:: as [path or filename, extension].
code::
"fish.rtf".splitext;
"Imaginary/Directory/fish.rtf".splitext;
::

subsection::YAML and JSON parsing

method::parseYAML
Parse this string as YAML/JSON.
returns::
A nested structure of link::Classes/Array::s (for sequences), link::Classes/Dictionary##Dictionaries:: (for maps) and link::Classes/String::s (for scalars).

method::parseYAMLFile
Same as code::parseYAML:: but parse a file directly instead of a string. This is faster than reading a file into a string and then parse it.

subsection::Document Support

method::newTextWindow
Create a new link::Classes/Document:: with this.
code::
"Here is a new Document".newTextWindow;
::

method::openDocument
Create a new link::Classes/Document:: from the path corresponding to this. The selection arguments will preselect the indicated range in the new window. Returns this.
code::
(
String.filenameSymbol.asString.openDocument(10, 20)
)
::

method::findHelpFile
Returns the path for the helpfile named this, if it exists, else returns nil.
code::
"Document".findHelpFile;
"foobar".findHelpFile;
::

method::help
Performs link::#-findHelpFile:: on this, and opens the file it if it exists, otherwise opens the main helpfile.
code::
"Document".help;
"foobar".help;
::

subsection::Misc methods

method::speak
Sends string to the speech synthesisier of the OS. (OS X only.) see: link::Classes/Speech::
code::
"hi i'm talking with the default voice now, i guess".speak;
::

method::inspectorClass
Returns class link::Classes/StringInspector::.


subsection::Drawing Support

The following methods must be called within an Window-drawFunc or a SCUserView-drawFunc function, and will only be visible once the window or the view is refreshed. Each call to Window-refresh SCUserView-refresh will 'overwrite' all previous drawing by executing the currently defined function.

See also: link::Classes/Window::, link::Classes/UserView::, link::Classes/Color::, and link::Classes/Pen::.

note::
for cross-platform GUIs, use code::Pen.stringAtPoint, Pen.stringInRect, Pen.stringCenteredIn, Pen.stringLeftJustIn, Pen.stringRightJustIn:: instead.
::

method::draw
Draws the String at the current 0@0 link::Classes/Point::. If not transformations of the graphics state have taken place this will be the upper left corner of the window. See also link::Classes/Pen::.
code::
(
w = Window.new.front;
w.view.background_(Color.white);
w.drawFunc = {
        "abababababa\n\n\n".scramble.draw
};
w.refresh
)
::

method::drawAtPoint
Draws the String at the given link::Classes/Point:: using the link::Classes/Font:: and link::Classes/Color:: specified.
code::
(
w = Window.new.front;
w.view.background_(Color.white);
w.drawFunc = {
        "abababababa\n\n\n".scramble.drawAtPoint(
                100@100,
                Font("Courier", 30),
                Color.blue(0.3, 0.5))
};
w.refresh;
)
::

method::drawInRect
Draws the String into the given link::Classes/Rect:: using the link::Classes/Font:: and link::Classes/Color:: specified.
code::
(
w = Window.new.front;
r = Rect(100, 100, 100, 100);
w.view.background_(Color.white);
w.drawFunc = {
        "abababababa\n\n\n".scramble.drawInRect(r, Font("Courier", 12), Color.blue(0.3, 0.5));
        Pen.strokeRect(r);
};
w.refresh;
)
::

method::drawCenteredIn
Draws the String into the given Rect using the Font and Color specified.
code::
(
w = Window.new.front;
w.view.background_(Color.white);
r = Rect(100, 100, 100, 100);
w.drawFunc = {
        "abababababa\n\n\n".scramble.drawCenteredIn(
                r,
                Font("Courier", 12),
                Color.blue(0.3, 0.5)
        );
        Pen.strokeRect(r);
};
w.refresh;
)
::

method::drawLeftJustIn
Draws the String into the given Rect using the Font and Color specified.
code::
(
w = Window.new.front;
w.view.background_(Color.white);
r = Rect(100, 100, 100, 100);
w.drawFunc = {
        "abababababa\n\n\n".scramble.drawLeftJustIn(
                r,
                Font("Courier", 12),
                Color.blue(0.3, 0.5)
        );
        Pen.strokeRect(r);
};
w.refresh;
)
::

method::drawRightJustIn
Draws the String into the given link::Classes/Rect:: using the link::Classes/Font:: and link::Classes/Color:: specified.
code::
(
w = Window.new.front;
w.view.background_(Color.white);
r = Rect(100, 100, 100, 100);
w.drawFunc = {
        "abababababa\n\n\n".scramble.drawRightJustIn(
                r,
                Font("Courier", 12),
                Color.blue(0.3, 0.5)
        );
        Pen.strokeRect(r);
};
w.refresh;
)
::

method::bounds
Tries to return a link::Classes/Rect:: with the size needed to fit this string if drawed with given font.
argument:: font
A link::Classes/Font::