filename

>filename

Simply write to file.

>>filename

Append to (not necessarily) existing file.

+<filename

Also open the file for input, allowing inplace editing. With this option variant no input filenames need to be given. But if you want to perform the builtin on more files, you must use "-" as an input filename for this one. In fact the output gets written to a temporary file which gets moved to filename at the end.

|shellcommand

Pipe the builtin's output to the Shell command(s).

This option is necessary because there is no redirection syntax.

-l

--link

Try to link the files. If that fails, try symbolic link, if that is also requested, else copy.

-s

--symbolic

--symbolic-link

--symlink

Try to symbolically link the files. If that fails, copy.

See the note under &ln.

-c list

--characters=list

Print all the characters specified by list. List may be any Perl expression returning a list of integers. The integers can be either positive, starting at zero to count from the beginning, or negative to count from the end. Unlike Unix "cut", the order you request is respected.

Unlike in Perl's slice operator where a ".." range must be either positive or negative, &cut allows starting with a positive and ending with a negative. But this is only available if your expression consists only of numbers, commas and "..". E.g. "1..-2" means everything but the first (0) and the last (-1).

The list expression can look at the whole line in $_. Changes to that will be ignored, however, because when this expression is evaluated the line has already been split to Perl's autosplit variable @::F. The numbers you return are in fact indices to that list.

-d string

--delimiter=string

Set a new delimiter for input fields and output. Unlike Unix "cut", this may have any length.

-E

--noescape

Treat "\" as normal literals for "-p, --printf=format".

-f list

--fields=list

Print all the groups specified by list. List is as described under "-c, --characters=list". Note that this hides the standard option "-f" which must be given as "--force".

-l list

--lines=list

Print all the lines specified by list. List is as described under "-c, --characters=list" with one major difference: The first line has number 1, there is no line 0. This is definitely inefficient for big files, if you have a mixed positive to negative range in your list, as it reads everything to memory. Otherwise Perl could optimize this, but I don't know if it does.

-m

--matching

Print only matching lines, i.e. ones which have enough characters or fields. This implies "--only-delimited", which is why you will miss single-field lines with "--fields=0".

-p format

--printf=format

Apply format (with \escapes) to all fields or characters.

-s

--only-delimited

Print only lines containing delimiters.

    &cut -c 10-20,-5,25- $(input)
    &cut -c 'grep $$_ % 3, 0..99' $(input) # 1st 100 columns not multiple of 3
    &cut -d: --fields 0,4 --printf='%10s is %s\n' /etc/passwd

\cA

Is a control character ^A.

\u

Upcases the following letter.

\U

Upcases the rest, or up to the next "\E" or "\L" if found.

\xHH, \x{HHHH}

Is the character value of the given Hex code. Note that numeric codes are not portable to EBCDIC platforms!

Unlike Unix "yes", &yes is exactly like &echo, except that it repeats the output for as long as it can, typically until an "--output '| command'" terminates. And, if &yes has no arguments, it defaults to "y".

"Standard options": "-A, --args-file, --arguments-file=filename, -f, --force, -o, --output=filename, -O, --outfail, -v, --verbose"

-E

--noescape

Treat "\" as normal literals.

-n

--nonewline

Do not add a newline after the last string. (Not understood by &printf.)

-n

--nonewline

Do not add a newline after the output.

    &expr ($(VAR) - 3) * 2 < 1 && -1 || 1
    &expr "$(VAR) - 3 * 2 < 1 ? 'joy' : 'sorrow'" -o $(output)
    -&expr $(VAR) - 3 * 2 -o >>$(output)

-c

--count

Suppress normal output; instead print a count of matching lines. With the "-v, --invert-match" option (see below), count non-matching lines.

-l

--list

--files-with-matches

Output only the name of those files with matches. When this is combined with "-v, --invert-match", output the name of files with lines that don't match (a bit absurdly but compatible with Unix -vl). When this is combined with a doubled "-vv", output the name of files with no matches.

-v

--vice-versa

--revert-match

--invert-match

