💾 Archived View for gmi.noulin.net › sheepy › libsheepyReadme.md captured on 2024-08-25 at 10:07:06.
⬅️ Previous capture (2023-07-10)
-=-=-=-=-=-=-
- [libsheepy](#libsheepy) - [Features](#features) - [Compilation](#compilation) - [Install](#install) - [Examples](#examples) - [Demo](#demo) - [Readme](#readme-example) - [Showdir](#showdir-example) # libsheepy libsheepy is C library for handling text files and strings. Status: __libsheepy and libsheepyObject implemented__ The API in libsheepy.h is stable and tested, libsheepyObject.h is stable and tested. Current API is compatible with future version of libsheepy and will be changed only if a serious bug is found (rare). The version number are x.Major.Minor.Patch and is updated like this: - when Patch changes for bug fixes or small changes in documentation, build scripts, ... - when Minor changes, the API is extended only (new functions, ...) - when Major changes, the API is changed in backward compatible way (rare) Future: (mainly speed improvements) - optimize memory management - optimize internals - add functions saving results in given objects - create generics calling class functions directly Usage: I use libsheepy in C scripts and resource limited environments Platforms: - Linux/GNU, Intel (Ivy Bridge or newer for DRNG RDRAND) - Linux/GNU, ARM (raspberry pi) - Android/Termux ARM - MacOS - FreeBSD - OpenBSD - DragonflyBSD - Alpine Linux (musl libc) - OpenIndiana (illumos, solaris, sunOS) - Haiku 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). The functions in libsheepy are similar to their equivalent functions in javascript or python. For example: - `upperS` is equivalent to `.upper()` in python. - `forEach` is similar to the javascript `forEach`. - `enumerate` is similar to the python `enumerate`. There are __2 parts__ in libsheepy: 1. C functions: simple data structures and functions, implemented in __libsheepy.h and libsheepy.c__ 2. C objects: json, dictionary, array objects, __libsheepyObject.h__ is the header to include. libsheepy uses the type `char **` to represent the lists (dynamic array of strings). The end of the list is NULL. libsheepy is NULL safe and any parameter can be NULL. - the list*S functions assume the list elements are not NULL - 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. 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/) __Status__: (libsheepy.h and libsheepy.c) - Unit tests: 97% code coverage of the core functionality - 98% branch coverage (mainly malloc failures are not tested) - Valgrind - Memcheck: No memory leaks - 94% code coverage of the core functionality - Static analysis: done with cppcheck, clang static analyzer, gcc static analyzer, coverity, facebook infer - GCC warnings: Enabled all useful warnings in GCC 10.2 and removed them. # Features - stability: libsheepy releases identical MAJOR version are backward compatible, in future MAJOR version the API will be backward compatible as much as possible - 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) - error reporting - setjmp, longjmp macros - short int names: i8, i16, i32... - MIN, MAX macros ... - cast macros - logging - terminal color control codes - time functions - file/path functions - random numbers software and hardware - user input functions (passwords) - string functions - array (static, dynamic) - for queues, rings, stacks... - dictionary, json object, stringify and parsing - thread pool - UTF-8 string functions: length, makeValid... - json and yml parsers # Compilation and install To be able to compile, __gcc__ (4.9 or newer for libsheepyObject) and __make__ have to be installed on the machine. In the root directory run:
apk add gcc libc-dev git
pkg install git clang
pkg install git gcc-8 system/header
git clone https://spartatek.se/git/libsheepy.git
cd libsheepy
git pull
./make.sh
./makeTermux.sh
./makeOpenIndiana.sh
For home folder install instead of running `make.sh`, run:
./homeMake.sh
The compiled lib and headers are in release/ after `make all` or `build.sh` successfully executed The lib is installed in `/usr/local/` and in `/data/data/com.termux/files/usr/` in Termux 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:
./clean.sh
./buildMusl.sh
./install.sh
For the musl libc setup in sheepy, see [README.md](https://spartatek.se/r/sheepy/file/README.md.html) in the sheepy repo # Examples This code shows some features of the smallArray and smallJson classes:
// array declaration
smallArrayt *array;
// object init
initiateG(&array);
// push strings to array
pushManySG(array, "first string", "second string", "end");
// print array
logVarG(array);
// add a bool at index -3 (0 is beginning of the array, -1 is the end)
injectG(array, -3, TRUE);
// add an int element at the end
pushG(array, 2);
// print array
putsG(array);
// loop on the array elements
iter(array, element) {
// print index and element
printf("Element index %d, value: %m\n", iterIndexG(array), element);
}
// free array
terminateG(array);
// create a local json object
createSmallJson(json);
// parse json string
parseG(&json, "{\"key1\": [1,2], \"key2\": {\"subkey1\": \"a value\"}}");
// or use _ instead of \" for readabilty:
// parseG(&json, "{"_"key1"_": [1,2], "_"key2"_": {"_"subkey1"_": "_"a value"_"}}");
// print json
logVarG(&json);
// free buffers in json object
freeG(&json);
## Demo A demo illustrating how to use libsheepy is located in the `example` folder. The demo runs on both linux and macOS. The demo shows how to use: `execOut`, `exitFailure`, `listPushS`, `listPrintS`, `forEach`, `split`, `listGetS`, `strEq`, `trimS`, `listCreateS`, `enumerate` ## Linux In linux, the demo can be executed as a C script if `tcc` is installed.
apt-get install tcc
cd example
./demoScript.c
Alternatively, compile the C files with:
cd example
./compileLinux.sh
./demo
## Termux Compile with (adding `-D__TERMUX__=1 -D__arm__=1` to the linux gcc commands):
cd example
gcc -D__TERMUX__=1 -D__arm__=1 -g3 -std=gnu99 -c ../release/libsheepy.c
gcc -D__TERMUX__=1 -D__arm__=1 -std=gnu99 -o demo demo.c libsheepy.o
./demo
## MacOS Compile the C files and run like this:
cd example
./compileMacOS.sh
./demo
## Expected results from the demo The results from the demo look like this:
./demo
Steps
- execOut "ls"
- push "libsheepy" at the end of list
- push CLI argument
- print list
- forEach print lines containing the words two or libsheepy
total 0
drwxr-xr-x 1 remy remy 12 Dec 22 14:19 .
drwxr-xr-x 1 remy remy 742 Dec 24 16:09 ..
-rw-r--r-- 1 remy remy 0 Dec 22 14:19 one
drwxr-xr-x 1 remy remy 18 Dec 22 14:19 two
libsheepy
Print lines with string "two" or "libsheepy":
drwxr-xr-x 1 remy remy 18 Dec 22 14:19 two
libsheepy
## demoStatic This demo shows how to use the objects in libsheepy.
make
cd example
gcc -g3 -std=gnu99 -o demoStatic demoStatic.c ../release/libsheepy.a -pthread
clang -g3 -std=gnu11 -o demoStatic demoStatic.c ../release/libsheepy.a -pthread
./demoStatic
demoStatic links statically to libsheepy ## readme example This README file is generated using `example/README.template` and `readme.c` The readme shows how to use: `readText`, `forEach`, `trimS`, `isEmptyS`, `findS`, `listPushS`, `sliceS`, `strEq`, `replaceS`, `listAppendS` ## showdir example showdir is a simple program showing the text content of files in current directory or a given path. It shows how to use: `walkDir`, `forEach`, `catS`, `readText`, `listPrintS`, `listFreeS` ## sumNums example `sumNums.c` sums integers in a text file line by line.
INPUT FILE: sum.txt
1
2
3
./sumNumsScript.c sum.txt
RESULT: 6
The sumNums shows how to use: `readText`, `listCompactS`, `trimS`, `forEach`, `split`, `listGetS`, `parseInt` ## cfp example `cfp.c` prints the current working directory in front of the given parameters on the command line. ## search and replace example `search and replace` is useful for refactoring source code. It takes a list of files in `files.txt` and a list of strings to search and replace in `replace_configuration.txt`. It uses the pcre library for the regular expressions. Install pcre with the command:
apt-get install libpcre3-dev
## regex demo example Example with the pcre library. Install pcre with the command:
apt-get install libpcre3-dev
## dmce example `dmce` stands for `did my code execute`. It displays the lines changed in the unstaged files and not executed the unit tests. The program has to be compiled with gcov. `dmce` uses `git diff` to list the changes. ## csv example `csv.c` loads a csv file into 2 lists: a void** list to hold the lines, the lines are split into char** lists. ## inotify example `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. ## objects example `objects.c` prints the list of object types with effects and colors.
make
cd example
gcc -g3 -std=gnu11 -o objects objects.c ../release/libsheepy.a -pthread
./objects
## json example `json.c` shows how to load/print JSON files and YML files. It also shows how to use the `foreach` in dictt objects, `parse`, `parseYML`, `stringify`, `toYML`, `freeO` and `toStringO`
make
cd example
gcc -g3 -std=gnu11 -o json json.c ../release/libsheepy.a -pthread
./json
## csvStatic and dmceStatic examples Theses examples are identical to the csv and dmce examples using libsheepy objects instead.
gcc -g3 -std=gnu11 -o csvStatic csvStatic.c ../release/libsheepy.a -pthread
./csvStatic
gcc -g3 -std=gnu11 -o dmceStatic dmceStatic.c ../release/libsheepy.a -pthread
./dmceStatic