Main header file for WallShell. More...

Data Structures
struct	ws_atomic_bool_t
	Atomic bool structure provided by WallShell. More...

struct	ws_command_t
	Command Data Structure. More...

struct	ws_help_entry_general_t
	General help structure. More...

struct	ws_help_entry_specific_t
	Specific help structure. More...

struct	ws_color_t
	Color structure used internally by WallShell. More...

Typedefs
typedef pthread_mutex_t	ws_mutex_t
	Wrapper around your system's mutex type. More...

typedef uint64_t	ws_thread_id_t
	Wrapper around your system's thread hadnle. More...

Enumerations
enum	ws_error_t
	All potential error returns by WallShell functions. More...

enum	ws_fg_color_t
	All built in foreground colors. More...

enum	ws_bg_color_t
	All built in background colors. More...

enum	ws_stream
	Simple enum relating to stream types that WallShell uses. More...

enum	ws_cursor_t
	Cursor directions. More...

enum	ws_logtype_t
	Logging types. More...

Functions
void	ws_lockMutex (ws_mutex_t *mut)
	Locks the provided mutex. More...

void	ws_unlockMutex (ws_mutex_t *mut)
	Unlocks the provided mutex. More...

ws_mutex_t *	ws_createMutex ()
	Create a mutex. More...

void	ws_destroyMutex (ws_mutex_t *mut)
	Destroys the provided mutex. More...

ws_thread_id_t	ws_getThreadID ()
	Gets the threadID of the calling thread. More...

bool	ws_getAtomicBool (ws_atomic_bool_t *ab)
	Gets the value stored by the atomic bool. More...

void	ws_setAtomicBool (ws_atomic_bool_t *ab, bool b)
	Sets the value of the provided atomic bool. More...

ws_atomic_bool_t *	ws_createAtomicBool (bool b)
	Creates an atomic bool. More...

void	ws_destroyAtomicBool (ws_atomic_bool_t *ab)
	Destroys the provided atomic bool. More...

void	ws_sleep (size_t ms)
	Sleep function wrapper. More...

void	ws_stopTerminal ()
	Stops the currently running terminal. More...

void	ws_setThreadName (char *name)
	Sets the name of the calling thread. More...

void	ws_removeThreadName (const char *name)
	Removes the name of the provided thread. More...

void	ws_printThreadID ()
	Prints the threadID of the calling thread.

void	ws_doPrintThreadID (bool b)
	Set print threadID, which prints the threadID of function calling `ws_logger`. More...

ws_color_t	ws_getCurrentColors ()
	Get the current console colors. More...

ws_color_t	ws_getDefaultColors ()
	Get the current default colors. More...

void	ws_setDefaultColors (ws_color_t c)
	Set the default colors to the provided ones. More...

void	ws_setForegroundDefault (ws_fg_color_t c)
	Set the default foreground color. More...

void	ws_setBackgroundDefault (ws_bg_color_t c)
	Set the default background color. More...

ws_error_t	ws_setForegroundColor (ws_fg_color_t color)
	Sets the foreground color to the provided color. More...

ws_error_t	ws_setBackgroundColor (ws_bg_color_t color)
	Sets the background color to the provided color. More...

ws_error_t	ws_setConsoleColors (ws_color_t colors)
	Set the background and foreground colors to the provided ones. More...

void	ws_setStream (ws_stream type, FILE *stream)
	Sets the stream to the provided one. More...

void	ws_moveCursor (ws_cursor_t direction)
	Moves the cursor once in the provided direction. More...

void	ws_moveCursor_n (ws_cursor_t direction, size_t n)
	Move the cursor n times in the provided direction. More...

ws_error_t	ws_registerCommand (const ws_command_t c)
	Register the command to the command handler. More...

void	ws_deregisterCommand (const ws_command_t c)
	Deregister the provided command. More...

ws_error_t	ws_executeCommand (char *commandBuf)
	Execute a command with the provided buffer. More...

ws_error_t	ws_terminalMain ()
	Main function for the terminal. More...

