-The following are a collection of informal notes on getting this to compile and run under Windows using Cygwin.
-I may formalize this at a later point in time.
+# fss-0002
-I have tested and was able to successfully (statically) compile and run FLL+Byte Dump under Cygwin.
-The resulting binary could be transfered to another machine and runs if the cygwin.dll is copied with it (placed along the byte_dump.exe).
+Cygwin:
+ The following are a collection of informal notes on getting this to compile and run under Windows using Cygwin.
+ I may formalize this at a later point in time.
-To compile the FLL, some functionality needs to be disabled.
-Fortunately, FLL is specifically designed to be hackable so the process is easier that it might otherwise be.
+ I have tested and was able to successfully (statically) compile and run FLL+Byte Dump under Cygwin.
+ The resulting binary could be transfered to another machine and runs if the cygwin.dll is copied with it (placed along the byte_dump.exe).
-For a monolithic build, compiled statically, add the following to "defines" in the "data/build/settings" file (of the packaged source).
- "-D_di_libcap_ -D_pthread_attr_unsupported_ -D_pthread_sigqueue_unsupported_ -D_di_f_attribute_visibility_ -Df_attribute_visibility_hidden -Df_attribute_visibility_internal -Df_attribute_visibility_protected -Df_attribute_visibility_public"
+ To compile the FLL, some functionality needs to be disabled.
+ Fortunately, FLL is specifically designed to be hackable so the process is easier that it might otherwise be.
-Before packaging "data/build/settings", the build settings files are either found inside the individual projects or under the build directory at the root of the source repository.
+ For a monolithic build, compiled statically, add the following to "defines" in the "data/build/settings" file (of the packaged source).
+ "-D_di_libcap_ -D_pthread_attr_unsupported_ -D_pthread_sigqueue_unsupported_ -D_di_f_attribute_visibility_ -Df_attribute_visibility_hidden -Df_attribute_visibility_internal -Df_attribute_visibility_protected -Df_attribute_visibility_public"
-The file level_1/fl_control_group/c/control_group.c (for function fl_control_group_apply()) had to have the following changed from:
- if (unshare(CLONE_NEWCGROUP) < 0) {
- if (errno == EINVAL) return F_status_set_error(F_parameter);
- if (errno == ENOMEM) return F_status_set_error(F_memory_not);
- if (errno == ENOSPC) return F_status_set_error(F_space_not);
- if (errno == EPERM) return F_status_set_error(F_prohibited);
+ Before packaging "data/build/settings", the build settings files are either found inside the individual projects or under the build directory at the root of the source repository.
- return F_status_set_error(F_failure);
- }
-to:
- return F_status_set_error(F_supported_not);
+ The file level_1/fl_control_group/c/control_group.c (for function fl_control_group_apply()) had to have the following changed from:
+ if (unshare(CLONE_NEWCGROUP) < 0) {
+ if (errno == EINVAL) return F_status_set_error(F_parameter);
+ if (errno == ENOMEM) return F_status_set_error(F_memory_not);
+ if (errno == ENOSPC) return F_status_set_error(F_space_not);
+ if (errno == EPERM) return F_status_set_error(F_prohibited);
-There may have been other things to disable that I forgot to document.
+ return F_status_set_error(F_failure);
+ }
+ to:
+ return F_status_set_error(F_supported_not);
-I do not believe I had to make any changes to compile byte_dump.
+ There may have been other things to disable that I forgot to document.
-Compiling byte_dump statically against the FLL library is a bit inefficient in that it contains the entire FLL library.
-The byte_dump program only needs a portion of it.
-I may need to provide a list of everything that can be disabled to provide a smaller and more optimal byte_dump binary.
+ I do not believe I had to make any changes to compile byte_dump.
+
+ Compiling byte_dump statically against the FLL library is a bit inefficient in that it contains the entire FLL library.
+ The byte_dump program only needs a portion of it.
+ I may need to provide a list of everything that can be disabled to provide a smaller and more optimal byte_dump binary.
-One of the objectives of this project is to make as much, if not all, of the functions available for use.
+# fss-0002
-Another of the objectives is to design each function to operate in isolation to another function.
-There is some flexibility in regards to this when it comes to individual projects.
+Private Functions:
+ One of the objectives of this project is to make as much, if not all, of the functions available for use.
-Such a design has advantages and disadvantages.
+ Another of the objectives is to design each function to operate in isolation to another function.
+ There is some flexibility in regards to this when it comes to individual projects.
-One of those disadvantages is possible redundant code.
-The c-programming language does not have private functions by any normal means.
-The use of the f_gcc_attribute_visibility_internal helps simulate private functions.
-Such functionality only works in supporting GCC compilers.
+ Such a design has advantages and disadvantages.
-These synthetic private functions are implemented as an exception to the objectives for maintainability and redundancy purposes.
-Such implementations should be kept to a bare minimum.
+ One of those disadvantages is possible redundant code.
+ The c-programming language does not have private functions by any normal means.
+ The use of the f_gcc_attribute_visibility_internal helps simulate private functions.
+ Such functionality only works in supporting GCC compilers.
-Functions defined as private will not be normally exposed through the public headers files.
-Such functions will be prefixed with 'private_'.
+ These synthetic private functions are implemented as an exception to the objectives for maintainability and redundancy purposes.
+ Such implementations should be kept to a bare minimum.
-The header files and source files for these private functions will be prefixed with "private-".
-Normally, this product uses underscores for names, but, as a special name, the dash "-" is used.
-Normally, the names begin with the project name (such as directory_type.h instead of type_directory.h), but as a special case to further separate private files, this is prefixed onto source files (such as private-directory.h).
+ Functions defined as private will not be normally exposed through the public headers files.
+ Such functions will be prefixed with 'private_'.
+
+ The header files and source files for these private functions will be prefixed with "private-".
+ Normally, this product uses underscores for names, but, as a special name, the dash "-" is used.
+ Normally, the names begin with the project name (such as directory_type.h instead of type_directory.h), but as a special case to further separate private files, this is prefixed onto source files (such as private-directory.h).
-# fss-002
+# fss-0002
#
# This readme file is inteded to provide a basic introduction to the Featureless Linux Library (FLL).
#
The bootstrap compiling provides a way to build and compile the entire FLL project, without the Featureless Make (Fake) program.
This bootstrap process solves the problem where if you don't already have Fake installed, then you cannot install Fake.
+ These bootstrap scripts are written in GNU Bash.
The source code needs to be packaged before it can be compiled by either the bootstrap scripts or by the Fake program.
- The Fake program is not intended to be used as an installer, so the bootstrap scripts also provide an install script.
+ The Fake program is neither intended nor designed to be used as an installer, so the bootstrap scripts also provide an install script written in GNU Bash.
This install script is intended to be used only by the FLL.
Future versions of the FLL may include an install equivalent to the Fake program (and there may possibly be a package generation equivalent as well).
The bootstrap-example.sh script is intended to be a functional example of the command line arguments that should be used to generate, compile, and install the entire FLL.
- The install.sh script is intended to install the built and compiled FLL code onto the system.
- This script very loosely follows a small amount of the logic of configure scripts.
+ The install.sh script is intended to install the built and compiled FLL code onto the system.
+ This script very loosely follows a small amount of the logic of the standard configure scripts.
The package.sh script is intended to convert the FLL source code from the source code repository structure into a packaged or release.
Of particular note is that there are multiple ways to package the FLL, such as each package as its own individual project, each package by level, or each package as a monolithic library.
This script also provides management functions for ensuring the dependencies and configuration settings are accurate.
+
+Other Readmes:
+ Repository providers like Github and Gitlab utilize README.md, LICENSE, and other special files at the root project level.
+ This practice is not supported by the FLL project structure and is not normally used.
+
+ Instead, these are provided only on special branches intended exclusively to be used for the appropriate repository provider.
+ These readmes and related files are intended to document the project within the scope of the repository provider and usually a particular release version.
Any function must therefore support returning F_implemented_not.
There are some projects that can be enabled/disabled such as f_capability and f_threads.
- These may explicitly document returning F_implemented_not.
+ These should explicitly document returning F_implemented_not.
Common Return Types for f_status_t:
There are some f_status_t return types that are not required to be returned but are used quite often that they might seem required.
--- /dev/null
+# fss-0002
+
+Style Guide:
+ The Featureless Linux Library uses a set of styles and practices designed in hopes to communicate both explicitly and implicitly multiple meanings and contexts.
+ The idea is that code should be readable like a story rather than be a mash of characters jumbled together into as few lines as possible.
+ This design has a tendency to go against the norm given that longer lines (such as 120 characters or more) may be common.
+
+ There are general style guides used in everything and there are more specific and context-explicit styles used in special cases.
+
+General Style Guides:
+ - Naming Structure.
+ - Commas in Sets.
+
+Specific Style Guides:
+ - Return Code Names.
+ - Global String Constant Names.
+ - Enumeration Names.
+ - Define Names.
+ - Type Definition names.
+ - Function Names.
+ - File Names.
+
+Naming Structure:
+ All files, programs, functions, and comments that have specific meaning follow this general naming structure.
+ This structure may be similar to camel-casing or snake-casing, but it is not nor is it intended to match them.
+
+ These special names may only contain word characters, underscore "_", and dash "-".
+
+ The underscore "_" and dash "-" are explicitly intended to communicate separation of context or not.
+ The underscore character represents a space separating multiple words, logic, concepts, or ideas represented by the previous words and should share meaning.
+ The dash character represents a break in the words, logic, concepts, or ideas.
+
+ Limitations in the software may restrict the use of these and the following also apply\:
+ - In the event that a dash cannot be used, fall back to an underscore.
+ - In the event that an underscore cannot be used, fall back to a dash.
+ - In the event that both underscore and dash cannot be used, it is fine to have neither.
+ - For software that uses plus "+", it may become necessary to replace the dash with the plus, but this should be avoided.
+ - Other language-specific (compiler languages, spoken languages, written languages, etc..) restrictions may apply that prevent or alter this style.
+
+ In general, these special names should always be lower case and this is encouraged.
+ The use of upper case is not forbidden and is encouraged to be used for special communication or language-specific purposes.
+
+ Consider the following to better understand how and when to use the underscore and dash to implicitly communicate context\:
+ Take the words "my", "red", "cat", "dog", and "apple".
+
+ If you wanted to communicate that the structure of a document is focused on "my red X", then you can use the following naming structure to communicate this\:
+ 1) my_red-cat, my_red-dog, my_red-apple.
+
+ If you wanted, instead, to communicate that the structure is focused on "my X", then you can use the following naming structure to communicate this\:
+ 2) my-red_cat, my-red_dog, my-red_apple.
+
+ By following this logic, another person can more easily identify your logic and make changes or fixes.
+ Let us say that somebody wants to add "happy" to the context\:
+
+ 1) This can become: my_red-happy_cat, my_red-happy_dog, my_red-apple.
+ 2) This can become: my-happy_cat, my-happy_dog, my-red_apple.
+
+ The person who added "happy" might have fixed a situation where there is no red cat or dog and while understanding that there is no happy apple.
+ However, in case (1) because "my_red" is grouped together by the underscore, it is clear that there is a "my_red" must be preserved and there is red cat and red dog, so happy is added to the cat and dog but not the apple without removing the "red".
+
+Commas in Sets:
+ In english, the more grammatically correct way to write lists is to have commas except for the last item in the set.
+ This makes hacking and patching more difficult, even if only slightly.
+
+ This project requires that, so long as it is allowed by the language (in terms of valid syntax, etc..), items in a list must always end in a comma.
+
+ Example Grammatically Correct Way\:
+ - char list[] = {
+ 'a',
+ 'b',
+ 'c'
+ };
+
+ Example FLL Correct Way\:
+ - char list[] = {
+ 'a',
+ 'b',
+ 'c',
+ };
+
+Return Code Names:
+ The return code names are C-language specific names used by this project as the status or return codes for functions and programs.
+ To uniquely identify these, they follow the naming structure "(A)_(b)", where "(A)" is replaced with an upper-case character representing the project level (or name) and "(b)" is replaced with the lower-case status code name using words that are underscore separated.
+
+ These are enumerations but they do not follow the enumeration style guide and are an exception to it.
+
+ Examples\:
+ - F_none
+ - F_signal_file_size_limit
+
+Global String Constant Names:
+ The C-language specific global names are used in two ways\:
+ 1) Via a define (macro).
+ 2) As a variable at the global scope.
+
+ When used as a define, these follow the naming structure "(A)_(b)_s" or "(a)_(b)_s", where "(A)" is replaced with an upper-case character representing the project level, "(a)" is a lower-case alternative of "(A)" and "(b)" is replaced with the lower-case name using words that are underscore separated.
+
+ When used as a variable these follow the naming structure "(a)_(b)_s", where "(a)" is replaced with an lower-case character representing the project level (or name) and "(b)" is replaced with the lower-case name using words that are underscore separated.
+
+ The trailing "_s" designates that this is a string.
+
+ In general, the defines are always using the upper-case variant and the variable are always using the lower-case.
+ This separation allows for a define and a variable to both exist simultaneously without naming conflict.
+ This is used extensively to define strings in this practice such that a define exists while a variable is provided.
+
+ A special case define that describes the length of the string is of the forms: (A)_(b)_s_length or "(a)_(b)_s_length".
+
+ Examples\:
+ - F_file_open_mode_truncate_s: as a define, such as: #define F_file_open_mode_truncate_s "w".
+ - f_file_open_mode_truncate_s: as a variable, such as: extern const f_string_t f_file_open_mode_truncate_s;.
+ - FAKE_build_setting_name_build_compiler_s: as a define.
+ - fake_build_setting_name_build_compiler_s: as a variable.
+ - fake_build_setting_name_build_compiler_s_length: for describing the length of the string represented by fake_build_setting_name_build_compiler_s.
+
+Enumeration Names:
+ The C-language specific enumeration names follow the naming structure "(b)_e", where "(b)" is replaced with the lower-case name using words that are underscore separated.
+
+ The trailing "_e" designates that this is an enumeration.
+
+ Examples\:
+ - f_console_verbosity_quiet_e
+ - f_fss_basic_e
+ - fss_extended_list_read_parameter_at_e
+
+Define Names:
+ The C-language specific define names (also known as macro names) follow the naming structure "(A)_(b)_d", where "(A)" is replaced with an upper-case character representing the project level and "(b)" is replaced with the lower-case name using words that are underscore separated.
+
+ The trailing "_d" designates that this is a define (a macro).
+
+ Examples\:
+ - F_file_mode_special_sticky_d
+ - F_attribute_visibility_internal_d
+ - FL_diectory_recurse_depth_max_d
+
+Type Definition names:
+ The C-language specific type definition names follow the naming structure "(a)_(b)_t", where "(a)" is replaced with an lower-case character representing the project level and "(b)" is replaced with the lower-case name using words that are underscore separated.
+
+ The trailing "_t" designates that this is a type definition.
+
+ In addition to the type definition, special defines (macros) are provided that are specific to type definitions are an exception to the Define Names rules.
+ - Each type definition should have an initializer and that initializer name follows the naming structure "(a)_(b)_t_initialize" where "_initialize" is appended to the type definition name.
+
+ - Each type definition may have special defines (macros) used as functions for helping with special operations such as complex initialization, allocation, and deallocation.
+ These special case defines are an exception to the Define Name rules and follow the naming structure "macro_(a)_(b)_t_(c)" where "macro_" is prepended to the type definition name and the (c) is just like (b) but is used to communicate the special purpose.
+
+ Examples\:
+ - f_string_static_t
+ - f_status_t
+ - macro_f_account_t_clear
+ - macro_f_string_dynamic_t_resize
+
+Function Names:
+ The C-language specific function names follow the naming structure "(a)_(b)" or "private_(a)_(b)", where "(a)" is replaced with an lower-case character representing the project level (or name) and "(b)" is replaced with the lower-case name using words that are underscore separated.
+
+ The leading "private_" is used to designate that this is a private function.
+
+ In addition, special practices are followed.
+ - For FLL projects, each project has a level.
+ Each project within some level is prepended to functions with their level representation characters of: "F" (level 0), "FL" (level 1), and "FLL" (level 2).
+
+ - For programs, each program has a project name.
+ The program name, or a short alias of the program name, is prepended to functions.
+
+ - For programs, the "main" function does not do this and is always called "main" without modification.
+
+ Examples\:
+ - f_fss_basic_e
+ - fl_conversion_string_to_binary_signed
+ - fake_print_help
+
+File Names:
+ The C-language specific file names follow the naming structure "(c-)(b)(-c)" where "(b)" is replaced with the lower-case name using words that are underscore separated and "(c-)" and "(-c)" are just like "(b)" except there may be any number of these (or none at all) and the dash "-" is used to separate context as per the General Naming Structure.
+
+ In addition, special practices are followed:
+ - private-(c-)(b)(-c): "private-" is prepended to all source and header files intended to be private (aka: not intended to be exposed via the API or ABI).
+
+ - (c-)(b)(-c)-common: "-common" is appended to all files used as a common include for standard practice data such as global strings, define strings, type definitions, and memory allocation or deallocation functions.
-# fss-002
+# fss-0002
Threads Documentation:
With the inclusion of the f_thread project, the Featureless Linux Library supports and uses threads by default.
Therefore, avoid using any design or functions that may force or require the use of pthread_testcancel() but when forced to be very careful to clear up resources and locks to make sure that if a cancellation occurs that nothing bad can happen.
A better approach would be to use timed checks on some variable shared between all affected functions and scopes that designates cancellation.
That way when a cancellation is reseived through the custom variable, the functions can actually handle the situation, safely and properly, before cancelling.
+
+C/C++ Standard:
+ Newer C/C++ standards provide thread support.
+ This is ideally much better than POSIX in that it will be more portable.
+ At this time, most C/C++ compilers do not implement this thread support.
-This file contains FLL-wide todo notes.
+# fss-0002
-- Custom language support needs to be looked into to allow for the project to support multiple languages.
- Given that this project focuses on KISS principles, the project is targeted towards programs for specific users.
- In which case, the language can be hardcoded in as a single language.
- Later versions after this first locale support will then consider supporting multiple languages not necessarily compiled in.
+FLL-wide To Do Notes:
+ - Research/Implement optimizaton by using pointers to reduce the complexity of processing multi-depth structures, such as fss_nest:
+ this:
+ nests->array[nests->used].array[index].array[0] = xxx;
+ could become:
+ *current = nests->array[nests->used].array[index].array;
+ current->array[0] = xxx;
+ The idea is that in the first case, thee is a lot more dereferencing needing to be performed whereas the second case, the massive dereferencing happens only the first time and then all subsequent calls have simpler dereferencing.
-- consider updating byte_dump to support multiple --first and multiple parameters such all --first parameters are effectively added together.
- What this does is allow skipping a file using counters greater than the max_int size.
- The --last position, should therefore be rewritten to be relative to the --first position.
- alternatively, implement a --skip parameter that skips past the max_int number of bytes X number of times (--skip X) would skip X*max_int bytes.
- alternatively, implement support for specifying metric unit symbols (such as 100m for 100 megabytes).
+ * Programs to create:
+ * - document: the documentation is built/processed/generated.
+ * - finish: the project is installed.
+ * - coverage: the project has tests run against it.
-- Research/Implement optimizaton by using pointers to reduce the complexity of processing multi-depth structures, such as fss_nest:
- this:
- nests->array[nests->used].array[index].array[0] = xxx;
- could become:
- *current = nests->array[nests->used].array[index].array;
- current->array[0] = xxx;
- The idea is that in the first case, thee is a lot more dereferencing needing to be performed whereas the second case, the massive dereferencing happens only the first time and then all subsequent calls have simpler dereferencing.
+ - F_STATUS_XX could be the error code for the program on exit, such that +s, ++status is a new standard parameter for specifying the variable name.
+ Variable name will be made uppercase and will be only alphabetic or underscore.
- * Programs to create:
- * - document: the documentation is built/processed/generated.
- * - finish: the project is installed.
- * - coverage: the project has tests run against it.
+ Go back through all existing f_file and f_directory code, updating return codes and respective documentation.
+ Update f_utf_file and create a f_utf_directory?
-- F_STATUS_XX could be the error code for the program on exit, such that +s, ++status is a new standard parameter for specifying the variable name.
- Variable name will be made uppercase and will be only alphabetic or underscore.
-
-Go back through all existing f_file and f_directory code, updating return codes and respective documentation.
-Update f_utf_file and create a f_utf_directory?
-
-The f_conversion project:
-- needs to have its parameter orders corrected.
-- needs to follow the private-conversion.? design.
-
-fix recursive functions to be consistent and all have max recursion lengths just like the *_all() file functions.
+ Fix recursive functions to be consistent and all have max recursion lengths just like the *_all() file functions.
Featureless Settings Specification: 0000 - Basic:
Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as part of the object.
Whitespace separates an Object from the Content.
- An Object may be followed by a newline, in which case means that the Object has no Content.
+ An Object may be preceded by a newline, in which case means that the Object has no Content.
+ If only printing whitespace follows a valid Object, that Object is considered to have no Content.
Content exists on the same line as the Object.
Content is represented as a single Content column terminated by a newline.
Content column consists of everything following the first non-whitespace character until the newline.
Content column includes trailing whitespace before newline is reached.
Content column does not include any of the leading whitespace.
- No delimits are supported in the content.
-
- If only printing whitespace follows a valid Object, that Object is considered to have no Content.
+ No delimits are supported in the Content.
Key\:
\s = whitespace, except newline.
* = zero or more occurrences.
+ = one or more occurrences.
+ Before Structure\:
+
Structure\:
\s*\q+\s+\b*\n
+ After Structure\:
+
Example\:
# fss-0000
# valid comments are ignored.
Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object.
Whitespace separates an Object from the Content.
An Object may be followed by a newline, in which case means that the Object has no Content.
+ If only printing whitespace follows a valid Object, that Object is considered to have no Content.
Content exists on the same line as the Object.
Content is represented as multiple Content columns.
+ = one or more occurrences.
()* = grouping that repeats 0 or more times.
+ Before Structure\:
+
Structure\:
\s*\q+\s+(\s*\q+)*\s*\n
+ After Structure\:
+
Example\:
# fss-0001
# valid comments are ignored.
1.1) Content
1.2) content 2
1.3) content_3.
+
2.1) object
2.2) set.
# fss-0002
#
-# Note: this file is in fss-0002 format and as a result the example below has to be escaped (can potentially be confusing when reading this raw).
+# Note: This file is in fss-0002 format and as a result the example below has to be escaped (can potentially be confusing when reading this raw).
+# The "This Does\\\:" below is actually "This Does\:" when processed by fss-0002.
Featureless Settings Specification: 0002 - Basic List:
Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object.
Non-whitespace may not follow the colon of a valid Object.
Content is represented as a single Content column of every line following a valid object until the end of file (or string) or until the next valid Object is found.
- Any content that could be interpreted as a valid Object must have the colon delimited.
+ Any Content that could be interpreted as a valid Object must have the colon delimited.
There is no single-quote or double-quote delimitation in this specification.
Only the colon that would result in a valid Object can be delimited.
\n = newline.
* = 0 or more occurrences.
+ Before Structure\:
+
Structure\:
\s*\o\l*:\s*\n\c*\n*
+ After Structure\:
+
Example\:
# fss-0002
# valid comments are ignored.
This Does\\\:
Second\:
Continues until EOS/EOF.
- All whitespace, including newline (and leading whitespace) is part of content.
+ All whitespace, including newline (and leading whitespace) is "part of content."
# Valid comments are still ignored.
Objects would be\:
2) Second
Contents would be\:
- 1.1) Does not need to be quoted.
- This: does not need to be delimited.
- This Does\:
- 2.1) Continues until EOS/EOF.
- All whitespace, including newline (and leading whitespace) is part of content.
+ 1.1) Does not need to be quoted.
+ This: does not need to be delimited.
+ This Does\:
+ 2.1) Continues until EOS/EOF.
+ All whitespace, including newline (and leading whitespace) is "part of content."
Non-whitespace may not follow the open-brace of a valid Object.
Content is represented as a single Content column of every line following a valid object until the end of file (or string) or until a non-delimited close-brace (}).
- Any Content column that could be interpreted as an end of content must be delimited if it should be part of the Content.
+ Any Content column that could be interpreted as an end of Content must be delimited if it should be part of the Content.
Whitespace may follow a valid close-brace but a terminating newline must be present to designate a valid end of Content.
There is no single-quote or double-quote delimitation in this specification.
\n = newline.
* = 0 or more occurrences.
+ Before Structure\:
+
Structure\:
\s*\o\l*{\s*\n\c*\n\s*}\s*\n
+ After Structure\:
+
Example\:
# fss-0003
# valid comments are ignored.
This: does not need to be delimited.
\}
}
+
Second {
Continues until EOS/EOF.
- All whitespace, including newline (and leading whitespace) is part of content.
+ All whitespace, including newline (and leading whitespace) is "part of content."
# Valid comments are still ignored.
}
2) Second
Contents would be\:
- 1.1) Does not need to be quoted.
- This: does not need to be delimited.
- }
- 2.1) Continues until EOS/EOF.
- All whitespace, including newline (and leading whitespace) is part of content.
+ 1.1) Does not need to be quoted.
+ This: does not need to be delimited.
+ }
+ 2.1) Continues until EOS/EOF.
+ All whitespace, including newline (and leading whitespace) is "part of content."
Featureless Settings Specification: 0004 - Very Basic List:
This is a fss-0002 Basic List whose Content is then processed as fss-0000 Basic.
- TODO: further document this.
+ All Basic List (fss-0002) escapes are applied before any Basic (fss-0000) is identified.
+
+ See the fss-0000.txt and fss-0002.txt specification files for details on the syntax rules.
+
+ Example\:
+ # fss-0004
+ # valid comments are ignored.
+ "The Object"\:
+ Does not need to be quoted.
+ This: does not need to be delimited.
+ This Does\\\:
+ Second\:
+ Continues until EOS/EOF.
+ All whitespace, including newline (and leading whitespace) is "part of content."
+ # Valid comments are still ignored.
+
+ Outer Objects would be\:
+ 1) "The Object"
+ 2) Second
+
+ Inner Objects would be\:
+ 1.1) Does
+ 1.2) This:
+ 1.3) This
+
+ 2.1) Continues
+ 2.2) All
+
+ Inner Contents would be\:
+ 1.1.1) not need to be quoted.
+ 1.2.1) does not need to be delimited.
+ 1.3.1) Does\:
+
+ 2.1.1) until EOS/EOF.
+ 2.2.1) whitespace, including newline (and leading whitespace) is "part of content."
Featureless Settings Specification: 0005 - Somewhat Basic List:
This is a fss-0002 Basic List whose Content is then processed as fss-0001 Extended.
- TODO: further document this.
+ All Basic List (fss-0002) escapes are applied before any Extended (fss-0001) is identified.
+
+ See the fss-0001.txt and fss-0002.txt specification files for details on the syntax rules.
+
+ Example\:
+ # fss-0005
+ # valid comments are ignored.
+ "The Object"\:
+ Does not need to be quoted.
+ This: does not need to be delimited.
+ This Does\\\:
+ Second\:
+ Continues until EOS/EOF.
+ All whitespace, including newline (and leading whitespace) is "part of content."
+ # Valid comments are still ignored.
+
+ Outer Objects would be\:
+ 1) "The Object"
+ 2) Second
+
+ Inner Objects would be\:
+ 1.1) Does
+ 1.2) This:
+ 1.3) This
+
+ 2.1) Continues
+ 2.2) All
+
+ Inner Contents would be\:
+ 1.1.1) not
+ 1.1.2) need
+ 1.1.3) to
+ 1.1.4) be
+ 1.1.5) quoted.
+
+ 1.2.1) does
+ 1.2.2) not
+ 1.2.3) need
+ 1.2.4) to
+ 1.2.5) be
+ 1.2.6) delimited.
+
+ 1.3.1) Does\:
+
+ 2.1.1) until
+ 2.1.2) EOS/EOF.
+
+ 2.2.1) whitespace,
+ 2.2.2) including
+ 2.2.3) newline
+ 2.2.4) (and
+ 2.2.5) leading
+ 2.2.6) whitespace)
+ 2.2.7) is
+ 2.2.8) part of content.
Featureless Settings Specification: 0006 - Somewhat Extended List:
This is a fss-0003 Extended List whose Content is then processed as fss-0000 Basic.
- TODO: further document this.
+ All Extended List (fss-0003) escapes are applied before any Basic (fss-0000) is identified.
+
+ See the fss-0000.txt and fss-0003.txt specification files for details on the syntax rules.
+
+ Example\:
+ # fss-0006
+ # valid comments are ignored.
+ "The Object" {
+ Does not need to be quoted.
+ This: does not need to be delimited.
+ \}
+ }
+
+ Second {
+ Continues until EOS/EOF.
+ All whitespace, including newline (and leading whitespace) is "part of content."
+ # Valid comments are still ignored.
+ }
+
+ Outer Objects would be\:
+ 1) "The Object"
+ 2) Second
+
+ Inner Objects would be\:
+ 1.1) Does
+ 1.2) This\:
+ 1.3) }
+
+ 2.1) Continues
+ 2.2) All
+
+ Inner Contents would be\:
+ 1.1.1) not need to be quoted.
+ 1.2.1) does not need to be delimited.
+ 1.3.1)
+
+ 2.1.1) until EOS/EOF.
+ 2.2.1) whitespace, including newline (and leading whitespace) is "part of content."
Featureless Settings Specification: 0007 - Very Extended List:
This is a fss-0003 Extended List whose Content is then processed as fss-0001 Extended.
- TODO: further document this.
+ All Extended List (fss-0003) escapes are applied before any Extended (fss-0001) is identified.
+
+ See the fss-0001.txt and fss-0003.txt specification files for details on the syntax rules.
+
+ Example\:
+ # fss-0007
+ # valid comments are ignored.
+ "The Object" {
+ Does not need to be quoted.
+ This: does not need to be delimited.
+ \}
+ }
+
+ Second {
+ Continues until EOS/EOF.
+ All whitespace, including newline (and leading whitespace) is "part of content."
+ # Valid comments are still ignored.
+ }
+
+ Outer Objects would be\:
+ 1) "The Object"
+ 2) Second
+
+ Inner Objects would be\:
+ 1.1) Does
+ 1.2) This\:
+ 1.3) }
+
+ 2.1) Continues
+ 2.2) All
+
+ Inner Contents would be\:
+ 1.1.1) not
+ 1.1.2) need
+ 1.1.3) to
+ 1.1.4) be
+ 1.1.5) quoted.
+
+ 1.2.1) does
+ 1.2.2) not
+ 1.2.3) need
+ 1.2.4) to
+ 1.2.5) be
+ 1.2.6) delimited.
+
+ 1.3.1)
+
+ 2.1.1) until
+ 2.1.2) EOS/EOF.
+
+ 2.2.1) whitespace,
+ 2.2.2) including
+ 2.2.3) newline
+ 2.2.4) (and
+ 2.2.5) leading
+ 2.2.6) whitespace)
+ 2.2.7) is
+ 2.2.8) part of content.
Featureless Settings Specification: 0008 - Embedded List:
This is a fss-0003 Extended List whose Content is then recursively processed as fss-0003 Extended List.
- TODO: further document this.
+ See the fss-0003.txt specification file for details on the syntax rules.
+
+ Example\:
+ # fss-0008
+ # valid comments are ignored.
+ "The Object" {
+ Does not need to be quoted.
+ This: does not need to be delimited.
+ \}
+ }
+
+ Second {
+ Nested Example.
+
+ Third {
+ Fourth {
+ This is nested Content.
+ }
+ }
+ }
+
+ Outer Objects would be\:
+ 1) "The Object"
+ 2) Second
+
+ Inner Objects (depth 1) would be\:
+ 2.1) Third
+
+ Inner Objects (depth 2) would be\:
+ 2.1.1) Fourth
+
+ Inner Contents (depth 0) would be\:
+ 1.1.1) Does not need to be quoted.
+ This: does not need to be delimited.
+ }
+
+ 2.1.1) Nested Example.
+
+ Third {
+ Fourth {
+ This is nested Content.
+ }
+ }
+
+ Inner Contents (depth 1) would be\:
+ 2.1.1.1) Fourth {
+ This is nested Content.
+ }
+
+ Inner Contents (depth 2) would be\:
+ 2.1.1.1.1) This is nested Content.
Featureless Settings Specification: 0009 - Reverse Mapping:
This is based off of fss-0000 Basic, except the Object is at the end of the line.
- TODO: further document this.
+ Each Object starts at the end of a line and whitespace to the left of the Object is not treated as part of the object.
+ Whitespace separates an Object from the Content.
+ An Object may be preceded by a newline, in which case means that the Object has no Content.
+ If only printing whitespace precedes a valid Object, that Object is considered to have no Content.
+
+ Content exists on the same line as the Object.
+ Content is represented as a single Content column that begins at a newline.
+ Content column consists of everything following the first non-whitespace character at the start of the line until the Object is reached.
+ Content column includes trailing whitespace before newline is reached.
+ Content column does not include any of the whitespace between the last non-whitespace character and the start of the Object.
+ No delimits are supported in the Content.
+
+ Key\:
+ \s = whitespace, except newline.
+ \b = either whitespace or printable, except newline.
+ \q = non-whitespace or quoted whitespace with no whitespace outside of the quotes.
+ \n = newline.
+ * = zero or more occurrences.
+ + = one or more occurrences.
+
+ Before Structure\:
+
+ Structure\:
+ \s*\b*\s+\q+\s*\n
+
+ After Structure\:
+
+ Example\:
+ # fss-0009
+ # valid comments are ignored.
+ Content from newline. "The Object"
+ object set. Second
+
+ Object would be\:
+ 1) The Object
+ 2) Second
+
+ Content would be\:
+ 1.1) Content from newline.
+ 2.1) object set.
+++ /dev/null
-# fss-0002
-
-Featureless Settings Specification: 000A - Extended Reverse Mapping:
- This is based off of fss-0001 Extended, except the Object is at the end of the line.
-
- TODO: further document this.
+++ /dev/null
-# fss-0002
-
-Featureless Settings Specification: 000B - Simple List:
- This might be similar to fss-0008 - Embedded List, except it is an fss-0003 Extended List with a (non-recursive) fss-0002 Basic List inside the Content.
-
- TODO: further document this.
--- /dev/null
+# fss-0002
+
+Featureless Settings Specification: 000A - Extended Reverse Mapping:
+ This is based off of fss-0001 Extended, except the Object is at the end of the line.
+
+ Each Object starts at the end of a line and whitespace to the left of the Object is not treated as an object.
+ Whitespace separates an Object from the Content.
+ An Object may be followed by a newline, in which case means that the Object has no Content.
+ If only printing whitespace follows a valid Object, that Object is considered to have no Content.
+
+ Content exists on the same line as the Object.
+ Content is represented as multiple Content columns.
+ Content columns are whitespace separated parts within the Content is terminated by the start of the Object.
+ Any number of Content columns may exist in the Content until the Object is reached.
+
+ Key\:
+ \s = whitespace, except newline.
+ \b = either whitespace or printable, except newline.
+ \q = non-whitespace or quoteded whitespace, no whitespace outside of quotes.
+ \n = newline.
+ * = 0 or more occurrences.
+ + = one or more occurrences.
+ ()* = grouping that repeats 0 or more times.
+
+ Before Structure\:
+
+ Structure\:
+ \s*(\s*\q+)*\s+\q+\s*\n
+
+ After Structure\:
+
+ Example\:
+ # fss-000a
+ # valid comments are ignored.
+ Content "content 2" content_3. "The Object"
+ object set. Second
+
+ Objects would be\:
+ 1) The Object
+ 2) Second
+
+ Contents would be\:
+ 1.1) Content
+ 1.2) content 2
+ 1.3) content_3.
+
+ 2.1) object
+ 2.2) set.
--- /dev/null
+# fss-0002
+
+Featureless Settings Specification: 000B - Simple List:
+ This might be similar to fss-0008 - Embedded List, except it is an fss-0003 Extended List with a (non-recursive) fss-0002 Basic List inside the Content.
+
+ See the fss-0002.txt and fss-0003.txt specification files for details on the syntax rules.
+
+ Example\:
+ # fss-000b
+ # valid comments are ignored.
+ "The Object" {
+ Does not need to be quoted.
+ This: does not need to be delimited.
+ \}
+ }
+
+ Second {
+ Nested Example.
+
+ Third:
+ Fourth:
+ There is parallel to Second rather than nested within Second.
+ }
+
+ Outer Objects would be\:
+ 1) "The Object"
+ 2) Second
+
+ Inner Objects (depth 1) would be\:
+ 2.1) Third
+ 2.2) Fourth
+
+ Inner Contents (depth 0) would be\:
+ 1.1.1) Does not need to be quoted.
+ This: does not need to be delimited.
+ }
+
+ 2.1.1) Nested Example.
+
+ Third:
+ Fourth:
+ There is parallel to Second rather than nested within Second.
+
+ Inner Contents (depth 1) would be\:
+ 2.1.1.1)
+ 2.2.1.1) There is parallel to Second rather than nested within Second.
# fss-0002
Featureless Settings Specification: 000D - Basic Rule:
- This is a special case that follows FSS-0002 (Basic List), and different FSS formats inside this Basic List.
+ This is a special case that follows fss-0002 (Basic List), and different FSS formats inside this Basic List.
This Basic List is considered the "Outer List" and the Content of this Outer List is considered the "Inner Content".
- The Inner Content may be any of the following FSS formats: FSS-0000 (Basic), FSS-0001 (Extended), and FSS-0003 (Extended List).
+ The Inner Content may be any of the following FSS formats: fss-0000 (Basic), fss-0001 (Extended), and fss-0003 (Extended List).
The way in which each format is determined is first to see if the Inner Content Object would be a valid Extended List Object.
If the Inner Content Object is not a valid Extended List Object, then check to see if it is an Basic/Extended Object.
The FSS Basic and FSS Extended Objects have the same format for Object names but the FSS Extended List Object is slightly different.
Anything that would match an FSS Extended List Object must therefore be an FSS Extended List Object.
- This supports the use of IKI-0000 (Unrestricted) but only within the Content of the outermost Basic List.
- Furthermore, should there be a Basic List that defines IKI names and values, then that Basic List must not support IKI substitution.
+ This supports the use of iki-0000 (Unrestricted) but only within the Content of the outermost Basic List.
+ That is to say, the IKI is only processed once.
Additional restrictions on the use of IKI syntax is allowed if explicitly defined in the implementing specification.
- This additional restriction may also include using a more restrictive IKI syntax, such as "IKI-0001 (Basic IKI)".
+ This additional restriction may also include using a more restrictive IKI syntax, such as "iki-0001 (Basic IKI)".
Anything implementing this specification may impose its own restrictions on when to determine if the Inner Content is what FSS format, based on Object names.
- See the appropriate specifications for the Key/Structure/Example documentation for the respective FSS-0000 (Basic), FSS-0001 (Extended), and FSS-0003 (Extended List).
+ See the fss-0000.txt, fss-0001.txt and fss-0003.txt specification files for details on the syntax rules.
Example\:
-
+ # fss-000d
main:
name "Boot Devices"
2.1.2) ip link set lo down;
3.1.1) mount -a -O no_netdev
3.1.2) umount -arf -O no_netdev
-
- Multiple sub-standards may be appended to the FSS header, using the same format structure, such as supporting IKI: "# fss-0000 iki-0000" or HTML5: "# fss-0000 html-0005".
- With the ? representing the (hexadecimal/base-16) number that represents the particular specification structure.
- All settings specifications SHOULD avoid any form of noise, relative to the data being stored.
- - ie: XML would be considered anti-KISS due to the extreme level of noise generated by the XML language (not easy to read).
+ - XML would be considered anti-KISS due to the extreme level of noise generated by the XML language (not easy to read).
- The settings files are setup so that they should (reasonably) produce easy readability on both the console and in a GUI.
- The most basic form of FSS specifications consist of two main parts: an "object" and the "content".
- - Object: considered the name or identifier of some particular data; Objects do not need an associated Content.
- - Content: the data associated with a given Object; all Content MUST have an associated Object.
+ The most basic form of FSS specifications consist of two main parts: an "Object" and the "Content".
+ - Object: Considered the name or identifier of some particular data; Objects do not need an associated Content.
+ - Content: The data associated with a given Object; all Content MUST have an associated Object.
Objects and Contents can include any characters allowed by the specifications.
The specification may choose how a given Object or Content are represented and parsed.
- For example, in FSS-0000 (Basic), Content is treated as a single item whereas in FSS-0001 (Extended), Content is broken apart in multiple sub parts.
+ For example, in fss-0000 (Basic), Content is treated as a single item whereas in fss-0001 (Extended), Content is broken apart in multiple sub parts.
Contents may be broken up into zero or more discrete sets of Content.
Each of these discrete sets of Content are referred to as a column.
These columns do not need to be setup in a column structure, the word "column" is simply used as a grouping terminology.
While a Content refers to the entire set, a column (more specifically, a Content column) refers to the individual discrete sets within the Content.
- For example, in FSS-000 (Basic) the entire Content may be further represented as a single column.
- For example, in FSS-001 (Extended) the entire Content may be further represented as multiple columns.
+ For example, in fss-000 (Basic) the entire Content may be further represented as a single column.
+ For example, in fss-001 (Extended) the entire Content may be further represented as multiple columns.
In all cases, specifications that separate Objects from Contents using whitespace, the first whitespace separating the Object and Content must not be considered part of the Object nor part of the Content.
All spaces after the first separating whitespace is generally ignored until the first non-whitespace character is found, unless otherwise specified.
This simplifies identifying the object, use quoted Objects to support whitespace before/after an object for styling purposes.
Unless otherwise specified, quotes may only be either a single quote (') or a double quote (") and only a backslash '\' may be used as a delimiter.
- For example, FSS-0000 (Basic)\:
+ For example, fss-0000 (Basic)\:
\"Object 1" has content starting at the '1', with an Object named '"Object'.
\\"Object 1" has content starting at the '1', with an Object named '\"Object'.
"Object 1\" is an unterminated object due to the escaped closing quote.
Unless otherwise specified, character/data delimits are performed only when required and not unilaterally.
In the case of Objects, delimits would only apply when that Object could be potentially identified as an Object.
- For example, FSS-0001 (Extended) needs quotes to group parts that include spaces, if there is no initial quote, then a quote following the data MUST NOT be delimited.
+ For example, fss-0001 (Extended) needs quotes to group parts that include spaces, if there is no initial quote, then a quote following the data MUST NOT be delimited.
Such as these following three lines\:
"Object 1" "This is a single quoted Content." \"Additional unquoted Content."
Object_2 This is multiple" Contents and the trailing quote does not need to be delimited.
- fss-0007: Very Extended List
- fss-0008: Embedded List
- fss-0009: Reverse Mapping
- - fss-000A: Extended Reverse Mapping
- - fss-000B: Simple List
- - fss-000C: Iki Text
- - fss-000D: Basic Rule
+ - fss-000a: Extended Reverse Mapping
+ - fss-000b: Simple List
+ - fss-000c: Iki Text
+ - fss-000d: Basic Rule
This specification provides a small set of vocabulary names meant to be used for substitution in simple scripts.
This specification only loosely defines the vocabulary context.
- Flexibility on interpretation is intended so that the context can be more fine-tuned for a given script design.
+ This vocabulary may be further extended but must at least support the taxonomy defined here.
+ Flexibility on interpretation is intended so that the context can be more fine-tuned and customized.
+
+ The taxonomy for the "context", "define", and "parameter" are intentionally not defined here and left open.
+ One utilizing this should document the taxonomy for each of these as desired.
Vocabulary\:
+ - context: intended to be used for printing (or tagging) context codes before and after text, such as with color context.
- define: intended to be used for global properties, much like a C/C++ #define.
- parameter: intended to be used for parameters or variables.
The variable name is considered the "Object".
The variable variable is considered the "Content".
- The IKI format will use IKI-0000 to represent an IKI with no explicitly defined vocabulary.
- Whereas IKI-0001 and beyond represent a specific IKI vocabulary.
+ The IKI format will use iki-0000 to represent an IKI with no explicitly defined vocabulary.
+ Whereas iki-0001 and beyond represent a specific IKI vocabulary.
Whitespace, non-word (and non "_", "-", "+") character punctuations, or the start of file must exist before any valid variable name.
Whitespace and non-word (and non "_", "-", "+") character punctuations may not exist as part of the variable name.
projects / fll / commitdiff