Sam is an interactive multi-file text editor. In addition to a mouse-driven cut-and-paste interface, a textual command language makes complex or repetitive editing tasks easy to specify. The command language is characterized by the composition of regular expressions to describe the structure of the text being modified.

A normal sam session begins with a new sam terminal window. You are expected to use the console at the top and mouse chording to manipulate files and edit text. sam behaves pretty much like ed if you invoke it with sam -d.

This post assumes you have read The Sam Paper and are running on 9front.

To switch from a text window to the end of the command window use ctrl+b. Ctrl+g switches to the last focused window. This is useful to return to a text window after having switched to the command window.

Manipulating Files

To open all source, header, and GN build files located in src and inc folders run the following command in a rio rc window:

% cd $home/NEIN999/
% sam `{walk -f src inc | grep '\.(c|cpp|cc|h|gn)'}

The above missed to add make files to the list of files sam knows about:

B < walk -f src | grep '(Makefile|mkfile)'

Note: the previous command is executed in the ‘samterm’ window.

To see what files are known to sam you can either right click or type n into a samterm window to get a list of files (sam is a multi-file editor so it keeps track of all files it was told to open).

Large scale software projects contain hundreds of files organised in more or less complex file hierarchies. There might be so many files that selecting a file using the mouse is cumbersome. It might be quicker to search for files using sams command language.

To see all .cpp files known to sam that are in a util folder one can use the following:

X/- .*\/util\/.*\.cpp/

That will print:

 -. src/util/Allocate.cpp
 -. src/util/Arguments.cpp
 -. src/util/Atomic.cpp
 ...

To open one of the files prepend the file name with b, select b src/util/Allocate.cpp, middle-click and chose send.

It is easy to get into a frenzy and modifiy a multitude of files. To check what files have been modified the following command is useful:

X/'/

In this particular example it prints:

'+. src/util/Allocate.cpp

Especially after bulk search and replace actions many files might be modified. To save all modified files to disk run the following:

X/'/ w

Commands that output file names usually prepend the name with a few characters. The first three characters are a concise notation for the state of the file:

Search and Replace

Search

Let’s check what files have a copyright notice and print some context to check the year, company name, and the presence of a specific tag before for all source files in the util folder:

X/.*(inc|src)\/util\/.*\.(cc|cpp|h)/ ,g/Copyright \(C\)/ {
	,x/.*\n/ g/Copyright \(C\)/ {
		f
		=
		-1,+1 p
	}
}

This command executed in the samterm window produces the following output:

 -. inc/util/Adaptor.h
3; #16,#83
 <copyright>
 Copyright (C) 2013 PlanNein, Inc. This software and the associate
 documentation are confidential and proprietary to PlanNein, Inc.
 -. inc/util/Allocate.h
9; #301,#368
 <copyright>
 Copyright (C) 2013 PlanNein, Inc. This software and the associate
 documentation are confidential and proprietary to PlanNein, Inc.
...

Need more context before or after the match, similar to UNIX style grep -C2 ... or grep -B2 -A3 ...?

X/.*(inc|src)\/util\/.*\.(cc|cpp|h)/ ,g/Copyright \(C\)/ {
	,x/.*\n/ g/Copyright \(C\)/ {
		f
		=
		-2,+3 p
	}
}

Note how the output now shows two lines before the match and three lines after the matches (i.e. like grep -B2 -A3 ...:

 -. inc/util/Adaptor.h
3; #16,#83
/*
 <copyright>
 Copyright (C) 2013 PlanNein, Inc. This software and the associate
 documentation are confidential and proprietary to PlanNein, Inc.
 Your use or disclosure of this software is subject to the terms and
 conditions of a written license agreement between you, or your company,
 -. inc/util/Allocate.h
9; #301,#368
/*
 <copyright>
 Copyright (C) 2013 PlanNein, Inc. This software and the associate
 documentation are confidential and proprietary to PlanNein, Inc.
 Your use or disclosure of this software is subject to the terms and
 conditions of a written license agreement between you, or your company,
 ...

Replace

Replacing stuff in a single file is easy. Doing it across multiple files is much more interesting. Let’s say we want to replace all occurrences of Copyright (C) in source files with COPYRIGHT ©:

X/\.(cc|cpp|h)/ ,g/Copyright \(C\)/ {
	,x/.*\n/ g/Copyright \(C\)/ {
		s/Copyright \(C\)/COPYRIGHT ©/
	}
}

Let’s break this down:

1. X/\.(cc|cpp|h)/… selects all source files ending in .(cc|cpp|h) that sam knows about
2. ,g/Copyright \(C\)/… out of that set only considers files matching the pattern Copyright \(C\)
3. ,x/.*\n/… for each line of such a file
4. g/Copyright \(C\)/… that contains the pattern Copyright \(C\)
5. { s/Copyright \(C\)/COPYRIGHT ©/ }… substitute the replacement text for the first match, in dot, of the regular expression.

You can do much more advanced things than simple search replace once you get the hang how to use the command language.

Cheatsheet

Addresses

Regular Expressions

Text Commands

Display Commands

I/O Commands

Loops and Conditionals

Miscellaneous

Idioms