void	ws_setAsciiDeleteAsBackspace (bool b)
	Some consoles send backspace as ASCII delete (0x7f) instead of '\b'. More...

void	ws_setConsoleLocale ()
	Sets the console locale. More...

void	ws_setConsolePrefix (const char *newPrefix)
	Set the prefix to the provided one. More...

void	ws_initializeDefaultStreams ()
	Initialize all streams to their defaults. More...

void	ws_printGeneralHelp (ws_help_entry_general_t *entry)
	help More...

void	ws_printSpecificHelp (ws_help_entry_specific_t *entry)
	Prints the specific help entry. More...

bool	ws_promptUser (const char *format,...)
	Prompts the user yes/no using the given prompt. More...

bool	ws_compareCommands (const ws_command_t c1, const ws_command_t c2)
	Operator overloading isn't available in C. More...

void	ws_cleanAll ()
	Cleans everything. More...

void	ws_logger (ws_logtype_t type, const char *format,...)
	Logger function for WallShell. More...

void	ws_vlogger (ws_logtype_t type, const char *format, va_list args)
	Logger function for WallShell. More...

void	ws_setLoggerColors (ws_logtype_t type, ws_fg_color_t fg, ws_bg_color_t bg)
	Set the logger colors for the specified log type. More...

Detailed Description

Main header file for WallShell.

Author: MalTheLegend104

C99 compliant command handler. Meant to be easily portable and highly configurable.

Version: v1.0.0

Copyright: Copyright 2024 MalTheLegend104

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Typedef Documentation

◆ ws_mutex_t

typedef pthread_mutex_t ws_mutex_t

Wrapper around your system's mutex type.

Note: pthread_mutex_t is replaced with your systems mutex type.

◆ ws_thread_id_t

typedef uint64_t ws_thread_id_t

Wrapper around your system's thread hadnle.

Note: uint64_t is replaced with your systems thread handle type.

Enumeration Type Documentation

◆ ws_bg_color_t

enum ws_bg_color_t

All built in background colors.

Almost every single terminal will have themed colors relating to these. While it is possible to change to any RGB color using virtual terminal sequences, it's not advised. Using these allows for good cross platform support and is guaranteed to work almost anywhere. These colors are even supported by old BIOS text modes, along with modern VESA and GOP modes.

Note: Almost all of these colors are exactly as the name is described, with the exception of 4. The "yellows" and "magenta" are slightly off of what you'd expect. Typically, WS_BG_MAGENTA is a darker shade of purple, while WS_BG_BRIGHT_MAGENTA is what you'd normally consider magenta. Similarly, WS_BG_YELLOW is typically a shade or orange, while WS_BG_BRIGHT_YELLOW is what you'd expect for yellow.

Warning: Background colors are highly dependent on the terminal being used. It's advised to use WS_BG_DEFAULT if you don't explicitly need a background color. Some terminals have transparency that will be messed up by other color backgrounds. It's also important to note that not every terminal will fill the background when a newline character is used, or for spaces not followed by another character.

◆ ws_cursor_t

enum ws_cursor_t

Cursor directions.

These are internal cursor directions. The values they are assigned are related to their scancodes.

Note: For input using scancodes and not virtual terminal sequences, WallShell expects the E0 scancode before these.

◆ ws_error_t

enum ws_error_t

All potential error returns by WallShell functions.

All returns should be descriptive enough to understand what they mean. Any function that can return a value from this enum will describe what it has the possibility of returning and why.

◆ ws_fg_color_t

enum ws_fg_color_t

All built in foreground colors.

Almost every single terminal will have themed colors relating to these. While it is possible to change to any RGB color using virtual terminal sequences, it's not advised. Using these allows for good cross platform support and is guaranteed to work almost anywhere. These colors are even supported by old BIOS text modes, along with modern VESA and GOP modes.

Note: Almost all of these colors are exactly as the name is described, with the exception of 4. The "yellows" and "magenta" are slightly off of what you'd expect. Typically, WS_FG_MAGENTA is a darker shade of purple, while WS_FG_BRIGHT_MAGENTA is what you'd normally consider magenta. Similarly, WS_FG_YELLOW is typically a shade or orange, while WS_FG_BRIGHT_YELLOW is what you'd expect for yellow.