Invert the sense of matching, to select non-matching lines. Note that this hides the standard option "-v" which must be given as "--verbose".

-w filename

--waste-file=filename

An optional waste basket for collecting the rejected lines. This is not only for debugging your selection code, but also for splitting your input in two. As with the normal output, you may modify $_ before returning false.

    &sed s/foo/bar/ f1 f2 f3 -o outfile # like sed s/foo/bar/ f1 f2 f3 >outfile
    &sed '$$_ = uc' f1 f2 f3 -o outfile # like tr '[:lower:]' '[:upper:]' f1 f2 f3
    &grep '$$. % 3' f1 f2 f3 -o outfile # eliminate every 3rd line
    &grep -c /match/i f1 f2 f3          # count the lines matching 'match' to STDOUT

Without pushing you to mass generate accessors, here's how you could do it by simply putting a comment of RO or RW between each type and desired variable name, all on one line. The generated getter and optionally setter methods go into the next found public or protected section:

    # Create get and maybe set method from "type /* R[OW] */ member;".
    sub cxx_accessors {
      $acc ||= '';              # Candidate for 5.10.0 state
      if( m!^\s*(.+?)\s*/\*\s*R([OW])\s*\*/\s*(.+?)\s*;! ) {
        $acc .= "#line $.\n";   # Tell C++ where this came from
        $acc .= "void set\u$3( const $1 &__tmp ) { $3 = __tmp; }"
          if $2 eq 'W';
        $acc .= "const $1 &get\u$3() const { return $3; }\n";
      } elsif( /^\s*(?:public|protected)\s*:/ ) {
        $_ .= $acc;
        $acc = '';
      }
    }
 
    %.cc: %.cc.in               # Use &sed for I/O handling
        &sed --sync-lines &cxx_accessors $(input) -o $(output)

-c

--copy

Copy the files rather than moving them. This is preferable, as it doesn't force makepp to rebuild the file next time. But it is not the default, for compatibility with other install programs.

-d

--directory

In the third form form of this command create all the given directories and any necessary parent directories.

-g group

--group=group

Change the group ownership of the destination files. The group may be given by name or numerically.

-l

--link

Try to link the files. If that fails, copy.

--log=filename

--logfile=filename

Use filename instead of normal logfile.

-m mode

--mode=mode

Sets mode for all destination files or directories. Mode must be an octal string.

-o owner

--owner=owner

Change the ownership of the destination files. The owner may be given by name or numerically.

-r

--resolve

--resolve-symbolic

--resolve-symbolic-link

--resolve-symlink

-S

--symbolic

--symbolic-link

--symlink

Creates symbolic links instead of moving. These options are passed to &ln and are described there.

-s

--strip

Calls the "strip" utility, which must be in the $PATH, on the destination files.

-r

--resolve

--resolve-symbolic

--resolve-symbolic-link

--resolve-symlink

This is what you always wanted "ln -s" to do. Create symbolic rather than hard links, not to the strings specified, but really to the given files.

-s

--symbolic

--symbolic-link

--symlink

Create symbolic rather than hard links.

Note: On various file or operating systems, this operation is not supported. Or it is, e.g. by Cygwin, but not understood by native Windows compilers, if you use one. For a makefile you can't change, to get at least some sort of result, &ln and "&cp -l -s" can copy the files for you instead (not directories though). To achieve this, you need to export the following variable before calling makepp:

export MAKEPP_LN_CP=1

&ln --resolve or --symbolic will copy the files instead of creating a symbolic link.

export MAKEPP_LN_CP=2

&ln will copy the files instead of creating a hard link.

export MAKEPP_LN_CP=3

All invocations of &ln will copy the files instead of creating either kind of link.

-m mode

--mode=mode

Sets mode for all created directories, irrespective of the umask. Mode must be an octal string.

-p

--parent

Also create any necessary parent directories. Ignore directory creation failure due to the directory already existing (even if it was created concurrently by another process).

-a

--assignment

