AviSynth Library Files

################################################################################
#    Documentation: Documentation for libraries
#    Copyright (C) 2012  Adrian Hawryluk - adrianh.bsc@gmail.com
#
#    This program is free software: you can redistribute it and/or modify
#    it under the terms of the GNU General Public License as published by
#    the Free Software Foundation, either version 3 of the License, or
#    (at your option) any later version.
#
#    This program is distributed in the hope that it will be useful,
#    but WITHOUT ANY WARRANTY; without even the implied warranty of
#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#    GNU General Public License for more details.
#
#    You should have received a copy of the GNU General Public License
#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
#
#==[ log ]=====================================================================
#  2012/01/23 - Adrian Hawryluk
#   - added GPL
#  2012/02/29 - Adrian Hawryluk
#   - updated document
#   - released 0.5b
#  2012/03/01 - Adrian Hawryluk
#   - released 0.51b
#  2012/03/02 - Adrian Hawryluk
#   - released 0.52b
#
# Change Log:
# ===========
# 0.52b - Fixed StrCmp function workaround.
#           StrCmp     < v2.60 true replacement
#       - Added ord() function
#       - Fixed up include hierarchy so it is faster and saner.
#       - Removed cruft and added additional inline documentation.
#       - Changed it so that you MUST make a call to output_file().  If you don't
#         anything that is output is lost.
# 0.51b - Added workaround functions to make this library compatible with 
#         versions 2.07 or higher.  Workarounds include functions if they
#         don't already exist:
#           Min(a, b)  < v2.58 replacement (takes only 2 parameters)
#           Max(a, b)  < v2.58 replacement (takes only 2 parameters)
#           ScriptDir  < v2.60 replacement (only works when using include, not import)
#           ScriptFile < v2.60 replacement (only works when using include, not import)
#           ScriptName < v2.60 replacement (only works when using include, not import)
#           undefined  < v2.60 replacement
#           StrCmpi    < v2.60 replacement
#           StrCmp     < v2.60 replacement (is actually StrCmpi)
# 0.5b  - Replaced old SESA/RA_foreach construct with a new improved model
#       - introduced file, string, include, vars, and varsConst libraries.
#       - Added and fixed SESA/RA_findSorted, SESA/RA_setSorted functions.
#       - Added ability to take variables into and out of the for loop scope.
#       - Fixed some miscellaneous bugs.
#       - Added AviSynthLib Usage.odt/AviSynthLib Usage.pdf for your reading 
#         pleasure.
#       - TODO: Need more regression tests built.
#               Possible structs, dictionary and OOP libraries.
# 0.1b  - Just released
################################################################################

Introduction:
=============
These libraries I created for AviSynth were originally because I couldn't find
any array system that was usable.  The only one I was referred to took too long
to be useful.

However, due to this, a whole lot of little libraries fell out that can be used
for other uses as well.

These libraries have been documented in source code.  I will try and make a more
thorough, easier to read document later.  However, until that time, I'm going
do describe my coding style to give you some insight as to what I am doing in
the code.

Naming conventions:
===================
Because of the flat namespace, I've opted to use a modified naming convention
that I use in C.  Functions/variables that are related to each other are
prefixed with a common word/acronym.  These are then followed by zero, one, or
two or more underscores '_'.  I use zero or one to indicate that the function/
variable should be touched by users in the 'outside world', two or more if it
is meant for internal consumption only.  Zero denotes a local variable, one or
more are global variables/functions.  CamelCase is used prior and after the 
underscores.  Occasionally I will use more than one group of underscores to
specify something that is related to the group with the same prefix.

Library overview:
=================
block
 - Encapsulate data in a string.

blocks
 - Test showing use of blocks as an array construct (SLOW!)

cachedDynamicElementSizedArray (CDESA)
 - Original idea to make array faster - superseded by reference array.
   Defunct for now.

encodedHexNumber
 - Encodes hex numbers to make it clear how long the hex string is.

for
 - Making recursion perform like non-recursion.  It's still recursion
   but it is nicer to the stack.

hex
 - Replace missing Hex function and added some others.

memory
 - Allocates/deallocates memory and gives out references to allocated memory.

misc
 - Miscellaneous stuff that didn't fit anywhere else.

parameters
 - Allow for long parameter lists to be converted as quickly as possible
   to a RA for later processing.

profile
 - Profile the code to determine where the bottleneck is coming from.

referenceArray (RA)
 - The actual reason for this project.  A fast O(1) array implementation.

singleElementSizeArray (SESA)
 - Originally meant for the cache of the CDESA, repurposed for the RA.

testing
 - This is support for regression testing.
 
lib_regressionTests
 - These keep me sane by ensuring that modifications I do will not break
   the current functionality.  These are a work in progress.

                       [---] NEW IN 0.5b [---]
file
 - File name manipulation utilities and a file search utility.
 
string
 - Some string functions that I thought should be around.

include
 - An include library to include files only once to speedup loading.
 
vars
 - A way of bringing in variables into another scope and back again.
 
varsConst
 - A way of bringing variables into another scope, but NOT back again.

For more information on each library, please go to the corresponding library
file. Please forgive any obvious errors in the documentation displaying
parameters that aren't there, function names that are wrong or descriptions
that are for another function.  This is due to me forgetting to update a 
cut and paste template from another function.  Please tell me and I'll fix it
as soon as I can.

Also, I've created a AviSynthLib Usage document (AviSynthLib Usage.odt /
AviSynthLib usage.pdf) to help with learning how to use the libraries.

Installation:
=============
Take the 7z file and uncompress it into the plugins folder while maintaining
the directory tree.  This is important as include.avsi must be in the
plugins folder while the rest of the library needs to be in the AviSynthLib
directly off of that folder.

Also, if you are using a version of AviSynth prior to 2.60 *AND* you did not
install in C:\Program Files\AviSynth 2.5, you must make a modification to
the include.avsi file.  Look for this line in that file:

    global ScriptDir="C:\Program Files\AviSynth 2.5\plugins\"

You must change that path to your installation directory.  Also, make sure
you keep the trailing "\plugins\" folder listed.

Conclusion:
===========
I've had fun learning this language and writing this code while I've been 
unemployed.  I hope it helps others out there.

If you have any questions, or bug reports please feel free to write to me at 
adrianh.bsc@gmail.com.  Please put somewhere in the subject line 'AviSynthLib'
(with or without quotes) so that I can become aware of it sooner, as I do get
a lot of email.

Thanks.



Adrian Hawryluk


Addendum:
=========
There are some interesting possibilities out there with this language, and these
libraries, including but not limited to, creating structures and a possible OO 
framework.  I'm not sure if there is that much interest in this, but if there 
is, please drop me a line and say so. :)