README.template (10448B)
1 - [libsheepy](#libsheepy) 2 - [Features](#features) 3 - [Compilation](#compilation) 4 - [Install](#install) 5 - [Examples](#examples) 6 - [Demo](#demo) 7 - [Readme](#readme-example) 8 - [Showdir](#showdir-example) 9 10 # libsheepy 11 libsheepy is C library for handling text files and strings. 12 13 Status: __libsheepy and libsheepyObject implemented__ 14 15 The API in libsheepy.h is stable and tested, libsheepyObject.h is stable and tested. 16 Current API is compatible with future version of libsheepy and will be changed only if a serious bug is found (rare). 17 18 The version number are x.Major.Minor.Patch and is updated like this: 19 - when Patch changes for bug fixes or small changes in documentation, build scripts, ... 20 - when Minor changes, the API is extended only (new functions, ...) 21 - when Major changes, the API is changed in backward compatible way (rare) 22 23 24 Future: (mainly speed improvements) 25 - optimize memory management 26 - optimize internals 27 - add functions saving results in given objects 28 - create generics calling class functions directly 29 30 Usage: I use libsheepy in C scripts and resource limited environments 31 32 Platforms: 33 - Linux/GNU, Intel (Ivy Bridge or newer for DRNG RDRAND) 34 - Linux/GNU, ARM (raspberry pi) 35 - Android/Termux ARM 36 - MacOS 37 - FreeBSD 38 - OpenBSD 39 - DragonflyBSD 40 - Alpine Linux (musl libc) 41 - OpenIndiana (illumos, solaris, sunOS) 42 - Haiku 43 44 libsheepy is the default library in the [sheepy project](https://spartatek.se/r/sheepy/file/README.md.html) (sheepy is a build system to run c programs like scripts). 45 46 The functions in libsheepy are similar to their equivalent functions in javascript or python. 47 For example: 48 49 - `upperS` is equivalent to `.upper()` in python. 50 - `forEach` is similar to the javascript `forEach`. 51 - `enumerate` is similar to the python `enumerate`. 52 53 There are __2 parts__ in libsheepy: 54 55 1. C functions: simple data structures and functions, implemented in __libsheepy.h and libsheepy.c__ 56 2. C objects: json, dictionary, array objects, __libsheepyObject.h__ is the header to include. 57 58 libsheepy uses the type `char **` to represent the lists (dynamic array of strings). The end of the list is NULL. 59 60 libsheepy is NULL safe and any parameter can be NULL. 61 62 - the list*S functions assume the list elements are not NULL 63 - the listn*S functions can process lists with NULL elements. When there are NULL elements, the developer has to keep track of the list length. 64 65 Check out the [user guide](https://spartatek.se/libsheepyUserGuide/) to learn how to use libsheepy and read the more detailed documentation at [https://spartatek.se/libsheepy/](https://spartatek.se/libsheepy/) 66 67 __Status__: (libsheepy.h and libsheepy.c) 68 - Unit tests: 97% code coverage of the core functionality - 98% branch coverage (mainly malloc failures are not tested) 69 - Valgrind - Memcheck: No memory leaks - 94% code coverage of the core functionality 70 - Static analysis: done with cppcheck, clang static analyzer, gcc static analyzer, coverity, facebook infer 71 - GCC warnings: Enabled all useful warnings in GCC 10.2 and removed them. 72 73 # Features 74 75 - stability: libsheepy releases identical MAJOR version are backward compatible, in future MAJOR version the API will be backward compatible as much as possible 76 - few generics to handle all types (for example: eqG(a,b) true when the a and b values are equal, a can be an int and b can be a string representing an int) 77 - error reporting 78 - setjmp, longjmp macros 79 - short int names: i8, i16, i32... 80 - MIN, MAX macros ... 81 - cast macros 82 - logging 83 - terminal color control codes 84 - time functions 85 - file/path functions 86 - random numbers software and hardware 87 - user input functions (passwords) 88 - string functions 89 - array (static, dynamic) - for queues, rings, stacks... 90 - dictionary, json object, stringify and parsing 91 - thread pool 92 - UTF-8 string functions: length, makeValid... 93 - json and yml parsers 94 95 # Compilation and install 96 97 To be able to compile, __gcc__ (4.9 or newer for libsheepyObject) and __make__ have to be installed on the machine. 98 99 In the root directory run: 100 101 ``` 102 # Apline Linux only 103 apk add gcc libc-dev git 104 # End Alpine Linux 105 106 # Termux only 107 pkg install git clang 108 # End Termux 109 110 # OpenIndiana 111 pkg install git gcc-8 system/header 112 # End OpenIndiana 113 114 git clone https://spartatek.se/git/libsheepy.git 115 cd libsheepy 116 git pull 117 118 # All except Termux and OpenIndiana 119 ./make.sh 120 121 # Termux only 122 ./makeTermux.sh 123 124 # OpenIndiana only 125 ./makeOpenIndiana.sh 126 ``` 127 128 For home folder install instead of running `make.sh`, run: 129 130 ``` 131 # Home folder install 132 ./homeMake.sh 133 134 # And create the LIBSHEEPY environment variable as shown at the end of the homeMake.sh script 135 ``` 136 137 The compiled lib and headers are in release/ after `make all` or `build.sh` successfully executed 138 139 The lib is installed in `/usr/local/` and in `/data/data/com.termux/files/usr/` in Termux 140 141 On systems using glibc, it is possible to link against the musl libc (musl libc must be installed in the system, typically on /usr/local/) by running: 142 143 ``` 144 ./clean.sh 145 ./buildMusl.sh 146 ./install.sh 147 ``` 148 149 For the musl libc setup in sheepy, see [README.md](https://spartatek.se/r/sheepy/file/README.md.html) in the sheepy repo 150 151 # Examples 152 153 This code shows some features of the smallArray and smallJson classes: 154 155 ```c 156 // array declaration 157 smallArrayt *array; 158 // object init 159 initiateG(&array); 160 161 // push strings to array 162 pushManySG(array, "first string", "second string", "end"); 163 164 // print array 165 logVarG(array); 166 167 // add a bool at index -3 (0 is beginning of the array, -1 is the end) 168 injectG(array, -3, TRUE); 169 170 // add an int element at the end 171 pushG(array, 2); 172 173 // print array 174 putsG(array); 175 176 // loop on the array elements 177 iter(array, element) { 178 // print index and element 179 printf("Element index %d, value: %m\n", iterIndexG(array), element); 180 } 181 182 // free array 183 terminateG(array); 184 185 // create a local json object 186 createSmallJson(json); 187 188 // parse json string 189 parseG(&json, "{\"key1\": [1,2], \"key2\": {\"subkey1\": \"a value\"}}"); 190 // or use _ instead of \" for readabilty: 191 // parseG(&json, "{"_"key1"_": [1,2], "_"key2"_": {"_"subkey1"_": "_"a value"_"}}"); 192 193 // print json 194 logVarG(&json); 195 196 // free buffers in json object 197 freeG(&json); 198 ``` 199 200 ## Demo 201 202 A demo illustrating how to use libsheepy is located in the `example` folder. 203 204 The demo runs on both linux and macOS. 205 206 The demo shows how to use: `execOut`, `exitFailure`, `listPushS`, `listPrintS`, `forEach`, `split`, `listGetS`, `strEq`, `trimS`, `listCreateS`, `enumerate` 207 208 ## Linux 209 210 In linux, the demo can be executed as a C script if `tcc` is installed. 211 212 ``` 213 apt-get install tcc 214 cd example 215 ./demoScript.c 216 ``` 217 218 Alternatively, compile the C files with: 219 220 ``` 221 cd example 222 ./compileLinux.sh 223 ./demo 224 ``` 225 226 ## Termux 227 228 Compile with (adding `-D__TERMUX__=1 -D__arm__=1` to the linux gcc commands): 229 230 ``` 231 cd example 232 gcc -D__TERMUX__=1 -D__arm__=1 -g3 -std=gnu99 -c ../release/libsheepy.c 233 gcc -D__TERMUX__=1 -D__arm__=1 -std=gnu99 -o demo demo.c libsheepy.o 234 ./demo 235 ``` 236 237 ## MacOS 238 239 Compile the C files and run like this: 240 241 ``` 242 cd example 243 ./compileMacOS.sh 244 ./demo 245 ``` 246 247 ## Expected results from the demo 248 249 The results from the demo look like this: 250 251 ``` 252 ./demo 253 254 Steps 255 - execOut "ls" 256 - push "libsheepy" at the end of list 257 - push CLI argument 258 - print list 259 - forEach print lines containing the words two or libsheepy 260 261 total 0 262 drwxr-xr-x 1 remy remy 12 Dec 22 14:19 . 263 drwxr-xr-x 1 remy remy 742 Dec 24 16:09 .. 264 -rw-r--r-- 1 remy remy 0 Dec 22 14:19 one 265 drwxr-xr-x 1 remy remy 18 Dec 22 14:19 two 266 libsheepy 267 268 Print lines with string "two" or "libsheepy": 269 270 drwxr-xr-x 1 remy remy 18 Dec 22 14:19 two 271 libsheepy 272 273 ``` 274 275 ## demoStatic 276 277 This demo shows how to use the objects in libsheepy. 278 279 ``` 280 make 281 cd example 282 gcc -g3 -std=gnu99 -o demoStatic demoStatic.c ../release/libsheepy.a -pthread 283 # or with clang 284 clang -g3 -std=gnu11 -o demoStatic demoStatic.c ../release/libsheepy.a -pthread 285 ./demoStatic 286 ``` 287 288 demoStatic links statically to libsheepy 289 290 ## readme example 291 292 This README file is generated using `example/README.template` and `readme.c` 293 294 The readme shows how to use: `readText`, `forEach`, `trimS`, `isEmptyS`, `findS`, `listPushS`, `sliceS`, `strEq`, `replaceS`, `listAppendS` 295 296 ## showdir example 297 298 showdir is a simple program showing the text content of files in current directory or a given path. 299 300 It shows how to use: `walkDir`, `forEach`, `catS`, `readText`, `listPrintS`, `listFreeS` 301 302 ## sumNums example 303 304 `sumNums.c` sums integers in a text file line by line. 305 306 ``` 307 INPUT FILE: sum.txt 308 1 309 2 310 3 311 312 ./sumNumsScript.c sum.txt 313 314 RESULT: 6 315 ``` 316 317 The sumNums shows how to use: `readText`, `listCompactS`, `trimS`, `forEach`, `split`, `listGetS`, `parseInt` 318 319 ## cfp example 320 321 `cfp.c` prints the current working directory in front of the given parameters on the command line. 322 323 ## search and replace example 324 325 `search and replace` is useful for refactoring source code. 326 327 It takes a list of files in `files.txt` and a list of strings to search and replace in `replace_configuration.txt`. 328 329 It uses the pcre library for the regular expressions. 330 331 Install pcre with the command: 332 333 ``` 334 apt-get install libpcre3-dev 335 ``` 336 337 ## regex demo example 338 339 Example with the pcre library. 340 341 Install pcre with the command: 342 343 ``` 344 apt-get install libpcre3-dev 345 ``` 346 347 ## dmce example 348 349 `dmce` stands for `did my code execute`. It displays the lines changed in the unstaged files and not executed the unit tests. 350 351 The program has to be compiled with gcov. 352 353 `dmce` uses `git diff` to list the changes. 354 355 ## csv example 356 357 `csv.c` loads a csv file into 2 lists: a void** list to hold the lines, the lines are split into char** lists. 358 359 ## inotify example 360 361 `inotify.c` checks the changes in *.h and *.c files in the tree under the current working directory and runs a command given in parameter. 362 363 ## objects example 364 365 `objects.c` prints the list of object types with effects and colors. 366 367 ``` 368 make 369 cd example 370 gcc -g3 -std=gnu11 -o objects objects.c ../release/libsheepy.a -pthread 371 ./objects 372 ``` 373 374 ## json example 375 376 `json.c` shows how to load/print JSON files and YML files. 377 378 It also shows how to use the `foreach` in dictt objects, `parse`, `parseYML`, `stringify`, `toYML`, `freeO` and `toStringO` 379 380 ``` 381 make 382 cd example 383 gcc -g3 -std=gnu11 -o json json.c ../release/libsheepy.a -pthread 384 ./json 385 ``` 386 387 ## csvStatic and dmceStatic examples 388 389 Theses examples are identical to the csv and dmce examples using libsheepy objects instead. 390 391 ``` 392 gcc -g3 -std=gnu11 -o csvStatic csvStatic.c ../release/libsheepy.a -pthread 393 ./csvStatic 394 gcc -g3 -std=gnu11 -o dmceStatic dmceStatic.c ../release/libsheepy.a -pthread 395 ./dmceStatic 396 ```