• Libsheepy User Guide
• Sheepy setup
  • Install
  • First Sheepy Program
• Overview
• Defines
• Integer And Float Types
• Macros
• Error Reporting
• Logging
  • Variables
  • Configuration
  • Functions
  • Mask
• Loops
• Printf
  • Specifiers
  • Terminal Colors And Effects
• Stopwatch And Timer
• Naming conventions
• Libsheepy Classes
• Generics
• System Functions
• File Functions
• String Functions
• UTF8
• Arrays, Vector, Slice, Indexer, Slab, Bitsets
• Thread Pool
• Further Information

Libsheepy User Guide

Libsheepy is a generic C library handling text files, strings, json and more.

For an introduction, see libsheepy.

Libsheepy has a build tool called sheepy which runs C programs like scripts

This document shows how to use libsheepy for a user perspective. There is a detailed documentation at https://spartatek.se/libsheepy/ where each function has a description.

Sheepy setup

Install

git clone https://spartatek.se/git/sheepy.git
cd sheepy

sudo -H ./install.sh

First Sheepy Program

Create program with sheepy and run:

sheepy -n example

# run:
./example.c

Overview

Libsheepy has a few concepts and conventions described in the libsheepy overview page in the doxygen documentation:

• top-level includes
• function categories
• naming conventions
• memory management
• classes and objects

It is also helpful to look at the examples.

libsheepy.h is the API operating on basic data types.

The doxygen documentation is more detailed than this userguide and the source code is available to browse.

Defines

Example code:

local bool abool = false;            // static bool
puts(boolS(abool));                  // convert bool value to string
put                                  // new line
typ struct { u32 a; char *s;} datat; // typedef
datat data = init0Var;

if (not abool or !data.s) {
  data.s = strdup("string");
  toUpper(data.s[0]);
  ret;
}
elif (data.s and eqG(data.s, "Quit")) { // else if
  XSUCCESS;                             // exit(0);
}

void func(int a UNUSED, int b UNUSED) {
  ret;
}

• For further information, read libsheepy.h

Integer And Float Types

• For further information, read libsheepy.h

Macros

• For further information, read libsheepy.h

Error Reporting

The error reporting macros print an error message and the backtrace (glibc only).

• For further information, read libsheepy.h

Logging

• For further information, read libsheepy.h

Variables

There are a few macros logging variable name and their values, mainly for debugging:

int a = 1;

Log:

a=1

Configuration

The logs are printed to the stdout by default, use setLogFile(char *filename) to set a log file or multiple log files (max 15). When initLibsheepy is called, the log files are closed at program exit, use closeLogFiles(void) to explicitly close the log files.

The log mode configuration controls which information (date, function, program,...) is printed in the log, there are 8 modes:

Use setLogMode(int mode) to configure a log mode and getLogMode(void) to get current log mode.

The log symbols indicate the log level and are printed at the beginning of the first line. The log symbols can be set independently of the log mode, use getLogSymbols(void) to get current log mode for symbols and setLogSymbols(int mode) to set log symbols, choose LOG_VERBOSE for words, LOG_UTF8 for emojis, LOG_VOID for no symbols, LOG_INVALID_MODE (reset log symbols) for default log mode symbols, anything else (LOG_CONCISE,...) for symbols (!*+->~).

The short path configuration (setLogShortPath(bool shortPath) and getLogShortPath(void)) controls the length of the filename in the LOG_VERBOSE mode.

The max log level configuration (setMaxLogLevel(int logLevel) and getMaxLogLevel(void)) allows skipping the higher log level or completely disable all logs at runtime.

To disable logs at compile time anywhere in the code (local to the source file), undefine the pLog macro:

/* enable/disable logging */
#undef pLog
#define pLog(...)

To disable the logs at runtime, run:

setMaxLogLevel(LOG_DISABLE);

The libsheepy functions print log messages when errors are encountered, these logs are disabled with the disableLibsheepyErrorLogs macro:

// Mask libsheepy error logs
disableLibsheepyErrorLogs;

Functions

There are 5 log levels: critical, error, warning, pass and info. The functions for the log level end with the first letter of the log level: logC for critical, logI for info...

