~ubuntu-branches/ubuntu/hoary/ess/hoary

Go to the <A HREF="ess_1.html">first</A>, <A HREF="ess_5.html">previous</A>, <A HREF="ess_7.html">next</A>, <A HREF="ess_16.html">last</A> section, <A HREF="ess_toc.html">table of contents</A>.

<HR>

<H1><A NAME="SEC35" HREF="ess_toc.html#TOC35">Interacting with the ESS process</A></H1>

The primary function of the ESS package is to provide an easy-to-use

front end to the S interpreter. This is achieved by running the S

process from within an Emacs buffer, so that the Emacs editing commands

are available to correct mistakes in commands, etc. The features of

Inferior S mode are similar to those provided by the standard Emacs

shell mode (see section `Shell Mode' in <CITE>The Gnu Emacs Reference Manual</CITE>). Command-line completion of S objects and a number of `hot

keys' for commonly-used S commands are also provided for ease of

typing.

<UL>

<LI><A HREF="ess_6.html#SEC36">Command-line editing</A>: Entering commands and fixing mistakes

<LI><A HREF="ess_6.html#SEC37">Completion</A>: Completion of object names

<LI><A HREF="ess_6.html#SEC38">Completion details</A>: Advanced completion concepts

<LI><A HREF="ess_6.html#SEC39">Transcript</A>: Manipulating the transcript

<LI><A HREF="ess_6.html#SEC44">Command History</A>: Command History

<LI><A HREF="ess_6.html#SEC45">History expansion</A>: References to historical commands

<LI><A HREF="ess_6.html#SEC46">Hot keys</A>: Hot keys for common commands

<LI><A HREF="ess_6.html#SEC47">Statistical Process running in ESS?</A>

<LI><A HREF="ess_6.html#SEC48">Other</A>: Other commands provided by inferior-ESS

</UL>

<H2><A NAME="SEC36" HREF="ess_toc.html#TOC36">Entering commands and fixing mistakes</A></H2>

Sending a command to the ESS process is as simple as typing it in

and pressing the <KBD>RETURN</KBD> key:

<UL>

<LI>

<KBD>RET</KBD> (<CODE>inferior-ess-send-input</CODE>)

Send the command on the current line to the ESS process.

</UL>

If you make a typing error before pressing <KBD>RET</KBD> all the usual Emacs

editing commands are available to correct it (see section `Basic editing commands' in <CITE>The GNU Emacs Reference Manual</CITE>). Once the

command has been corrected you can press <KBD>RETURN</KBD> (even if the

cursor is not at the end of the line) to send the corrected command to

the ESS process.

ESS provides some other commands which are useful for fixing mistakes:

<UL>

<LI>

<KBD>C-c C-w</KBD> (<CODE>backward-kill-word</CODE>)

Deletes the previous word (such as an object name) on the command line.

<LI>

<KBD>C-c C-u</KBD> (<CODE>comint-kill-input</CODE>)

Deletes everything from the prompt to point. Use this to abandon a

command you have not yet sent to the ESS process.

<LI>

<KBD>C-c C-a</KBD> (<CODE>comint-bol</CODE>)

Move to the beginning of the line, and then skip forwards past the

prompt, if any.

</UL>

100

See section `Shell Mode' in <CITE>The Gnu Emacs Reference Manual</CITE>, for other

101

commands relevant to entering input.

102

103

104

105

106

<H2><A NAME="SEC37" HREF="ess_toc.html#TOC37">Completion of object names</A></H2>

107

108

109

110

111

112

113

In the process buffer, the <KBD>TAB</KBD> key is for completion, similar to

114

that provided by Shell Mode for filenames. In Inferior S mode,

115

pressing the <KBD>TAB</KBD> key when the cursor is following the first few

116

characters of an object name completes the object name; if the

117

cursor is following a file name <KBD>TAB</KBD> completes the file name.

118

119

120

121

<UL>

122

<LI>

123

124

<KBD>TAB</KBD> (<CODE>comint-dynamic-complete</CODE>)

125

126

Complete the S object name or filename before point.

127

</UL>

128

129

130

When the cursor is just after a partially-completed object name,

131

pressing <KBD>TAB</KBD> provides completion in a similar fashion to

132

133

134

except that completion is performed over all known S object names

135

instead of file names. ESS maintains a list of all objects known to S

136

at any given time, which basically consists of all objects (functions

137

and datasets) in every attached directory listed by the <CODE>search()</CODE>

138

command

139

140

along with the component objects of attached data frames

141

142

(if your version of S supports them).

143

144

145

146

For example, consider the three functions (available in Splus version

147

3.0) called <CODE>binomplot()</CODE>, <CODE>binom.test()</CODE> and

148

<CODE>binomial()</CODE>. Typing <KBD>bin TAB</KBD> after the S prompt will

149

insert the characters <SAMP>`om'</SAMP>, completing the longest prefix

150

(<SAMP>`binom'</SAMP>) which distinguishes these three commands. Pressing

151

<KBD>TAB</KBD> once more provides a list of the three commands which have

152

this prefix, allowing you to add more characters (say, <SAMP>`.'</SAMP>) which

153

specify the function you desire. After entering more characters

154

pressing <KBD>TAB</KBD> yet again will complete the object name up to

155

uniqueness, etc. If you just wish to see what completions exist without

156

adding any extra characters, type <KBD>M-?</KBD>.

157

158

159

160

<UL>

161

<LI>

162

163

<KBD>M-?</KBD> (<CODE>ess-list-object-name-completions</CODE>)

164

165

List all possible completions of the object name at point.

166

</UL>

167

168

169

ESS also provides completion over the components of named lists accessed

170

using the <SAMP>`$'</SAMP> notation, to any level of nested lists. This feature

171

is particularly useful for checking what components of a list object

172

exist while partway through entering a command: simply type the object

173

name and <SAMP>`$'</SAMP> and press <KBD>TAB</KBD> to see the names of existing list

174

components for that object.

175

176

177

178

179

180

181

Completion is also provided over file names, which is particularly

182

useful when using S functions such as <CODE>get()</CODE> or <CODE>scan()</CODE>

183

which require fully expanded file names. Whenever the cursor is within

184

an S string, pressing <KBD>TAB</KBD> completes the file name before

185

point, and also expands any <SAMP>`~'</SAMP> or environment variable references.

186

187

188

189

If the cursor is not in a string and does not follow a (partial) object

190

name, the <KBD>TAB</KBD> key has a third use: it expands history references.

191

See section <A HREF="ess_6.html#SEC45">References to historical commands</A>.

192

193

194

195

196

<H2><A NAME="SEC38" HREF="ess_toc.html#TOC38">Completion details</A></H2>

197

198

199

ESS automatically keeps track of any objects added or deleted to the

200

system (such as new objects created, or directories added to the search

201

list) to make completion as accurate as possible. Whenever ESS notices

202

that search list has changed

203

204

<A NAME="DOCF2" HREF="ess_foot.html#FOOT2">(2)</A> when you attach a directory or data

205

frame, the objects associated with it immediately become available for a

206

completion; when it is detached completion is no longer available on

207

those objects.

208

209

210

211

To maintain a list of accessible objects for completion, ESS needs to

212

determine which objects are contained in each directory or data frame on

213

the search list. This is done at the start of each S session, by

214

running the <CODE>objects()</CODE> command on every element of the search

215

list. On some systems, however, this can be rather slow; it's doubly

216

frustrating when you consider that most of the directories on the search

217

list are the standard S libraries, which never change anyway! When

218

ESS was installed, a database of the standard object names should have

219

been created which should speed up this process at the start of an S

220

session; if it has not been created you will get a warning like

221

`S-namedb.el does not exist'. See section <A HREF="ess_2.html#SEC7">Installing ESS on your system</A>, for information on

222

how to create this database.

223

224

225

226

Efficiency in completion is gained by maintaining a cache of objects

227

currently known to S; when a new object becomes available or is deleted,

228

only one component of the cache corresponding to the associated

229

directory needs to be refreshed. If ESS ever becomes confused about

230

what objects are available for completion (such as when if refuses to

231

complete an object you know is there), the command <KBD>M-x

232

ess-resynch</KBD>

233

234

forces the entire cache to be refreshed, which should fix the

235

problem.

236

237

238

239

240

<H2><A NAME="SEC39" HREF="ess_toc.html#TOC39">Manipulating the transcript</A></H2>

241

242

243

Most of the time, the cursor spends most of its time at the bottom of

244

the ESS process buffer, entering commands. However all the input

245

and output from the current (and previous) ESS sessions is stored in

246

the process buffer (we call this the transcript) and often we want to

247

248

move back up through the buffer, to look at the output from previous

249

commands for example.

250

251

252

253

Within the process buffer, a paragraph

254

255

is defined as the prompt, the command after the prompt, and the output

256

from the command. Thus <KBD>M-{</KBD> and <KBD>M-}</KBD> move you backwards and

257

forwards, respectively, through commands in the transcript. A

258

particularly useful command is <KBD>M-h</KBD> (<CODE>mark-paragraph</CODE>) which

259

will allow you to mark a command and its entire output (for deletion,

260

perhaps). For more information about paragraph commands,

261

see section `Paragraphs' in <CITE>The GNU Emacs Reference Manual</CITE>.

262

263

264

265

If an ESS process finishes and you restart it in the same process

266

buffer, the output from the new ESS process appears after the output

267

from the first ESS process separated by a form-feed (<SAMP>`^L'</SAMP>)

268

character. Thus pages in the ESS

269

270

process buffer correspond to ESS sessions. Thus, for example, you may

271

use <KBD>C-x [</KBD> and <KBD>C-x ]</KBD> to move backward and forwards through

272

ESS sessions in a single ESS process buffer. For more information about

273

page commands, see section `Pages' in <CITE>The GNU Emacs Reference Manual</CITE>.

274

275

276

277

<UL>

278

<LI><A HREF="ess_6.html#SEC40">Last command</A>: Manipulating the output from the last command

279

<LI><A HREF="ess_6.html#SEC41">Process buffer motion</A>: Viewing more historic commands

280

<LI><A HREF="ess_6.html#SEC42">Transcript resubmit</A>: Re-submitting commands from the transcript

281

<LI><A HREF="ess_6.html#SEC43">Saving transcripts</A>: Keeping a record of your S session

282

</UL>

283

284

285

286

<H3><A NAME="SEC40" HREF="ess_toc.html#TOC40">Manipulating the output from the last command</A></H3>

287

288

289

Viewing the output of the command you have just entered is a common

290

occurrence and ESS provides a number of facilities for doing this.

291

Whenever a command produces a longish output, it is possible that the

292

window will scroll, leaving the next prompt near the middle of the

293

window. The first part of the command output may have scrolled off the

294

top of the window, even though the entire output would fit in the window

295

if the prompt were near the bottom of the window. If this happens, you

296

can use the command

297

298

299

300

<UL>

301

<LI>

302

303

<KBD>C-c C-e</KBD> (<CODE>comint-show-maximum-output</CODE>)

304

305

Move to the end of the buffer, and place cursor on bottom line of

306

window.

307

</UL>

308

309

310

to make more of the last output visible. (To make this happen

311

automatically for all inputs, set the variable

312

<CODE>comint-scroll-to-bottom-on-input</CODE> to <CODE>t</CODE>; for information on

313

this and other options for handling process input and output

314

see section `Shell Mode Options' in <CITE>The GNU Emacs Reference Manual</CITE>.)

315

316

317

318

If the first part of the output is still obscured, use

319

320

321

<UL>

322

<LI>

323

324

<KBD>C-c C-r</KBD> (<CODE>comint-show-output</CODE>)

325

326

Moves cursor to the previous command line and and places it at the top

327

of the window.

328

</UL>

329

330

331

to view it. Finally, if you want to discard the last command output

332

altogether, use

333

334

335

336

<UL>

337

<LI>

338

339

<KBD>C-c C-o</KBD> (<CODE>comint-kill-output</CODE>)

340

341

342

Deletes everything from the last command to the current prompt.

343

</UL>

344

345

346

to delete it. Use this command judiciously to keep your transcript to a

347

more manageable size.

348

349

350

351

352

<H3><A NAME="SEC41" HREF="ess_toc.html#TOC41">Viewing more historic commands</A></H3>

353

354

355

If you want to view the output from more historic commands than the

356

previous command, commands are also provided to move backwards and

357

forwards through previously entered commands in the process buffer:

358

359

360

361

<UL>

362

<LI>

363

364

<KBD>C-c C-p</KBD> (<CODE>comint-previous-input</CODE>)

365

366

Moves point to the preceding command in the process buffer.

367

368

<LI>

369

370

<KBD>C-c C-n</KBD> (<CODE>comint-next-input</CODE>)

371

372

Moves point to the next command in the process buffer.

373

</UL>

374

375

376

Note that these two commands are analogous to <KBD>C-p</KBD> and <KBD>C-n</KBD>

377

but apply to command lines rather than text lines. And just like

378

<KBD>C-p</KBD> and <KBD>C-n</KBD>, passing a prefix argument to these commands

379

means to move to the <VAR>ARG</VAR>'th next (or previous) command. (These

380

commands are also discussed in section `Shell History Copying' in <CITE>The GNU Emacs Reference Manual</CITE>.)

381

382

383

384

There are also two similar commands (not bound to any keys by default)

385

which move to preceding or succeeding commands, but which first prompt

386

for a regular expression (see section `Syntax of Regular Expression' in <CITE>The GNU Emacs Reference Manual</CITE>), and then moves to

387

the next (previous) command matching the pattern.

388

389

390

391

<DL>

392

<DT>Command: comint-backward-matching-input regexp arg

393

394

<DT>Command: comint-forward-matching-input regexp arg

395

396

Search backward (forward) through the transcript buffer for the

397

<VAR>arg</VAR>'th previous (next) command matching <VAR>regexp</VAR>. <VAR>arg</VAR>

398

is the prefix argument; <VAR>regexp</VAR> is prompted for in the minibuffer.

399

</DL>

400

401

402

403

404

<H3><A NAME="SEC42" HREF="ess_toc.html#TOC42">Re-submitting commands from the transcript</A></H3>

405

406

407

When moving through the transcript, you may wish to re-execute some of

408

the commands you find there. ESS provides three commands to do this;

409

these commands may be used whenever the cursor is within a command line

410

in the transcript (if the cursor is within some command output,

411

an error is signaled). Note all three commands involve the <KBD>RETURN</KBD>

412

key.

413

414

415

416

<UL>

417

<LI>

418

419

<KBD>RET</KBD> (<CODE>inferior-ess-send-input</CODE>)

420

421

Copy the command under the cursor to the current command line, and

422

execute it.

423

424

<LI>

425

426

<KBD>C-c RET</KBD> (<CODE>comint-copy-old-input</CODE>)

427

428

Copy the command under the cursor to the current command line, but don't

429

execute it. Leaves the cursor on the command line so that the copied

430

command may be edited.

431

432

<LI>

433

434

<KBD>M-RET</KBD> (<CODE>ess-transcript-send-command-and-move</CODE>)

435

436

Copy the command under the cursor to the current command line, and

437

execute it. Moves the cursor to the following command.

438

</UL>

439

440

441

When the cursor is not after the current prompt, the <KBD>RETURN</KBD> key

442

has a slightly different behavior than usual. Pressing <KBD>RET</KBD> on any

443

line containing a command that you entered (i.e. a line beginning with a

444

prompt) sends that command to the ESS process once again. If you

445

wish to edit the command before executing it, use <KBD>C-c RET</KBD> instead;

446

it copies the command to the current prompt but does not execute it,

447

allowing you to edit it before submitting it.

448

449

450

451

These two commands leave the cursor at the new command line, allowing

452

you to continue with interactive use of S. If you wish to resubmit a

453

series of commands from the transcript, consider using <KBD>M-RET</KBD>

454

instead, which leaves the cursor at the command line following the one

455

you re-submitted. Thus by using <KBD>M-RET</KBD> repeatedly, you can

456

re-submit a whole series of commands.

457

458

459

460

These commands work even if if the current line is a continuation line

461

(i.e. the prompt is <SAMP>`+'</SAMP> instead of <SAMP>`>'</SAMP>) -- in this case all

462

the lines that form the multi-line command are concatenated together and

463

the resulting command is sent to the ESS process (currently this is

464

the only way to resubmit a multi-line command to the ESS process in

465

one go). If the current line does

466

467

not begin with a prompt, an error is signaled. This feature, coupled

468

with the command-based motion commands described above, could be used as

469

a primitive history mechanism. ESS provides a more sophisticated

470

mechanism, however, which is described in section <A HREF="ess_6.html#SEC44">Command History</A>.

471

472

473

474

475

<H3><A NAME="SEC43" HREF="ess_toc.html#TOC43">Keeping a record of your S session</A></H3>

476

477

478

To keep a record of your S session in a disk file, use the Emacs

479

command <KBD>C-x C-w</KBD> (<CODE>write-file</CODE>) to attach a file to the

480

ESS process buffer. The name of the process buffer will (probably)

481

change to the name of the file, but this is not a problem. You can

482

still use S as usual; just remember to save the file before you quit

483

Emacs with <KBD>C-x C-s</KBD>. You can make ESS prompt you for a filename in

484

which to save the transcript every time you start S by setting the

485

variable

486

487

<CODE>ess-ask-about-transfile</CODE> to <CODE>t</CODE>; see section <A HREF="ess_3.html#SEC16">Changing the startup actions</A>.

488

489

We recommend you save your transcripts with filenames that end in

490

<SAMP>`.St'</SAMP>. There is a special mode (ESS transcript mode ---

491

see section <A HREF="ess_9.html#SEC59">Manipulating saved transcript files</A>) for editing transcript files which is

492

automatically selected for files with this suffix.

493

494

495

496

497

S transcripts can get very large, so some judicious editing is

498

appropriate if you are saving it in a file. Use <KBD>C-c C-o</KBD> whenever

499

a command produces excessively long output (printing large arrays, for

500

example). Delete erroneous commands (and the resulting error messages

501

or other output) by moving to the command (or its output) and typing

502

<KBD>M-h C-w</KBD>. Also, remember that <KBD>C-c C-e</KBD> (and other hot keys)

503

may be used for commands whose output you do not wish to appear in the

504

transcript. These suggestions are appropriate even if you are not

505

saving your transcript to disk, since the larger the transcript, the

506

more memory your Emacs process will use on the host machine.

507

508

509

510

Finally, if it is your intention to produce S source code (suitable

511

for using with <CODE>source()</CODE> or inclusion in an S function) from a

512

transcript, then the command <KBD>M-x ess-clean-region</KBD> may be of use.

513

514

This command works in any Emacs buffer, and removes all prompts and

515

command output from an ESS transcript within the current region, leaving

516

only the commands. Don't forget to remove any erroneous commands first!

517

518

519

520

521

<H2><A NAME="SEC44" HREF="ess_toc.html#TOC44">Command History</A></H2>

522

523

524

525

526

527

528

529

ESS provides easy-to-use facilities for re-executing or editing previous

530

commands. An input history of the last few commands is maintained (by

531

default the last 50 commands are stored, although this can be changed by

532

setting the variable <CODE>comint-input-ring-size</CODE> in

533

534

<CODE>inferior-ess-mode-hook</CODE>.) The simplest history commands simply

535

select the next and previous commands in the input history:

536

537

538

539

<UL>

540

<LI>

541

542

<KBD>M-p</KBD> (<CODE>comint-previous-input</CODE>)

543

544

Select the previous command in the input history.

545

546

<LI>

547

548

<KBD>M-n</KBD> (<CODE>comint-next-input</CODE>)

549

550

Select the next command in the input history.

551

</UL>

552

553

554

For example, pressing <KBD>M-p</KBD> once will re-enter the last command into

555

the process buffer after the prompt but does not send it to the ESS

556

process, thus allowing editing or correction of the command before the

557

ESS process sees it. Once corrections have been made, press

558

<KBD>RET</KBD> to send the edited command to the ESS process.

559

560

561

562

If you want to select a particular command from the history by matching

563

it against a regular expression (see section `Syntax of Regular Expression' in <CITE>The GNU Emacs Reference Manual</CITE>), to search for a

564

particular variable name for example, these commands are also available:

565

566

567

568

<UL>

569

<LI>

570

571

<KBD>M-r</KBD> (<CODE>comint-previous-matching-input</CODE>)

572

573

Prompt for a regular expression, and search backwards through the input

574

history for a command matching the expression.

575

576

<LI>

577

578

<KBD>M-s</KBD> (<CODE>comint-next-matching-input</CODE>)

579

580

Prompt for a regular expression, and search backwards through the input

581

history for a command matching the expression.

582

</UL>

583

584

585

A common type of search is to find the last command that began with a

586

particular sequence of characters; the following two commands provide an

587

easy way to do this:

588

589

590

591

<UL>

592

<LI>

593

594

<KBD>A-M-r</KBD> (<CODE>comint-previous-matching-input-from-input</CODE>)

595

596

Select the previous command in the history which matches the string

597

typed so far.

598

599

<LI>

600

601

<KBD>A-M-s</KBD> (<CODE>comint-next-matching-input-from-input</CODE>)

602

603

Select the next command in the history which matches the string typed so

604

far.

605

</UL>

606

607

608

Instead of prompting for a regular expression to match against, as they

609

instead select commands starting with those characters already entered.

610

For instance, if you wanted to re-execute the last <CODE>attach()</CODE>

611

command, you may only need to type <KBD>att</KBD> and then <KBD>A-M-r</KBD> and

612

<KBD>RET</KBD>. (Note: you may not have an <KBD>ALT</KBD> key on your keyboard,

613

in which case it may be a good idea to bind these commands to some other

614

keys.)

615

616

617

618

See section `Shell History Ring' in <CITE>The GNU Emacs Reference Manual</CITE>, for a more detailed discussion of the history mechanism.

619

620

621

622

623

<H2><A NAME="SEC45" HREF="ess_toc.html#TOC45">References to historical commands</A></H2>

624

625

626

Instead of searching through the command history using the command

627

described in the previous section, you can alternatively refer to a

628

historical command directly using a notation very similar to that used

629

in <CODE>csh</CODE>. History references are introduced by a <SAMP>`!'</SAMP> or

630

<SAMP>`^'</SAMP> character and have meanings as follows:

631

632

633

634

635

636

<DD>

637

The immediately previous command

638

639

640

<DD>

641

The <VAR>N</VAR>th previous command

642

643

644

<DD>

645

The last command beginning with the string <SAMP>`text'</SAMP>

646

647

648

<DD>

649

The last command containing the string <SAMP>`text'</SAMP>

650

</DL>

651

652

653

In addition, you may follow the reference with a word designator

654

to select particular words of the input. A word is defined as a

655

sequence of characters separated by whitespace. (You can modify this

656

definition by setting the value of <CODE>comint-delimiter-argument-list</CODE>

657

to a list of characters that are allowed to separate words and

658

659

themselves form words.) Words are numbered beginning with zero. The

660

word designator usually begins with a <SAMP>`:'</SAMP> (colon) character;

661

however it may be omitted if the word reference begins with a <SAMP>`^'</SAMP>,

662

<SAMP>`$'</SAMP>, <SAMP>`*'</SAMP> or <SAMP>`-'</SAMP>. If the word is to be selected from the

663

previous command, the second <SAMP>`!'</SAMP> character can be omitted from the

664

event specification. For instance, <SAMP>`!!:1'</SAMP> and <SAMP>`!:1'</SAMP> both

665

refer to the first word of the previous command, while <SAMP>`!!$'</SAMP> and

666

<SAMP>`!$'</SAMP> both refer to the last word in the previous command. The

667

format of word designators is as follows:

668

669

670

671

672

673

<DD>

674

The zeroth word (i.e. the first one on the command line)

675

676

677

<DD>

678

The <VAR>n</VAR>th word, where <VAR>n</VAR> is a number

679

680

681

<DD>

682

The first word (i.e. the second one on the command line)

683

684

685

<DD>

686

The last word

687

688

689

<DD>

690

A range of words; <SAMP>`-<VAR>y</VAR>'</SAMP> abbreviates <SAMP>`0-<VAR>y</VAR>'</SAMP>

691

692

693

<DD>

694

All the words except the zeroth word, or nothing if the command had just

695

one word (the zeroth)

696

697

698

<DD>

699

Abbreviates <VAR>x</VAR>-$

700

701

702

<DD>

703

Like <SAMP>`<VAR>x</VAR>*'</SAMP>, but omitting the last word

704

</DL>

705

706

707

In addition, you may surround the entire reference except for the first

708

<SAMP>`!'</SAMP> by braces to allow it to be followed by other (non-whitespace)

709

characters (which will be appended to the expanded reference).

710

711

712

713

Finally, ESS also provides quick substitution; a reference like

714

<SAMP>`^old^new^'</SAMP> means "the last command, but with the first occurrence

715

of the string <SAMP>`old'</SAMP> replaced with the string <SAMP>`new'</SAMP>" (the last

716

<SAMP>`^'</SAMP> is optional). Similarly, <SAMP>`^old^'</SAMP> means "the last

717

command, with the first occurrence of the string <SAMP>`old'</SAMP> deleted"

718

(again, the last <SAMP>`^'</SAMP> is optional).

719

720

721

722

To convert a history reference as described above to an input suitable

723

for S, you need to expand the history reference, using the

724

<KBD>TAB</KBD> key. For this to work, the cursor must be preceded by a space

725

(otherwise it would try to complete an object name) and not be within a

726

string (otherwise it would try to complete a filename). So to expand

727

the history reference, type <KBD>SPC TAB</KBD>. This will convert the

728

history reference into an S command from the history, which you can

729

then edit or press <KBD>RET</KBD> to execute.

730

731

732

733

For example, to execute the last command that referenced the variable

734

<CODE>data</CODE>, type <KBD>!?data SPC TAB RET</KBD>.

735

736

737

738

739

<H2><A NAME="SEC46" HREF="ess_toc.html#TOC46">Hot keys for common commands</A></H2>

740

741

742

ESS provides a number of commands for executing the commonly used

743

functions. These commands below are basically information-gaining

744

commands (such as <CODE>objects()</CODE> or <CODE>search()</CODE>) which tend to

745

clutter up your transcript and for this reason some of the hot keys

746

display their output in a temporary buffer instead of the process buffer

747

by default. This behavior is controlled by the variable

748

<CODE>ess-execute-in-process-buffer</CODE> which, if

749

750

non-<CODE>nil</CODE>, means that these commands will produce their output in

751

the process buffer instead. In any case, passing a prefix argument to

752

the commands (with <KBD>C-u</KBD>) will reverse the meaning of

753

<CODE>ess-execute-in-process-buffer</CODE> for that command, i.e. the output

754

will be displayed in the process buffer if it usually goes to a

755

temporary buffer, and vice-versa. These are the hot keys that behave in

756

this way:

757

758

759

760

<UL>

761

<LI>

762

763

<KBD>C-c C-x</KBD> (<CODE>ess-execute-objects</CODE>)

764

765

Sends the <CODE>objects()</CODE>

766

767

command to the ESS process. A prefix argument specifies the

768

position on the search list (use a negative argument to toggle

769

<CODE>es-execute-in-process-buffer</CODE> as well). A quick way to see what

770

objects are in your working directory.

771

772

773

774

<LI>

775

776

<KBD>C-c C-s</KBD> (<CODE>ess-execute-search</CODE>)

777

778

Sends the <CODE>search()</CODE>

779

780

command to the ESS process.

781

782

783

784

<LI>

785

786

<KBD>C-c C-e</KBD> (<CODE>ess-execute</CODE>)

787

788

Prompt for an ESS expression, and evaluate it.

789

</UL>

790

791

792

<CODE>ess-execute</CODE> may seem pointless when you could just type the

793

command in anyway, but it proves useful for `spot' calculations which

794

would otherwise clutter your transcript, or for evaluating an expression

795

while partway through entering a command. You can also use this command

796

to generate new hot keys using the Emacs keyboard macro facilities;

797

see section `Keyboard Macros' in <CITE>The GNU Emacs Reference Manual</CITE>.

798

799

800

801

802

803

The following hot keys do not use <CODE>ess-execute-in-process-buffer</CODE>

804

to decide where to display the output -- they either always display in

805

the process buffer or in a separate buffer, as indicated:

806

807

808

809

<UL>

810

<LI>

811

812

<KBD>C-c C-a</KBD> (<CODE>ess-execute-attach</CODE>)

813

814

Prompts for a directory to attach to the ESS process with the

815

<CODE>attach()</CODE> command.

816

817

If a numeric prefix argument is given it is used as the position on the

818

search list to attach the directory; otherwise the S default of 2 is

819

used. The <CODE>attach()</CODE> command actually executed appears in the

820

process buffer.

821

822

<LI>

823

824

<KBD>C-c C-l</KBD> (<CODE>ess-load-file</CODE>)

825

826

Prompts for a file to load into the ESS process using

827

<CODE>source()</CODE>. If there is an error during loading, you can jump to

828

the error in the file with <KBD>C-x `</KBD> (<CODE>ess-parse-errors</CODE>).

829

830

See section <A HREF="ess_7.html#SEC52">Detecting errors in source files</A>, for more details.

831

832

<LI>

833

834

<KBD>C-c C-v</KBD> (<CODE>ess-display-help-on-object</CODE>) Pops up a help

835

buffer for an S object or function. See section <A HREF="ess_8.html#SEC58">Reading help files in ESS</A> for more

836

details.

837

838

<LI>

839

840

<KBD>C-c C-q</KBD> (<CODE>ess-quit</CODE>)

841

842

843

Sends the <CODE>q()</CODE>

844

845

command to the ESS process (or <CODE>(exit)</CODE>

846

847

to the XLS process), and cleans up any temporary buffers (such as

848

help buffers or edit buffers) you may have created along the way. Use

849

this command when you have finished your S session instead of simply

850

typing <CODE>q()</CODE> yourself, otherwise you will need to issue the command

851

<KBD>M-x ess-cleanup</KBD>

852

853

854

855

856

command explicitly to make sure that all the files that need to be saved

857

have been saved, and that all the temporary buffers have been killed.

858

</UL>

859

860

861

862

<H2><A NAME="SEC47" HREF="ess_toc.html#TOC47">Is the Statistical Process running under ESS?</A></H2>

863

864

865

866

867

For the S languages (S, S-Plus, R) ESS sets an option in the current

868

process that programs in the language can check to determine the

869

environment in which they are currently running.

870

871

872

873

ESS sets

874

<CODE>options(STERM="iESS")</CODE> for S language processes running in an

875

inferior <CODE>iESS[S]</CODE> or <CODE>iESS[R]</CODE> buffer.

876

877

878

879

ESS sets

880

<CODE>options(STERM="ddeESS")</CODE> for independent S-Plus for Windows

881

processes running in the GUI and communicating with ESS via

882

the DDE (Microsoft Dynamic Data Exchange) protocol through a

883

<CODE>ddeESS[S]</CODE> buffer.

884

885

886

887

Other values of <CODE>options()$STERM</CODE> that we recommend are:

888

889

890

891

<UL>

892

<LI><CODE>length</CODE>: Fixed length xterm or telnet window.

893

894

<LI><CODE>scrollable</CODE>: Unlimited length xterm or telnet window.

895

896

<LI><CODE>server</CODE>: S-Plus Stat Server.

897

898

<LI><CODE>BATCH</CODE>: BATCH.

899

900

<LI><CODE>Rgui</CODE>: R GUI.

901

902

<LI><CODE>Commands</CODE>: S-Plus GUI without DDE interface to ESS.

903

904

</UL>

905

906

907

Additional values may be recommended in the future as new interaction

908

protocols are created. Unlike the values <CODE>iESS</CODE> and <CODE>ddeESS</CODE>,

909

ESS can't set these other values since the S language program is not

910

under the control of ESS.

911

912

913

914

915

<H2><A NAME="SEC48" HREF="ess_toc.html#TOC48">Other commands provided by inferior-ESS</A></H2>

916

917

918

The following commands are also provided in the process buffer:

919

920

921

922

<UL>

923

<LI>

924

925

<KBD>C-c C-c</KBD> (<CODE>comint-interrupt-subjob</CODE>)

926

927

Sends a Control-C signal to the ESS process. This has the effect of

928

929

930

aborting the current command.

931

932

<LI>

933

934

<KBD>C-c C-z</KBD> (<CODE>ess-abort</CODE>)

935

936

937

Sends a STOP signal to the ESS process, killing it immediately.

938

It's not a good idea to use this, in general: Neither <CODE>q()</CODE> nor

939

<CODE>.Last</CODE> will be executed and device drivers will not finish

940

cleanly. This command is provided as a safety to

941

<CODE>comint-stop-subjob</CODE>, which is usually bound to <KBD>C-c C-z</KBD>. If

942

you want to quit from S, use <KBD>C-c C-q</KBD> (<CODE>ess-quit</CODE>) instead.

943

944

945

946

<LI>

947

948

<KBD>C-c C-d</KBD> (<CODE>ess-dump-object-into-edit-buffer</CODE>)

949

950

Prompts for an object to be edited in an edit buffer. See section <A HREF="ess_7.html#SEC49">Editing S functions</A>.

951

</UL>

952

953

954

Other commands available is Inferior S mode are discussed in

955

section `Shell Mode' in <CITE>The Gnu Emacs Reference Manual</CITE>.

956

957

958

<HR>

959

Go to the <A HREF="ess_1.html">first</A>, <A HREF="ess_5.html">previous</A>, <A HREF="ess_7.html">next</A>, <A HREF="ess_16.html">last</A> section, <A HREF="ess_toc.html">table of contents</A>.

960

</BODY>

961

</HTML>

Older »