NAME

SYNTAX

	ps help				# version 3.9 and later
	ps caption name message...	# version 3.9 and later
	ps create name
	ps convert name
	ps delete name
	ps exists name			# version 4.6 and later
	ps list  [name]
	ps rename oldname newname	# version 3.9 and later
	ps name = name [& | ^ + - * m < > ( )] name
	ps name = name with (constraint) # version 4.8 and later
	ps name = name with "string"	# version 4.8 and later

DESCRIPTION

	: ps help

The command

	ps caption name message

A named pattern set can be created with the pe command, or it can be created by converting an existing set of token markings into a structured and named pattern set with the create option, as follows:

	: ps create Setname

The reverse operation, converting a set of structured matches into basic markings while leaving the set unmodified is performed by the convert option.

	: ps convert name

The list option lists the available sets (or a specific one) together with the number of patterns that each set contains.

The delete option omits the named set.

	: ps delete name

	: ps exists name

The list command displays non-empty sets.

	: ps list [name]

	: ps rename oldname newname

The ps command can also be used to create new derived sets by applying standard set operations to other named sets. The three most important commands in this set can be used to define set union, difference, or intersection. But, there are six additional set operations, inspired by the operators from Allen Interval Logic (Cobra version 4.1 and later). When defining set operations, the first name given is followed (after a space) by an assignment operator (=) and two existing setnames separated by one of the valid operators.

	: ps C = A & B

	: ps C = A + B		# or A | B

	: ps C = A - B		# or A ^ B

The additional set operations inspired by Allen interval logic are as follows. Note that a match from a pattern expression defines an interval in the code, with a start, an end, and possibly some tokens in between. So we can ask for matches to be contained in one another or to overlap, etc. The operations are:

	: ps C = A * B		# or A d B (for A during B)

	: ps C = A m B		# A meets B

	: ps C = A < B		# A precedes B

	: ps C = A > B		# B follows A

	: ps C = A ( B		# A starts before and ends during B

	: ps C = A ) B		# A starts during and ends after B

Finally, we can also use the ps command to create a subset of matches stored in a new named set, containing only matches from a given set that contain a specific text-string, or matching a specific expression on the token attributes of the first lexical token in a match.

	: ps C = A with "for"	# match contains at least one for statement
	: ps D = A with "k"	# match contains at least one use of variable k
	: ps E = A with (.fnm == "foo.c" && .lnr < 100)

EXAMPLES

  $ cobra *.c	# cobra sources
  : pe A: for ( x:@ident .* ) { .* :x = .* }
  9 patterns stored in set 'A'
  : dp A 1	# display first pattern matched
  ...
  : pe B: for ( .* ) { .* emalloc .* }
  7 patterns stored in set 'B'
  : dp B 1	# display first pattern matched
  ...
   : ps C = A & B  	# set intersection
   : ps D = A + B  	# set union
   : ps E = A - B  	# set difference
   : ps F = B - A
   : ps convert F	# convert the patterns in set C to markings
   : pe X: for ( .* )
   : ps Y = X m X	# nested for-loops
   : pe N: @int
   : ps M = X * N	# for loop controls containing declarations of integers
   : ps O = X with "if"	# matches containing at least one if statement

SEE ALSO