Mask

The logM macros are maskable at runtime. The mask configuration is stored in the logMask variable and libsheepy uses bit 63 (libsheepyErrorMask) in logMask.

showLogsInMask(mask) and hideLogsInMask(mask) shows or hides logs in a mask.

To disable the logM macros at compile time, undefine pLogMask:

#undef pLogMask
#define pLogMask(...)

For example:

#define group1 0x03
#define group11 0x01
#define group12 0x02
#define group2 0x04

showLogsInMask(group11);
logMI(group1, "is shown when logMask has bit 0 or 1 set");
logMI(group11, "is shown when logMask has bit 0 set");
logMI(group12, "is shown when logMask has bit 1 set");
logMI(group2, "is shown when logMask has bit 2 set");

Loops

Libsheepy has a loop breaker system that breaks possible infinite loops. loopBreakerInit initializes the loop breaker before the loop, loopBreakerReset resets the loop breaker for the next loop and loopBreaker(breakCount) breaks the loop after breakCount loops.

Usage:

loopBreakerInit;
forever {
  loopBreaker(20);
}
if (didBreak) logE("infinite loop detected");
loopBreakerReset;
forever {
  loopBreaker(100);
}
if (didBreak) logE("infinite loop detected");

There are also iterators for the libsheepy objects implementing the iterator interface. The libsheepy classes with iterator interfaces are: smallArrayt, smallDictt and smallJsont

For example:

var array = createSA("1", "2", "3");
iter(array, elem) {
  logVarG(elem);
}

• For further information, read libsheepy.h

Printf

Specifiers

The specifiers are available when libsheepy is compiled against glibc.

Terminal Colors And Effects

The terminal colors can be added in any string that will be printed in a terminal. The string part with the effect starts with the chosen effect, for example BLD and ends with RST to cancel the effect. Terminal colors and effects are allowed to be combined: BLD RED "bold red" RST.

For example:

char *s = "This " BLD"color"RST " is " RED"red"RST ".";

- This and is have normal color
- color is bold
- red is red

Use stripCtrlS to remove terminal colors from a string.

When libsheepy is linked to glibc, it is possible to print RGB colors with %k and %K, the colors are coded as hexadecimal RGB:

logI("%k%KRGB color" RST, 0x99EEFF, 0x666666);

• For further information, read libsheepy.h

Stopwatch And Timer

For example:

stopwatchStart;
... code ...
stopwatchLogUs; // log time spent in code section

• For further information, read libsheepy.h and libsheepy.c

Naming conventions

Libsheepy Classes

All classes in libsheepy inherit from the baset class, the baset methods are: free, terminate, toString, duplicate.

All classes have a set of functions for creating and destroying objects:

• create*, createAllocate* declare and allocate objects. create* declare local objects that need to be freed (with freeG) but cannot be terminated. createAllocate* declare a pointer and allocate the object, the object has to be terminated (or smashed, terminateG or smashG)
• initiate*, initiateAllocate* allocate already declared objects
• alloc* allocate objects and return them, an initial value is sometime required.

These function names end with either: SmallArray, SmallBool, SmallBytes, SmallContainer, SmallDict, SmallDouble, SmallInt, SmallJson, SmallString, Undefined

For example: createSmallJson(jsonObject) declares a local json object. freeG(jsonObject) frees the internal buffers.

The class name are: smallArrayt, smallBoolt, smallBytest, smallContainert, smallDictt, smallDoublet, smallIntt, smallJsont, smallStringt, undefinedt

Objects of type:

• smallArrayt hold objects of type smallArrayt, smallBoolt, smallBytest, smallContainert, smallDictt, smallDoublet, smallIntt, smallStringt, undefinedt
• smallBoolt hold a bool value
• smallBytest hold a void buffer of bytes
• smallContainert hold a void pointer
• smallDictt are dictionaries of key-values with key as strings (char*) and with values of type smallArrayt, smallBoolt, smallBytest, smallContainert, smallDictt, smallDoublet, smallIntt, smallStringt, undefinedt
• smallDoublet hold a double
• smallIntt hold an int64_t
• smallJsont hold either a smallArrayt, a smallBoolt, a smallDictt, a smallDoublet, a smallIntt, a smallStringt or an undefinedt
• smallStringt hold a string (char*)
• undefinedt don't hold any data and are represented as null