◆ ws_logtype_t

enum ws_logtype_t

Logging types.

These are meant to be used in conjunction with all logger functions. The logtype determines what will be printed out.

◆ ws_stream

enum ws_stream

Simple enum relating to stream types that WallShell uses.

Mostly used exclusively in ws_setStream().

Function Documentation

◆ ws_cleanAll()

void ws_cleanAll ( )

Cleans everything.

Resets everything to it's default state, frees all allocations, etc. Ideally you should call this before you exit, but the system garbage collector should clean it up. Don't rely on the system gc for critical applications.

◆ ws_compareCommands()

bool ws_compareCommands	(	const ws_command_t	c1,
		const ws_command_t	c2
	)

Operator overloading isn't available in C.

Compare two commands using this.

Parameters

c1	Command to compare.
c2	Command to compare.

Returns: true If they are the same.; false If they are different.

◆ ws_createAtomicBool()

ws_atomic_bool_t* ws_createAtomicBool ( bool b )

Creates an atomic bool.

Parameters

b	Initial value held by the bool.

Returns: NULL if it couldn't be created, pointer to the object otherwise.

◆ ws_createMutex()

ws_mutex_t* ws_createMutex ( )

Create a mutex.

Returns: Pointer to a mutex object if successful, NULL otherwise.

◆ ws_deregisterCommand()

void ws_deregisterCommand ( const ws_command_t c )

Deregister the provided command.

Parameters

c	Command to be deregistered. If it doesn't exist (not already registered), nothing happens.

◆ ws_destroyAtomicBool()

void ws_destroyAtomicBool ( ws_atomic_bool_t * ab )

Destroys the provided atomic bool.

Parameters

ab	Atomic bool to destroy.

◆ ws_destroyMutex()

void ws_destroyMutex ( ws_mutex_t * mut )

Destroys the provided mutex.

Parameters

mut	mutex to be destroyed.

◆ ws_doPrintThreadID()

void ws_doPrintThreadID ( bool b )

Set print threadID, which prints the threadID of function calling ws_logger.

Defaults to on.

Parameters

b	True to turn on, false to turn off.

◆ ws_executeCommand()

ws_error_t ws_executeCommand ( char * commandBuf )

Execute a command with the provided buffer.

Parameters

commandBuf Buffer containing the command to execute, including any flags, parameters, etc.

Returns: Can return WS_OUT_OF_MEMORY if malloc returns NULL when DISABLE_MALLOC is not defined.

◆ ws_getAtomicBool()

bool ws_getAtomicBool ( ws_atomic_bool_t * ab )

Gets the value stored by the atomic bool.

Parameters

ab	Atomic bool object pointer.

Returns: False if bool does not exist, otherwise the value contained by the bool.

◆ ws_getCurrentColors()

ws_color_t ws_getCurrentColors ( )

Get the current console colors.

Returns: The ws_color_t of the current colors.

◆ ws_getDefaultColors()

ws_color_t ws_getDefaultColors ( )

Get the current default colors.

Returns: The ws_color_t of the default colors.

◆ ws_getThreadID()

ws_thread_id_t ws_getThreadID ( )

Gets the threadID of the calling thread.

Returns: ws_thread_id_t relating to the calling thread.

◆ ws_initializeDefaultStreams()

void ws_initializeDefaultStreams ( )

Initialize all streams to their defaults.

All default to their std-versions. (stdout, stderr, stdin)

◆ ws_lockMutex()

void ws_lockMutex ( ws_mutex_t * mut )

Locks the provided mutex.

Parameters

mut	Mutex to be locked.

◆ ws_logger()

void ws_logger	(	ws_logtype_t	type,
		const char *	format,
			...
	)

Logger function for WallShell.

Printf like formatting, automatically adds a newline.

Parameters

type	Type of logging.
format	Printf style formatting string.
...	Printf style formatting arguments.

