%++++++++
% Copyright:    (C) 2008-2015 UDS/CNRS
% License:       GNU General Public License
%.IDENTIFICATION acut.tex
%.PURPOSE        Man page of acut, can be edited in LaTeX
%.AUTHOR         Francois Ochsenbein
%.VERSION   1.0  21-Jul-1992
%.VERSION   1.1  07-Oct-1992: Added Formats
%.VERSION   1.2  11-Dec-1992: 5 columns in format file
%.VERSION   1.3  27-Mar-1993: -T Options
%.VERSION   1.4  13-Oct-1993: Decimals
%.VERSION   1.6  15-Jan-1994: Decimals with possible prefix / suffix
%.VERSION   1.7  03-Feb-1995: B
%.VERSION   2.2  10-Apr-1997: New Counts
%.VERSION   2.3  22-Feb-1998: -a option
%.VERSION   2.4  20-Jul-1999: Truncation Facilities
%.VERSION   2.5  03-Feb-2000: regexp
%.VERSION   2.6  10-Feb-2000: -c
%.VERSION   2.6  18-Jul-2001
%.VERSION   3.3  30-Dec-2004
%.VERSION   3.5  24-Aug-2005
%.VERSION   4.3  27-Jun-2014
%----------

\def\pgm{{\bf acut}\ }
\begin{manpage} {1}{acut}{Gets parts of a file}
	{Jun-2014}{Extract Columns}
\def\pfile{{\em file}}\def\cols{{\em cols}}
\syntax{ \pgm 
	[{\bf --C}{\em comment}] 
	[{\bf --d}{\em c}] 
	[{\bf --el}] 
	[{\bf --T} {\em s1} {\em s2}] 
	[{\bf--a}\cols$|${\bf--c}\cols$|${\bf--f}\cols]... 
	[{\bf--i}{\em text}]...
	[{\em file...}] }

\mansec{ Description }
The \pgm command allows to extract and reformat columns of a file, 
and to insert fixed text. Unlike {\bf cut}(1), the order of the columns
is arbitrary, and several cut/insert arguments can be specified.
The columns can be raw characters ({\bf--c}) or intervals delimited
by a {\em delimiter} character ({\bf--f}). 

\pgm also allows to {\em translate} (replace characters) in
specified columns ({\bf T}), and to remove leading and/or trailing
blanks in specified columns ({\bf h}, {\bf j} and {\bf t}),
or to perform regular expression substitution in the specified columns.

\pgm is especially useful for reformatting decimal or sexagesimal numbers which
can be properly aligned (see below). Accepted sexagesimal representations
include blank- or column-separated numbers (like {\tt 12:04:56}
or {\tt 12~04~56}), as well as number without separator (like {\tt 120445})

\mansec{Options}

\option{--version}
	prints the version and exits.

\option{--C{\em comment}}
	defines {\em comment} lines -- lines starting by 
	{\em comment} are just copied to the output without reformatting.
	For instance, {\bf --C'\#'} will consider lines starting
	by a {\em has} sign as comments. By default, {\em blank lines}
	are considered by comments.

\option{--d{\em c}}
	defines the character used as a {\em delimiter} between
	columns; this delimiter is only used in cunjunction
	with the {\bf -f} option. Its default is the {\em tab}.
	
\option{--el}
	asks to process the empty lines. By default the empty lines
	are directly issued, assuming these have just a role of delimiter.
	{\em(added in V3.92)}

\option{--T {\em s1} {\em s2}}
   defines the {\em translation table}:  characters from {\em s1} are converted
   into the corresponding characters of {\em s2} (byte-by-byte
   translation). Strings {\em s1} and {\em s2} must have the same length.
   The complete alphabet may be specified by {\bf\b a} (lowercase)
   or {\bf\b A} (uppercase); {\bf\b s} stands for the 6 spaces
   (blank, tab, vtab, newline, carriage-return, form-feed)
   %The dash (-) may be used to specify intervals, e.g.
   %{\tt a-z} for the 26 lowercase letters. 
   Non-printable characters can be specified using the C conventions
   (e.g. {\tt\b n} for the newline, or {\tt\b e} for the Escape,
   or the octal representation).

   As a shortcut, \pgm accepts the options {\bf--Tlow} and {\bf--Tup}
   for conversion to lowercase / uppercase.

