README.md

   1 # line
   2 The **line** utility reads from standard input, printing ranges of lines and columns to standard output.
   3
   4 ## Features
   5 * Quality
   6     * Compiled with security hardening flags.
   7     * Static analysis integrated using clang's `scan-build` using checkers `alpha.security`, `alpha.core.CastSize`,
   8     `alpha.core.CastToStruct`, `alpha.core.IdenticalExpr`, `alpha.core.PointerArithm`, `alpha.core.PointerSub`,
   9     `alpha.core.SizeofPtr`, `alpha.core.TestAfterDivZero`, `alpha.unix`.
  10     * Test harness
  11     * Follows [FreeBSD coding style](https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9).
  12 * Portable
  13     * C99 compliant *and* may be built in an environment which provides POSIX.1-2001 system interfaces.
  14     * Self-contained, no external dependencies
  15     * Easy to compile and uses POSIX make.
  16
  17 ## Limitations
  18 * Input lines are limited to `LINE_MAX` bytes in length.
  19
  20 ## Build dependencies
  21 The only dependency is a toolchain supporting the following flags:
  22
  23 ```
  24 CFLAGS = -std=c99 -O2 -Wall -Wextra -Wpedantic \
  25         -Walloca -Wcast-qual -Wconversion -Wformat=2 -Wformat-security \
  26         -Wnull-dereference -Wstack-protector -Wvla -Warray-bounds \
  27         -Wbad-function-cast -Wconversion -Wshadow -Wstrict-overflow=4 -Wundef \
  28         -Wstrict-prototypes -Wswitch-default -Wfloat-equal -Wimplicit-fallthrough \
  29         -Wpointer-arith -Wswitch-enum \
  30         -D_FORTIFY_SOURCE=2 \
  31         -fstack-protector-strong -fPIE -fstack-clash-protection
  32
  33 LDFLAGS = -Wl,-z,relro -Wl,-z,now -Wl,-z,noexecstack -Wl,-z,separate-code
  34 ```
  35
  36 Otherwise you can just remove the security flags and compile it with
  37 ```
  38 CFLAGS = -std=c99 -O2 -Wall -Wextra -Wpedantic
  39 LDFLAGS =
  40 ```
  41
  42 or pass your own flags to make
  43 ```sh
  44 make CC=gcc CFLAGS=... LDFLAGS=...
  45 ```
  46
  47 ## Installation
  48 Clone this repository then
  49
  50 ```sh
  51 $ make PREFIX=/usr install
  52 ```
  53
  54 This will install the compiled binary under `PREFIX` (`/usr/bin`) in this case, if not specified `PREFIX` will default
  55 to `/usr/local`. For staged installs, `DESTDIR` is also supported. As the binary does not have any dependency it does
  56 not have to be installed before use.
  57
  58 ## Usage
  59 The _range_ parameter is used to express a range of lines or columns to be printed. The lower and upper bounds of the
  60 interval must be positive integer numbers. If the lower bound is equal to the upper bound, only one line (or column)
  61 will be printed. If the upper bound is greater than the amount of lines (or columns) the output stops at the last line
  62 (or column).
  63
  64 The options are as follows:
  65
  66 * **-c** Interpret the specified range a range of columns. The result is that it prints the contents of the file within
  67 the column range.
  68 * **-h** Print usage information and exit.
  69
  70 ### Examples
  71 Print lines between 5 and 23 from standard input until it receives an EOF (`^D`) character
  72 ```sh
  73 $ line '5,23'
  74 ```
  75
  76 Print, for each line,  the characters between column 5 and 100
  77 ```sh
  78 $ line -c "5,100"
  79 ```
  80
  81 Print only line 7
  82 ```
  83 $ line '7,7'
  84 ```
  85
  86 ### Test suite
  87 The test suite consists of a POSIX shell script called `harness.sh` contained in the `test` folder. It's output is
  88 similar to [googletest](https://github.com/google/googletest)'s and it can be invoked with `make test` which, if
  89 everything is working should output something similar to
  90 ```sh
  91 (cd test && ./harness.sh)
  92 [----------] Test environment set-up.
  93 [==========] Running 6 test cases.
  94 [ RUN      ] should_handle_stdin
  95 [       OK ] should_handle_stdin
  96 [ RUN      ] should_handle_singleline
  97 [       OK ] should_handle_singleline
  98 [ RUN      ] should_handle_singlecolumn
  99 [       OK ] should_handle_singlecolumn
 100 [ RUN      ] should_handle_multiplelines
 101 [       OK ] should_handle_multiplelines
 102 [ RUN      ] should_handle_multiplecolumns
 103 [       OK ] should_handle_multiplecolumns
 104 [ RUN      ] should_handle_empty_string
 105 [       OK ] should_handle_empty_string
 106 [==========] 6 test cases ran.
 107 [  PASSED  ] 6 tests.
 108 [  FAILED  ] 0 tests.
 109 [----------] Test environment teardown.
 110 ```
 111
 112 ### Static analysis
 113 Static analysis on the code base is done by using clang's static analyzer run through `scan-build.sh` which wraps the
 114 `scan-build` utility. The checkers used are part of the
 115 [Experimental Checkers](https://releases.llvm.org/12.0.0/tools/clang/docs/analyzer/checkers.html#alpha-checkers)
 116 (aka *alpha* checkers):
 117
 118 * `alpha.security`
 119 * `alpha.core.CastSize`
 120 * `alpha.core.CastToStruct`
 121 * `alpha.core.IdenticalExpr`
 122 * `alpha.core.PointerArithm`
 123 * `alpha.core.PointerSub`
 124 * `alpha.core.SizeofPtr`
 125 * `alpha.core.TestAfterDivZero`
 126 * `alpha.unix`
 127
 128 ## License
 129 BSD 2-Clause FreeBSD License, see LICENSE.
 130