GDHLs is a generic set of data handling libraries, as the title might suggest. These libraries (put into one) is basically a set of functions and functionalities that I have created to solve problems that I though might be difficult and or time consuming to work with otherwise, yet useful in many occasions. This includes directory searching/listing/manipulation, error handling (something a bit more lightweight than throw/catch as is standard, but with similar effectiveness), and anything else that seems like it might be useful.
My next goal will be adding the function timings to the documentation of CLI. Although this library will only have a few calls when it is used, at the beginning of execution before anything time-sensitive, such informatiis still good to have. As this is a documentation update, there will be no version update when it is released.
The following stage will be finishing the conversions section (code & docs). This will be version 0.0.2.x.
At some indeterminant time, I will release a version 1.0.1.x (the first stable version), after I am confident there are no big bugs in the CLI library.
Like most code, to make things easier, naming conventions are used in the source of this project. These conventions help make the names of the things that are uesd easier to remember. The following is a list of the conventions, in the example two names will be given as demonstraition "name" and "multiword name".
| type | convention | samples |
| defined constant | This is a constant defined with "#define", it is converted to all caps, and words are separated by underscores. |
GDHLS_NAME GDHLS_MULTIWORD_NAME |
| function | This is function of standard type (return_type function_name(args). The words are separated by underscores, and the names are all lower case. These are prepended with "gdhls_". |
GDHLS_name GDHLS_multiword_name |
| function type | This is a function type (i.e. a typedef for a function listing the return type and args). This is in the form of no word separaters, and first letters capitolized in each word. |
GDHLS_Name GDHLS_MultiwordName |
| struct | This is a structure (i.e. the direct name, or the typedef so "struct" doesn't have to be used to declare an object of the type). THis is in the format of all caps, no spaces between words. |
GDHLS_NAME GDHLS_MULTIWORDNAME |
| variable, global | This is the name of a global variable. Globals will be prefixed with gdhls_, otherwise, just use all lowercase, words separated by underscores. |
GDHLS_name GDHLS_multiword_name |
| variable, internal | This is the name of an internal function or struct variable. Globals will be prefixed with gdhls_, otherwise, just use all lowercase, words separated by underscores. |
name multiword_name |
Additionally this library is "versioned" in a manner different from most other libraries, there are 4 version numbers instead of 2 or 3. I.E. it is in the form of: #.#.#.#. These numbers, are in order, the code number, binary number, feature number, and revision number. This may seem confusing at first, however, with it, a lot of compatability information can be determined and obtained.
Code number: The first relevant number is the code number. This is updated in two cases: when going from testing to stable, and when code compatability is broken. This effectively determines source-code compatability. If the code number is odd, it is a release version, if even, it is a test version. Zero (0), counts as even. Take the test version, add "1", and you have the release version (i.e. if you are looking at version 2.5.9.26, then 3.5.9.26 would be the release version with the same feature set). THIS MEANS THAT THERE WILL ALWAYS BE AT LEAST TWO VERSIONS BEING DISTRIBUTED AT ONE TIME! There will be the release version and the test version, the former is stable, and the latter is where test features will be added. The most important part of this: when using a library, you can check the feature and/or revision number, and if either (a) the feature number of the library is greater than the feature number you wrote it with, or (b) the feature number of the library is the same as the feature number you wrote with and the revision number is greater than or equal to the revision number you wrote it with, then, assuming that the code number is the same, the libraries will be "code compatable": you can recompile the code on either library. Additionally, with shared libraries, as long as you use function access only with any of the libraries data structures, you're code should work with any shared library fitting the same criteria. Lastly, if you go from an even (test) code number to the next odd code number (stable), with all of the other version numbers the same, then you are guranteed source and binary compatability. Additionally, if the program is written for an odd (stable) code number, and is run against the next lowest (even) code number, then the remaining numbers can be looked at as if both were stable for code and binary compatability. Outside of these two cases, all bets are off.
Binary number: This is the number indicating the binary version. This is updated every time binary compatability is broken. If it is the same, as long as the library you are using has the same feature "groups" implemented (see feature number), and all the appropriate functions that you call for said groups, then you will be fine. Direct structure access is also not broken.
Feature number: Each feature will have a number, as long as the feature number is greater than or equal to the feature number for the desired "feature", then it will have the basic functionality for that feature. Additionally, a feature may be expanded at higher feature numbers, if that is the case, then any feature number high than any in which the feature was expanded will also have the expanded parts of the feature. The features and their numbers: (1) cli, (2) conversions, (3) dirtree, (4) file_to_c, (5) v_node, (6) v_list, (7) error_queue, (8) v_array, (9) v_tree.
Revision number: This is updated for each release of the library - it indicates new features peices, or bugfixes
Lastly, there is the feature listings. Several times, there will be multiple ways to achieve a goal, depending on personal preference and style. When two ore more functions are listed that do similar thigns, and one is "preferreable" to another (example, one is omega(log(n)) and the other is omega(n) in terms of speed), then the preferred option will be highlighted in green, and the less preferred option will be highlighted in red. Next, some functions are absolutely required for effective use of the library, those will be noted in white. Lastly, there are some functions that are used internally in the libraries, but shouldn't be needed/called by the user, they are documented for completeness, and for users who may find a need of them. Information will be given in alphabetic order, except for the things not needed by programmers, which will be at the end of any given section.
| preferred | not preferred | required | not required for users |
This software is created and distributed under the BSD software Licence:
Copyright (c) 2004-2007, S James S Stapleton
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
(c) Copyright 2007, S James S Stapleton