\option{--a\cols}
	asks to insert a {\em delimiter} (the character defined by
	the {\bf--d{\em c}} option) between character columns;
	for example, {\tt\pgm -a1-15,16-} inserts a tab between 
	bytes 15 and 16.  \\
	Note that {\em only one }{\bf--a} option can be specified.

\option{--c\cols}
	defines a set of {\em character columns}. {\cols}  expressions
	can make use of commas and dashes, e.g. {\tt -c1,80,2-5}
	asks to pick successively the columns 1, then 80, then the
	range 2 to 5. {\cols} may be empty, meaning 
	{\em all consecutive columns between the previous
	{\bf--c} and next {\bf--c} definitions}.
	For details on how \cols\ can be written, refer
	to the \cols\ section.

\option{--f\cols}
	is similar to the {\bf--c} option, but columns are defined
	as the set of bytes between two {\em delimiter} characters.
	
\option{--i{\em text}}
	to insert the fixed text following the {\bf--i}
	into each line of the output. The {\bf--i} alone 
	asks to insert the {\em delimiter} (specified by the {\bf--d} option,
	{\em tab} by default)

\mansec{{cols} expressions}
	{{\cols} expressions} allow to define a set
	of positions (starting from 1)
	representing either byte positions ({\bf--c}) or column numbers
	({\bf--f}). Numbers may be separated by commas, e.g.
	{\tt -c1,5} for byte numbers 1 and 5, or by a {\em dash},
	like {\tt -c5-10} for bytes 5 through 10 (i.e. 6 consecutive
	bytes), or by a {\em plus} like {\tt -c5+6} for 6 bytes starting
	at byte \#5 (i.e. bytes 5 through 10). 
	
	There is however a difference between {\tt -f5-10} and {\tt -f5+6}:
	the former ({\tt-f5-10} consists of the 5 columns separated 
	by {\em 4 delimiters} (the character defined by the {\bf--d} option),
	while the latter {\tt-f5+6} {\em has no delimiter} between the
	5 columns (the 5 columns are {\em concatenated}). 
	An alternative way of concatenating the character-separated
	columns is to start the list of fields with a {\bf--} (minus), 
	e.g. {\tt-f5+6} and {\tt-f-2-10} are equivalent.

	A missing number after the {\em dash}
	means {\em up to end of line}, and a missing number before
	the dash means {\em from byte following the last defined column}.
	A {\em repetition factor} can be added, e.g. {\tt -c5+6*4}
	to specify the 4 fields laying over bytes $5-10$, $11-16$,
	$17-22$ and $23-28$.
	
	{\cols} may also be 
	\begin{itemize}
	\item	{\bf--c} meaning {\em all consecutive columns
	between the previous and the next {\cols} definition}
	\item	{\bf--c..} meaning 
	{\em all remaining columns},
	i.e. columns not mentioned in previous arguments.
	\end{itemize}
	
	{\cols} expressions may end with the following
	reformatting options:
	\begin{itemize}
	\item[{\bf \%}] (format {\bf \%[{\tt+}][{\tt0}]$n$[:|.]$d$[{\em opt}]} 
		asks to align the numeric value, possibly expressed in 
		sexagesimal, along a decimal point (.),
		assuming up to $d$ decimals or trailing spaces
		reserved for comments like uncertainty flags;
		a sign can be inserted ({\bf+}), and the number may be
		zero-filled ({\bf0}).
		See below the section on {\em Numbers} for details
  	\item[{\bf s}]{\em regular\_expression\_substitution} \quad
		asks to perform a substitution in the specified set of
		bytes in a way similar to {\bf sed(1)}
		See below the section on {\em pattern substitution} 
		for details.
  	\item[{\bf a}]{\em value} \quad
		asks to add to the column an (integer) {\em value} specified.
  	\item[{\bf+}] = (format {\bf+$n$[a$|$A$|$d$|$x$|$o]}) \quad
  		asks to edit a counter of width $n$
  		when the field defined is identical to same field
  		in the preceding line (see {\em Counter} section below)
	\item[{\bf b}] asks to {\em blank} the {\cols} if their contents
		is identical to the previous line.
		This option is only available for {\bf--c} column
		specifications.
	\item[{\bf B}] asks to replace blank columns by the
		contents of the previous record.
		This option is only available for {\bf--c} column
		specifications.
	\item[{\bf h}] asks to remove the {\em head} blanks;
		it is identical to {\bf\%--} (left-aligned format)
	\item[{\bf j}] asks to {\em justify} blanks; it has the same
			effect as {\bf ht}
	\item[{\bf l}] asks to adjust to the left, and is identical to {\bf h}
	\item[{\bf n}] indicates a {\em numeric} field (see below
		the section on {\em  Numbers})
	\item[{\bf r}] asks to adjust to the right, and is identical to {\bf t}
	\item[{\bf q}] asks to {\em unquote} the column 
		(remove leading/ending quote {\bf"}, replace adjacents
		quotes by a single one --- following the SQL conventions)
	\item[{\bf t}] asks to remove the {\em tail} blanks;
	\item[{\bf T}] asks to {\em translate} the {\cols} according
	to the translation table specified by the {\bf--T} option.
	The {\bf--T} option must of course precede the {\cols} definitions.
	\end{itemize}

	For instance, translating the first column in uppercase
	and removing leading \& trailing blanks in the other columns
	can be written as

	\noindent {\tt -T a-z A-Z -f1T -f2-j}

\mansec{Numbers (\%)}
With the 
{\bf \%[{\tt+}][{\tt0}]$n$[:|.]$d$[{\em opt}]}
option, the field is assumed to contain
a decimal number with up to {\em d} decimals. This option performs
also realignments of possible {\em prefix} (typically a limit flag) and of 
possible {\em suffix} (typically an uncertainty flag like a colon).

In this option, the following transformations are performed:
\begin{itemize}
\item	the sign can be systematically inserted at the
	very left whith the {\bf \%+} option.
\item	the decimal point is aligned in column $(n-d)$ with
	the {\bf \%$n.d$} option, or the rightmost digit is
	aligned in column $(n-d)$ with the {\bf \%$n:d$} option;
	for sexagesimal representations, the decimal point
	must pertain to the {\em seconds} part.
\item	the blanks between the sign and the digits are removed,
	or are {\em filled with zeroes} when the $n$ number starts
	by {\bf 0}
\item	the prefix, if any, is left flushed, 
\item	the suffix, if any, is right flushed. 
\item	1-letter {\em options} mean the following:
	\begin{itemize}
	\item	{\bf s}: the number is in {\em sexagesimal} representation,
		either time or angle ({\bf h m s}, or {\bf $\d$ ' ''}).
	\item	{\bf S}: the number is in {\em sexagesimal} representation,
		and the decimal fractions of the degree/hour or minutes 
		have to be changed to match a full sexagesimal representation,
		i.e. {\tt 23 12.5} will be changed into {\tt 23 12 30}
	\item	{\bf r}: the number will be {\bf rounded} to the specified
		number of decimals if more than $d$ decimals are supplied 
		in the input.
	\item	{\bf r!}: in addition to {\bf r}, apply limits to the
		value, as {\em 9-filled} values ({\bf -9...} for the
		minimum, {\bf 99...} for the maximum)
	\item	{\bf q}: add a lower-case {\em quality} to the number:
		{\tt a} when the number has effectively $d$ decimals,
		{\tt b} when $d-1$ decimals are supplied, etc.
		For sexagesimal representations, one sexagesimal part
		is equivalent to 2 digits.
	\item	{\bf Q}: upper-case {\em quality} (see {\bf q})
	\item	{\bf $<${\em num}}: limit the number to some predefined
		boundary, i.e. for a value of the field larger than
		{\em num}, replace its contents by {\em num}
		(see also the {\bf r!} option)
	\end{itemize}
	The options may be combined, e.g. 
	{\bf \%12.2sr} to round a sexagesimal value.
\end{itemize}
With a ``format'' {\tt \%10.3}, the following lines 
show the transformations on a few numbers,
(the first column contain initial data, the second the transformed numbers)
\begin{verbatim}
0123456789  0123456789
 -  12         -12.       
12.2:           12.2 :
 <10?       <   10.  ?
\end{verbatim}
When the alignment is not possible or a truncation occured,
a warning message is issued.

\mansec{Pattern Substitution (s)}
In a way similar to {\bf sed(1)}, the column defined can be
substituted. For instance, removing all blanks in the column between
bytes 1 and 12 can be written:

\begin{verbatim}
acut -c1-12s'/ //g' -c13-
\end{verbatim}
 
or squeezing the blanks (leaving just one when there are several)

\begin{verbatim}
acut -c1-12s'/  */ /g' -c13-
\end{verbatim}

The substitution can use the {\tt\b 1} \dots\ patterns matched as in
sed: for instance interverting the texts separated by a comma
between columns 1 and 12 can be written

\begin{verbatim}
acut -c1-12s'^/\([^,]*\),\(.*\)/\2,\1/'
\end{verbatim}

\mansec{Counters}
It is possible to ask to write a {\em counter} which is increased
each time two consecutive lines have an identical column,
and reset to $1$ when the column differs from the previous line.
This option may also follow the {\bf B} {\cols} expression, as in the example \\
{\tt -c1-11B+a} \\
which asks to replace a blank field in bytes 1-11 by 
a repetition of the contents
from previous line, followed by {\tt a} for the first (non-blank) line,
{\tt b} for the next (blank) line, etc. However, the counter is inserted
only when at least two consecutive lines have an identical column.

The complete option is {\bf+$n$[a$|$A$|$d$|$x$|$o]} where:
\begin{itemize}
\item  the number $n$ is the width of the extra column with the edited counter;
	the default value is $1$
\item  the letter specifies how to edit the counter:
	\begin{itemize}
	\item[{\bf a}] for lowercase alphabetic
	\item[{\bf A}] for uppercase alphabetic
	\item[{\bf d}] for decimal 
	\item[{\bf o}] for octal 
	\item[{\bf x}] for hexadecimal lowercase
	\item[{\bf X}] for hexadecimal uppercase
	\end{itemize}
\end{itemize}

\mansec{Restrictions}
The {\bf--c} and {\bf--f} options are mutually exclusive.

\mansec{Returned Status}
The \pgm command returns 0 in case of success, and
non-zero when bad options or unreadable files are found.

\mansec{Examples}
\begin{enumerate}
\item	To generate a tab-separated-table from an ascii file,
	column 1 from bytes 1 to 10, column 2 from bytes 11 to 20,
	and the rest as column 3, leading/trailing blanks removed 
	in each column: \\
{\tt 
acut -a1-10,11-20,21-j
}

\item	To rewrite the degree part of the declination in bytes 10-12: \\
{\tt 
acut -c1-9 -c10-12\%+03 -c13-
}


\item	To generate a file containing on each line: the column 1,
then column 80, then the columns 11 through 20 which are assumed to 
contain a (possibly badly aligned) number with up to 3 decimals,
and each field preceded with an obvious explanation, then all other columns: \\
{\tt 
acut -i"Col.1=" -c1 -i" Col.80=" -c80 -i" Cols11-20: " -c11-20\%10.3 -i/ -c..
}

\item	To remove all blanks in the columns 10 to 20, leaving other
	columns intact:
{\tt
acut -c -c10-20s'/ //g' -c
}
\end{enumerate}

\seealso{cut(1) \quad sed(1) }
\end{manpage}