Also treat assignments within the files as makepp would. Alas such lines can't be masked with an empty "$()", because it is legal to construct variable names with expressions. This additionally recognizes the statements "define", "export"/"unexport" and "override" (these can be masked with "$()").

-h \\%hash

--hashref=\\%hash

This allows preallocation of the variable values, including long ones not easily passed in a command. The passed expression may be any Perl code that returns a hash reference. This is merged with any other variables passed to the command, including from another "--hashref" option.

-f

--force

This prevents complaining about inexistent files. That is a side effect this option has in Unix, and the only one that makes sense here.

-m

--metainfo

In addition to the given files, this also deletes the meta information makepp stores about them in the .makepp directory. Thus makepp forgets all it ever knew about the given files. If the .makepp directory becomes empty after this, it too is deleted.

This will also delete given directories, but only if they are empty. To facilitate this, it will delete directories last, in the order of descending depth. So you can use "**" expressions to delete whole hierarchies. Here's an example to be found in many top level make files. Note that there is a "makeppclean" utility that can do this more efficiently.

    $(phony cleanold):
        &rm -fm $(only-stale **/*)
 
    $(phony clean): cleanold
        &rm -f $(wildcard **/*.[ao])
 
    $(phony distclean): clean
        &rm -fm $(only-targets **/*)

-c perlcode

--compare=perlcode

perlcode represents a Perl sort block, with the two sorting candidates in $a and $b.

-n

--numeric

--numeric-sort

This sorts sorts numerically on the beginnings of records. Leading whitespace is skipped. You can use "--transform" and "--detransform" if the numbers are not at the beginning.

-r

--reverse

Output the results in the reverse order. Note that this hides the standard option "-r" which must be given as "--record-size".

-t perlcode

--transform=perlcode

-d perlcode

--detransform=perlcode

If you have a complex code, sorting gets more and more expensive in proportion to the number of records n, because the code gets called O(n log(n)) times. To avoid that, you can allow Perl to concentrate on sorting, by first modifying the strings, such that complicated search criteria extraction happens once per record, and modifying them back, once they are sorted.

If these options are given, the "--transform" perlcode gets mapped to the records in $_ one after another, and can modify them. After sorting, the "--detransform" perlcode gets mapped to the modified records in $_ one after another, and can modify them back. You will usually use neither or both of these options, unless you want to output modified lines.

Turning the strings into a structure of extracted sort criteria, which your "--compare" perlcode can pick up is known as the Schwartzian Transform (ST). Packing everything into the string itself, so that no "--compare" perlcode is needed, allowing the whole sorting to happen without performing expensive Perl code, is known as the Guttmann-Rosler Transform (GRT). You can find tips by searching for those names on the web.

    # Expensively sort numerical expressions by value ($$ protects $ from makepp expansion)
    &sort --compare 'eval( $$a ) <=> eval( $$b )' $(input) -o >>$(output)
 
    # ST for case insensitive sorting
    &sort -t '[lc, $$_]' -c '$$a->[0] cmp $$b->[0]' -d '$$_->[1]' $(input) -o >>$(output)
 
    # GRT using modification functions defined elsewhere in the Makeppfile
    &sort -t &transform -d &detransform $(input) -o >>$(output)
    

-u

--uniq

--unique

After sorting, eliminate duplicates. These are either identical lines, or if the "--compare" option is given, ones which that perlcode reports as equivalent.

@# comment @

Note that despite borrowing from script "#" line end comment syntax, this one is an inline comment.

@MACRO@

This construct is replaced by the value of the MACRO. Macro names must start with a letter or underscore, followed by any number of letters, underscores, minuses or dots. Unlike in makepp names, underscore and minus are not equivalent.

@MACRO(arg1,arg2...)@

Like the first one, but parametrized. The args replace $1 through $9 or "${number}" in the value. Or, if the value is a Perl function, they are passed as normal parameters. The result then replaces the whole construct. One level of macro nesting is possible in that the args in parenthesis may contain plain "@MACRO@" invocations, as in "@f(@x@)@", where "@x@" gets expanded before being replaced into the body of "f".

@include(filename)@

This is the only predefined macro. It is replaced by the &template-processed content of the named file. Like all macros this can occur in the middle of a line. Alas, because of that, "-S, --synclines" ignores the file inclusion, making everything seem to come from the including file.

@MACRO=definition@

@MACRO?=definition@

This defines a macro within the file. This is replaced by nothing. The second form only takes effect if the macro was not defined, presumably on the command line.

@MACRO { Perlcode }@

This also defines a macro, the body of which is a Perl sub. The arguments, if there are any, get passed in as @_.

@{ Perlcode }@

This runs the Perlcode immediately and gets replaced by the return value.

So far we have only seen one syntax for embedding special things. There is another multiline syntax, and both allow a variation to suppress a newline. These are the builtin syntaxes (which can be configured by options below). Here SPECIAL stands for any of the constructs shown above:

@SPECIAL@

@SPECIAL@\

This can appear multiply anywhere on a line. The variant immediately followed by "\" only works at the end of the line. It also replaces the following line break.

@@SPECIAL@@ Normal text @@

@@SPECIAL@@ Normal text @@\

This is like the previous one. However the normal text, which also gets replaced, can span multiple lines. You can put the special parts on comment lines around source code that is only needed in an uninstalled script, to be eliminated or replaced during the installation process:

    # @@# the next 2 lines will disappear @@
    echo You are running the uninstalled version of this script
    # @@
    # @@REPLAMCENT@@
    echo Something else will be here
    # @@
    

A meaningless example showing the various possibilities:

    @m1=some definition@\
    @m2=foo $1 bar@\
    @middle_of_arg=iddl@\
    @m1@ @m2(m@middle_of_arg@e)@
    @@m2(many lines)@@
    ...
    @@ plain text 1 + 2 = @{ 1 + 2 }@

becomes

    some definition foo middle bar
    foo many lines bar plain text 1 + 2 = 3

"Standard options": "-A, --args-file, --arguments-file=filename, -f, --force, -i, --inpipe=shellcommand, -I, --infail, -o, --output=filename, -O, --outfail, -r, --record-size=number, --separator=string, -S, --synclines, -v, --verbose"

-d

--defined

Replace only instances of macros which are actually defined. Without this option the undefined ones will all be replaced by nothing.

-h \\%hash

--hashref=\\%hash

This allows preallocation of the macro values, including long ones not easily passed in a command. The passed expression may be any Perl code that returns a hash reference. This is merged with any other macros passed to the command, including from another "--hashref" option. A hash value may also be a code reference, in that case the function gets called, as with "@macro { Perlcode }@" definitions.

-s /prefix/suffix/

--simple=/prefix/suffix/

Use prefix and suffix before and after SPECIAL respectively instead of "@". The first character is the separator and need not be a slash. These values are Perl regexps. You must not introduce grouping like "(...)", but "(?:...)" is ok.

-m /prefix/suffix/afterprefix/[aftersuffix/]

--multiline=/prefix/suffix/afterprefix/[aftersuffix/]

Use prefix, suffix and afterprefix before and after SPECIAL and at the end of the block respectively instead of "@@". If aftersuffix is also given, the macro name must get repeated before it. The first character is the separator and need not be a slash. E.g. an XML-ish, to which you must add "--defined" if you want to preserve other tags, not defined by you:

    --defined --simple=|<|/>| --multiline=|<|>|</|>|
    

Or, better, use processing instructions "<?...?>", intended for such a purpose:

    --defined --simple='|<\?|\?>|'
    

Or, if you want to combine this with "&entity;" syntax for the simple macro replacements (preserving numeric entities "&#x263A;" which are not comments):

    --defined --simple='_(?:&(?!#)|<\?)_(?:;|\?>)_'
    

-c perlcode

--compare=perlcode

This Perlcode gets the previous and current lines in $a and $b and shall return true if it considers the two lines equal.

    &uniq --compare='lc( $$a ) eq lc $$b' $(inputs) -o $(output)