◆ ws_moveCursor()

void ws_moveCursor ( ws_cursor_t direction )

Moves the cursor once in the provided direction.

Parameters

direction Direction to move, using ws_cursor_t.

◆ ws_moveCursor_n()

void ws_moveCursor_n	(	ws_cursor_t	direction,
		size_t	n
	)

Move the cursor n times in the provided direction.

Parameters

direction	Direction to move the cursor, using ws_cursor_t.
n	Amount of times to move in that direction.

◆ ws_printGeneralHelp()

void ws_printGeneralHelp ( ws_help_entry_general_t * entry )

help

Prints the general help entry.

Parameters

entry Entry to be displayed. If you don't want sections displayed, mark them as NULL in the struct.

◆ ws_printSpecificHelp()

void ws_printSpecificHelp ( ws_help_entry_specific_t * entry )

Prints the specific help entry.

Parameters

entry Entry to be displayed. If you don't want sections displayed, mark them as NULL in the struct.

◆ ws_promptUser()

bool ws_promptUser	(	const char *	format,
			...
	)

Prompts the user yes/no using the given prompt.

Parameters

format	Printf style formatting string.
...	Printf style arguments.

Returns: True if the user reply's yes, false otherwise. Will return false if the user enters anything other than something starting with 'Y' or 'y'.

◆ ws_registerCommand()

ws_error_t ws_registerCommand ( const ws_command_t c )

Register the command to the command handler.

Parameters

c	Command to be registered.

Returns: Can return WS_COMMAND_LIMIT_REACHED if DISABLE_MALLOC is defined, and WS_OUT_OF_MEMORY if not.

◆ ws_removeThreadName()

void ws_removeThreadName ( const char * name )

Removes the name of the provided thread.

Parameters

name	Name of the thread.

◆ ws_setAsciiDeleteAsBackspace()

void ws_setAsciiDeleteAsBackspace ( bool b )

Some consoles send backspace as ASCII delete (0x7f) instead of '\b'.

If your system does this, set this to true. This only needs to be done if CUSTOM_WS_SETUP is defined. For POSIX this is typically true, for Windows this is false.

Parameters

b	Bool to set backspace_as_ascii_delete to.

◆ ws_setAtomicBool()

void ws_setAtomicBool	(	ws_atomic_bool_t *	ab,
		bool	b
	)

Sets the value of the provided atomic bool.

Parameters

ab	Atomic bool object.
b	Value to set the bool to.

◆ ws_setBackgroundColor()

ws_error_t ws_setBackgroundColor ( ws_bg_color_t color )

Sets the background color to the provided color.

Parameters

color Color to set the background to.

Returns: Can return WS_OUT_STREAM_NOT_SET if the stream hasn't be initialized.

◆ ws_setBackgroundDefault()

void ws_setBackgroundDefault ( ws_bg_color_t c )

Set the default background color.

Parameters

c	Color to set the default to.

◆ ws_setConsoleColors()

ws_error_t ws_setConsoleColors ( ws_color_t colors )

Set the background and foreground colors to the provided ones.

Parameters

colors Colors to set the background and foreground to.

Returns: Can return WS_OUT_STREAM_NOT_SET if the stream hasn't be initialized.

◆ ws_setConsoleLocale()

void ws_setConsoleLocale ( )

Sets the console locale.

This is only required on Windows systems, as terminals default to ASCII.

The built in SET_TERMINAL_LOCALE sets the Windows terminal to UTF8. Can be potentially be used on unix systems to configure locale, although this isn't done by default. If the system you are implementing requires locale configuration, redefine SET_TERMINAL_LOCALE to the needed configuration.

◆ ws_setConsolePrefix()

void ws_setConsolePrefix ( const char * newPrefix )

Set the prefix to the provided one.

The prefix is what is displayed at the start of a command line. It is possible to use this function to imitate a bash like user@name:path$, or any other combination.

Parameters

newPrefix

◆ ws_setDefaultColors()

void ws_setDefaultColors ( ws_color_t c )