Use sheepy -C classname to generate your own baset class from templates.

Generics

The macros create* and createAllocate* declare and initialize new object:

createAllocteSmallArray(array);
createSmallDict(dict);

Objects can be declared like other variables and then initialized with initiateG or allocG

smallArrayt *array;
smallDict dict;
smallStringt *string;

initiateG(&array);
initiateG(&dict);
string = allocG("new string");

The regular generic call format is:

methodG(object, other parameters...);

result = method2G(object, other parameters...);

To get the value in smallBool, smallDouble, smallInt, smallString use getValG(self).

To get a value in smallArrayt, smallDictt or smallJsont use getG(self, returnType, key).

To set a value in smallBool, smallDouble, smallInt, smallString use setFromG(self, value).

To set a value in smallArrayt, smallDictt or smallJsont use setG(self, returnType, key).

getG and setG support smallBool, smallDouble, smallInt, smallString types by setting returnType to unusedV.

The generics support these types where it makes sense:

• int, uint
• double
• char*
• char**
• smallArrayt
• smallBoolt
• smallBytest
• smallContainert
• smallDictt
• smallDoublet
• smallIntt
• smallJsont
• smallStringt
• undefinedt

For type char* and char**, the functions in lisheepy.h are called.

The generics returning a value have a returnType parameter, the possible values for returnType are:

• rtBaset
• rtBool
• rtBoolP
• rtDouble
• rtDoubleP
• rtInt64_t
• rtInt64_tP
• rtInt32_t
• rtInt32_tP
• rtUint64_t
• rtUint64_tP
• rtUint32_t
• rtUint32_tP
• rtF32
• rtF64
• rtF64P
• rtI64
• rtI64P
• rtI32
• rtI32P
• rtU64
• rtU64P
• rtU32
• rtU32P
• rtU8
• rtU16
• rtChar for char*
• rtSmallArrayt
• rtSmallBoolt
• rtSmallBytest
• rtSmallDictt
• rtSmallDoublet
• rtSmallIntt
• rtSmallJsont
• rtSmallStringt
• rtSmallContainert
• undefined or rtUndefinedt
• rtVoid

For example getG(dict, rtBool, "a") returns a bool and with rtBoolP it returns a pointer to a bool.

• For further information, read:
  • libsheepyObject.h lists all the generics
  • the class header files (libsheepyC*.h) have detailed method descriptions for each class:
    • libsheepyCSmallArray.h
    • libsheepyCSmallBool.h
    • libsheepyCSmallBytes.h
    • libsheepyCSmallContainer.h
    • libsheepyCSmallDict.h
    • libsheepyCSmallDouble.h
    • libsheepyCSmallInt.h
    • libsheepyCSmallJson.h
    • libsheepyCSmallString.h
    • libsheepyCUndefined.h

System Functions

• For further information, read libsheepy.h and libsheepy.c

File Functions

• For further information, read libsheepy.h and libsheepy.c

String Functions

• For further information, read libsheepy.h and libsheepy.c

UTF8

• For further information, read libsheepy.h and libsheepy.c

Arrays, Vector, Slice, Indexer, Slab, Bitsets

slice, staticSlice, vector, dVector, staticArray, dArray, slab, staticBitset, bitset are data structures defined in libsheepy.h.

They are arrays of user defined element type with counters and the other properties not available with C arrays.

The elements are accessed directly like regular C arrays with the At macros: vectorAt(&vectr, 1) = 3;.

The indexer allows seperating the data from the maximum count, head and last indexes. The indexer macros operate on a struct holding count, head and last indexes.

slice, staticSlice, vector, dVector, staticArray, dArray, slab are prefixes for the macros operating on the data structures. The macros define the types and handle the elements.

Bitset macros:

Examples:

