@c "stdchpfn.texi"

@node Standard Library Functions
@chapter Standard Library Functions
@cindex library
@cindex functions
@cindex standard library

This section describes the usage of existing library functions.
These library functions can be loaded by dlopening @file{stdchpfn.la},
which is located in @file{@i{pkglibdir}} (like @file{prefix/lib/hackt}).

To load the standard library:
@example
$ @kbd{hacchpsim -Lprefix/lib/hackt -lstdchpfn foo.obj}
@end example

@cindex LDFLAGS
@cindex hackt-config
To help with passing the correct library flags, you can also invoke
@samp{hackt-config --ldflags} to automatically expand the flags:

@example
$ @kbd{hacchpsim `hackt-config --ldflags` -lstdchpfn foo.obj}
@end example

@menu
* Function Descriptions:: list of functions
* Library Use Example:: example using standard library
* Function Renaming:: customization and remapping
* Library Organization:: file organization
@end menu

@c ----------------------------------------------------------------------------
@node Function Descriptions
@section Function Descriptions
@cindex library functions

This section gives brief usage descriptions of all functions 
available from the standard @command{chpsim} library.  

@menu
* Diagnostics Library::
* Conditionals Library::
* String Library::
* I/O Library::
* OS Library::
* Bitmanip Library::
@end menu

@node Diagnostics Library
@subsection Diagnostics

@include fn/assert.texi

@node Conditionals Library
@subsection Conditionals

@include fn/bcond.texi
@include fn/zcond.texi
@include fn/rcond.texi
@include fn/select.texi

@node String Library
@subsection Strings

@include fn/strcat.texi
@include fn/strtoz.texi
@include fn/strtob.texi
@include fn/strtor.texi

@node I/O Library
@subsection Input/Output

The first group of functions operate on @file{stdin} and @file{stdout}
for interactiion with the user.  
The @t{scan} input functions with throw a run-time exception 
upon conversion failure.  

@include fn/echo.texi
@include fn/printerr.texi
@include fn/zscan.texi
@include fn/zscan_prompt.texi
@include fn/bzscan.texi
@include fn/bzscan_prompt.texi
@include fn/xzscan.texi
@include fn/xzscan_prompt.texi
@include fn/bscan.texi
@include fn/bscan_prompt.texi
@include fn/sscan.texi
@include fn/sscan_prompt.texi

@strong{TODO:} @t{rscan} is not yet available, but is trivial to add.

I/O can also operate on file streams.  

@include fn/fopen.texi
@include fn/fappend.texi
@include fn/fprint.texi
@include fn/fclose.texi
@include fn/fflush.texi
@include fn/fzscan.texi
@include fn/fbzscan.texi
@include fn/fxzscan.texi
@include fn/fbscan.texi
@include fn/fsscan.texi

The following variants automatically restart a file stream 
once it reaches the end.

@include fn/fzscan_loop.texi
@include fn/fbzscan_loop.texi
@include fn/fxzscan_loop.texi
@include fn/fbscan_loop.texi
@include fn/fsscan_loop.texi

@node OS Library
@subsection Operating System Library

System-related operations are also supported.

@include fn/system.texi

@node Bitmanip Library
@subsection Bit-manipulation Library

The following functions are provided as fast implementations of
low-level bitwise manipulation functions.  

@include fn/parity.texi
@include fn/popcount.texi
@include fn/clz32.texi
@include fn/ctz.texi
@include fn/ffs.texi
@include fn/msb.texi
@include fn/lsb.texi

@c ----------------------------------------------------------------------------
@node Library Use Example
@section Library Use Example
@cindex library example

An example project that uses some standard library functions is installed
under @file{@i{pkgdatadir}/doc/examples/chpsim-stdlib/}.

@c ----------------------------------------------------------------------------
@node Function Renaming
@section Function Renaming
@cindex renaming library functions

This section describes ways in which one can customize the standard library.
Perhaps you don't like the names chosen, or you would like to remap
selected functions to your own versions.

The source file for @file{stdchpfn.la} is also installed
as @file{stdchpfn.cc} in the same location (@t{pkglibdir}).
It merely contains function registration macros that map
functions defined in @file{libstdchpfn.la} to names used in @command{chpsim}.
One can use this file as a starting point for remapping 
to functions to different names, or names to different functions.  
To re-use the existing underlying functions, just link your new
library against @samp{-L@i{pkglibdir} -lstdchpfn}
(in @var{LIBADD}, by Libtool/Automake convention),
which resolves to @file{libstdchpfn.la}, 
not the dlopenable module, @file{stdchpfn.la}.  

@c ----------------------------------------------------------------------------
@node Library Organization
@section Library Organization
@cindex library organization

The intentional separation between 
@file{libstdchpfn.la} and @file{stdchpfn.la}
demonstrates how one can build a @command{chpsim} module
on top of an existing C or C++ library without modifying it.  

@cindex library dependencies
@cindex dependent libraries
Q: When passing a module to @command{chpsim} with @option{-l} or dlopen, 
how does the system know what dependent libraries to load?
A: The @file{.la} Libtool archives encode library dependencies
for shared libraries, and (Libtool) libltdl's lt_dlopen automatically
takes care of dependent libraries for the user.  