Set the default colors to the provided ones.

Parameters

c	Colors to set the defaults to.

◆ ws_setForegroundColor()

ws_error_t ws_setForegroundColor ( ws_fg_color_t color )

Sets the foreground color to the provided color.

Parameters

color Color to set the foreground to.

Returns: Can return WS_OUT_STREAM_NOT_SET if the stream hasn't be initialized.

◆ ws_setForegroundDefault()

void ws_setForegroundDefault ( ws_fg_color_t c )

Set the default foreground color.

Parameters

c	Color to set the default to.

◆ ws_setLoggerColors()

void ws_setLoggerColors	(	ws_logtype_t	type,
		ws_fg_color_t	fg,
		ws_bg_color_t	bg
	)

Set the logger colors for the specified log type.

Parameters

type	Type of logging.
fg	Foreground color.
bg	Background color.

◆ ws_setStream()

void ws_setStream	(	ws_stream	type,
		FILE *	stream
	)

Sets the stream to the provided one.

Parameters

type	Type of stream to change.
stream	Stream you wish to change it to.

◆ ws_setThreadName()

void ws_setThreadName ( char * name )

Sets the name of the calling thread.

This will only be printed if threadID is true.

Parameters

name	Name of the thread.

◆ ws_sleep()

void ws_sleep ( size_t ms )

Sleep function wrapper.

Parameters

ms	Sleep time in milliseconds.

◆ ws_stopTerminal()

void ws_stopTerminal ( )

Stops the currently running terminal.

Only supported in threaded applications.

◆ ws_terminalMain()

ws_error_t ws_terminalMain ( )

Main function for the terminal.

Call after any configuration.

Returns: Can return WS_OUT_OF_MEMORY if DISABLE_MALLOC is not defined, and malloc returns NULL.

◆ ws_unlockMutex()

void ws_unlockMutex ( ws_mutex_t * mut )

Unlocks the provided mutex.

Parameters

mut	Mutex to be unlocked.

◆ ws_vlogger()

void ws_vlogger	(	ws_logtype_t	type,
		const char *	format,
		va_list	args
	)

Logger function for WallShell.

vprintf like formatting, automatically adds a newline.

Parameters

type	Type of logging.
format	printf style formatting string.
args	va_list of arguments.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ws_mutex_t

◆ ws_thread_id_t

Enumeration Type Documentation

◆ ws_bg_color_t

◆ ws_cursor_t

◆ ws_error_t

◆ ws_fg_color_t

◆ ws_logtype_t

◆ ws_stream

Function Documentation

◆ ws_cleanAll()

◆ ws_compareCommands()

◆ ws_createAtomicBool()

◆ ws_createMutex()

◆ ws_deregisterCommand()

◆ ws_destroyAtomicBool()

◆ ws_destroyMutex()

◆ ws_doPrintThreadID()

◆ ws_executeCommand()

◆ ws_getAtomicBool()

◆ ws_getCurrentColors()

◆ ws_getDefaultColors()

◆ ws_getThreadID()

◆ ws_initializeDefaultStreams()

◆ ws_lockMutex()

◆ ws_logger()

◆ ws_moveCursor()

◆ ws_moveCursor_n()

◆ ws_printGeneralHelp()

◆ ws_printSpecificHelp()

◆ ws_promptUser()

◆ ws_registerCommand()

◆ ws_removeThreadName()

◆ ws_setAsciiDeleteAsBackspace()

◆ ws_setAtomicBool()

◆ ws_setBackgroundColor()

◆ ws_setBackgroundDefault()

◆ ws_setConsoleColors()

◆ ws_setConsoleLocale()

◆ ws_setConsolePrefix()

◆ ws_setDefaultColors()

◆ ws_setForegroundColor()

◆ ws_setForegroundDefault()

◆ ws_setLoggerColors()

◆ ws_setStream()

◆ ws_setThreadName()

◆ ws_sleep()

◆ ws_stopTerminal()

◆ ws_terminalMain()

◆ ws_unlockMutex()

◆ ws_vlogger()