updated readme

svn path=/trunk/externals/loaders/hexloader/; revision=8827

1 files changed, 133 insertions, 0 deletions

diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..94cae11
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,133 @@
+---------
+hexloader
+---------
+(c) copyleft 2006-2007 IOhannes m zmölnig, IEM
+
+
+the problem
+-----------
+when dealing with abstractions and single-file externals, we have a 1-to-1 
+correspondence between an objectclass and a file.
+examples:
+  the [expr] object matches an external "./expr.pd_linux"
+  the [zexy/nop~] object matches an abstraction "./zexy/nop~.pd"
+general:
+  the object [<name>] matches a file "<name>.$EXT"
+when dealing with externals, the name of the objectclass is also to be found 
+in the setup function within the external
+example:
+  to load the "expr" external, Pd will look for a function 
+  "expr_setup()" within the file "./expr.pd_linux"
+general:
+  the external "<name>" has to provide a setup-function 
+  "void <name>_setup(void)"
+
+this works fine, as long as there are no special characters involved:
+according to the above scheme, when loading the external "expr~"
+Pd should actually be looking for "expr~_setup()" within the file 
+"./expr~.pd_linux"; 
+unfortunately, the C-language (wherein most externals are written) does not 
+allow function-names to use any characters other than "a-zA-Z0-9_".
+therefore the name "expr~_setup()" is invalid;
+therefore, Pd handles the case of the trailing "~" in a special way: it 
+actually expands the "~" to "_tilde" and looks for "expr_tilde_setup()"
+general:
+  the object [<name>~] corresponds to an external "<name>~.pd_linux" which 
+  offers a setupfunction "<name>_tilde_setup()"
+unfortunately this doesn't work well for a larger number of characters 
+forbidden in C-functionames.
+example:
+ how should the setupfunction for an objectclass [~<~] be named?
+
+additionally, several filesystems have problems with certain characters.
+for instance, you cannot use the character '>' on FAT32 filesystems.
+but how do you then create a file for the objectclass [>~]?
+
+
+a solution
+----------
+one solution is to just forbid objects with weird (non alphanumerical) names.
+pretty frustrating
+
+another solution
+----------------
+use libraries with valid names that hold objects with weird names
+
+a better solution
+-----------------
+another solution is to translate the forbidden characters into allowed ones.
+for instance, every ASCII-character can be called by it's name (e.g. 'a') as
+well as by it's numeric value "97" (or in hex: "0x61")
+the here-proposed solution is, to replace every illegal character by it's 
+hexadecimal representation (in lowercase).
+examples:
+  [>] corresponds to the file "0x3e.pd"
+  [>~] corresponds to the file "0x3e0x7e.pd" or to "0x3e~.pd"
+  [a>b] corresponds to the file "a0x3eb.pd"
+
+the same system can be applied to the setup-functions:
+examples:
+  [a>b] has a setupfunction "a0x3eb_setup()"
+CAVEAT:
+C also forbids to start function names with numeric values.
+therefore, this is a nono:
+  [>]'s setupfunction would be "0x3e_setup()" (ILLEGAL)
+we can simply fix this by putting the "setup()" in front:
+ [>] has a setupfunction "setup_0x3e()"
+
+implementation
+--------------
+the "hexloader" external adds the possibility to Pd use the proposed
+alternative naming scheme.
+just load the "hexloader" lib, and the next time you try to create the
+(yet unknown) object X, Pd will also look for several alternatives
+example:
+  [>~]
+	">~.pd_linux"			(filename ILLEGAL on SOME filesystems)
+		>~_setup() 		(ILLEGAL functioname)
+		setup_>~		(ILLEGAL functioname)
+		0x3e0x7e_setup()	(ILLEGAL functioname)
+		setup_0x3e0x7e()
+	"0x3e~.pd_linux"
+		0x3e~_setup()		(ILLEGAL functioname)
+		setup_0x3e~()
+		0x3e0x7e_setup()	(ILLEGAL functioname)
+		setup_0x3e0x7e()
+	"0x3e0x7e.pd_linux"
+		0x3e0x7e_setup()	(ILLEGAL functioname)
+		setup_0x3e0x7e()	
+	">~.pd"				(filename ILLEGAL on SOME filesystems)
+	"0x3e~.pd"
+	"0x3e0x7e.pd"
+the hexloader will try one alternative after another until it finds one
+that actually works (there is no problem in querying the ILLEGAL names,
+it is just impossible to create such filenames/setupfunctions)
+
+
+handling of "/"
+---------------
+a special problem is the "/" character, as this might be a special character
+in the name of an object and the path-delimiter
+example:
+	"a/b" might be a file "b" in the directory "a" or just "a/b"
+solution
+--------
+hexloader treats the "/" in a special way, as it tries all possibilities
+example:
+  [a/b}
+	a/b	(file "b" in directory "a")
+		b_setup()
+		setup_b()
+	a0x2fb	(file "a/b")
+		a0x2fb_setup()
+		setup_a0x2fb()
+
+
+CAVEATS
+=======
+obviously the abstraction "0x3e.pd" can be addressed as both [>~] and [0x3e]
+this basically means, we have now an n-to-1 correspondence!
+in the case of externals this could be fixed by only using the "setup_*"
+naming scheme (instead of Pd's standard "*_setup()")
+for practical reasons this has been dumped (too many devs created the wrong
+setupfunction and couldn't tell why the externals would not load)