sliceT(typeName, type);
typeName slce;
sliceInit(&slce);
// or
sliceInitCount(&slce, 17);
sliceAppend(&slce, value);
// get an element
int a                = sliceAt(&slce, 0);
// set
sliceAt(&slce, 1) = 3;
sliceFree(&slce);

staticSliceT(typeName, type, 10);
typeName slce;
staticSliceInit(&slce);
staticSliceAppend(&slce, value);
// get an element
int a                = staticSliceAt(&slce, 0);
// set
staticSliceAt(&slce, 1) = 3;
staticSliceFree(&slce);

vectorT(typeName, type);
typeName vectr;
vectorInit(&vectr);
// or
vectorInitCount(&vectr, 17);
vectorAppend(&vectr, value);
// get an element
int a                = vectorAt(&vectr, 0);
// set
vectorAt(&vectr, 1) = 3;
vectorFree(&vectr);

dVectorT(typeName, type);
typeName dvector;
dVectorInit(&dvector);
// or
dVectorInitCount(&dvector, 17);
dVectorAppend(&dvector, value);
// get an element
int a                = dVectorAt(&dvector, 0);
// set
dVectorAt(&dvector, 1) = 3;
dVectorFree(&dvector);

typedef struct {
  int a;
  char *key;
} element;
staticArrayT(typeName, element, 10);
typeName array;
staticArrayInit(array);
staticArrayPush(array);
staticArrayLast(array).a = fork();
val = staticArrayLast(array).a;
staticArrayPop(array);

char array[10][5];
// declare an indexer with smaller counters (default is int64_t):
indexerT(typeName, i8);
typeName indx;
indexerInit(indx, 10);
indexerPush(indx);
array[indexerLast(indx)][0] = '0';
// or
indexerPush(indx);
array[indx.last][0] = '0';
indexerPop(indx);
// accessing the first/head element
char c = array[indexerFirst(indx)][0];
char c = array[indx.head][0];

dArrayT(typeName, type);
typeName darray;
dArrayInit(&darray);
// or
dArrayInitCount(&darray, 17);
dArrayAppend(&darray, value);
// get an element
int a                = dArrayAt(&darray, 0);
// set
dArrayAt(&darray, 1) = 3;
dArrayFree(&darray);

slabT(typeName, type);
typeName slab;
slabInit(&slab);
// or
slabInitCount(&slab, 17);
slabAppend(&slab, value);
// get an element
int a                = slabAt(&slab, 0);
// set
slabAt(&slab, 1) = 3;
slabFree(&slab);

• For further information, read libsheepy.h

Thread Pool

The thread pool is initialized by initLibsheepy and the prefix for the thread pool is tpool.

The thread pool runs functions of type void f(void *p) where p is a pointer of your choice.

The functions are added to the thread pool queue using tpoolAdd and the first available thread runs the first function in the queue.

There is one thread per core and the threads are started with CPU affinity so they always run on the same core.

tpollWait waits until all the functions in the thread pool queue are finished.

tpool.h is the header for the thread pool and is included in libsheepyObject.h.

Thread pool function list:

Example:

int i = 0;

void emptyTask() {
  puts("the empty task");
}

void incTask(void *p) {
  int *i = (int*)p;
  sleep(1);
  (*i)++;
}

int main(int ARGC, char** ARGV) {
  initLibsheepy(ARGV[0]);
  tpoolAdd(emptyTask, NULL);
  tpoolAdd(incTask, &i);
  puts("Threads are running");
  tpoolWait;
  puts("All functions are finished");
}

Further Information

• libsheepy.h and libsheepy.c have detailed function descriptions
• libsheepyObject.h the API file to include in user programs
• the class header files (libsheepyC*.h) have detailed method descriptions for each class:
  • libsheepyCSmallArray.h
  • libsheepyCSmallBool.h
  • libsheepyCSmallBytes.h
  • libsheepyCSmallContainer.h
  • libsheepyCSmallDict.h
  • libsheepyCSmallDouble.h
  • libsheepyCSmallInt.h
  • libsheepyCSmallJson.h
  • libsheepyCSmallString.h
  • libsheepyCUndefined.h