codesimian
Class IndependentCS

IndependentCS is used to avoid DEPENDENCY CYCLES when creating the first few CSs.
If you add a new function to CS but not override in IndependentCS, you might create a dependency cycle.
All functions in IndependentCS return 0, false, or this. Override any new functions in CS to return that.

IndependentCS's functions never return any other CS, only returns itself.
Examples: P(87), heap(), getExec()... all return this CS.

insertP(int index,
CS insertMe)
same as setP(int,CS) but inserts instead of overwriting.

long

J()
Execute this CS and cast to long.
Most subclasses should override JForProxy() instead of J(), or neither.WARNING: by default, like the other execute functions, J() calls D() and casts to J's type.
long is the only primitive type that double has problems with.
double maps to long correctly for all values between at least -(2^51) and 2^51 - 1.
Past that, accuracy is less than integer precision.

setD

setP

Every CS is a list of other CSs, between size minP() and maxP() inclusive.
setP overwrites one of those CSs or adds a new one at the end, depending on the index.
If index is between 0 and countP()-1, overwrites. If it equals countP(), adds at end.

PType

There is a TYPE for each Param.
A TYPE is a CS whose minP() is at least 1.
When a TYPE executes, it MEASURES THE TYPE OF its first param CS.
It returns a positive number if it is that type, else 0 or negative.
Some TYPEs use only 2 numbers, while others can return any number on a continuous scale.

Types are optional. To not use types, return the default type: Static.defaultType().
The default type returns true for any CS.
Most CSs do not need types therefore they use the default type.

P

Returns a CS from this list with specific index. Every CS is a list of other CSs,
each with an index between 0 and countP()-1 inclusive.
The quantity of CSs in the list is countP(), which should be between minP() and maxP() inclusive.
Errors could occur if quantity is outside that range when this CS is EXECUTED.

There can also be CSs at negative indexs. Maps some negative indexs to the HEAP:
If x <= -2 then CS.P(x) returns CS.heap().P(-x).
Index -1 represents NULL.

description

a short description of this CS, shorter than the javadoc,
but long enough to tell what the params are for.
Example use: in automatically generated webpages for CodeSimian.
Example: "returns sum of all params" for Add.

fuel

Fuel limits EXECUTION of CSs, to make sure none execute too much more than the others.
Fuel is ENFORCED by PROXYs, but each subclass of CS must be designed to defer
all EXECUTE functions (V Z B C S I J F D L(Class) L(int,Class,int)) to the PROXY for that to work.
In a proxy, the relationship between X and XForProxy (for all X) is different [I'll write more about that later].
Depending on which proxy you choose, it might decrease fuel and not execute "?ForProxy()" if fuel runs out.

There are 2 kinds of fuel. The CS fuel can be shared, and can distribute fuel in complex ways.
The int fuel is individual to each CS.

This is the easiest (and slowest) way to use 1 fuel:
boolean usedFuel = fuel().setD( fuel().D() - cost() )

Fuel CSs must refuse to become negative. This code: fuel().setD(-3) must always return false.

When a CS's myFuel is decreased to 0, the only way it should
ever EXECUTE again is if FUEL is TRADED for myFuel.
One myFuel (type int) costs cost() (type double) amount of FUEL (type double, wrapped in a CS).
That often allows the efficient use of the FUEL CS object,
because you could trade many myFuels for more FUEL in the same amount of code as for trading one at a time.
When a CS's myFuel runs out, you might set it up so it automatically buys 10 more,
but only if some other code returns true.
Certain groups of code could be allowed more execution credits depending
on their expected usefulness, predicted by other intelligent code.

Can divide FUEL into heirarchies without extra code.
Every CS has a FUEL object, and fuel objects are CSs,
so every fuel object has a fuel object...
When a fuel object runs out of fuel, it might try to get more from its fuel object...
but that fuel object might refuse. A heirarchy of fuel control could be built.

newInstance

The primary way to instantiate subclasses of CS.
CodeSimian is partially a PROTOTYPE LANGUAGE.

Copies the INSTANCE CS and pointers to its childs.
anyCS.P(2) == anyCS.newInstance().P(2)

anyCS.getClass() and anyCS.newInstance().getClass() do not have to share any ancestor class except CS.class.
Classes that use artificial-intelligence may choose to return a different class type to improve themselves,
but that class type should try to BEHAVE SIMILARLY and must have the SAME childs when newInstance() returns it.

If a subclass is uses variables in a strange way, it may need to override newInstance() to copy them.

Returns a new CS instance of this "type".
This has the same name and purpose as java.lang.Class.newInstance().

Its vague. Subclasses of CS that have trees or networks of objects
that the CS depends on might need to copy the whole tree etc,
or might use the same tree, or only copy the root etc.
Example: the Function class might need to override newInstance() differently.

heap

HEAP is a place to put CSs that are not directly related to the CS that contains them.
Example: Params are directly relevant, but wrappers for the Java functions of a CS (like heap()) are not.

If you think of the positive (Param) indexs as STACK memory,
this is HEAP memory and is mapped to negative param indexs.
Index 0 is grouped with the positives. Index -1 is reserved for NULL.
Heap indexs start at -2, which maps to index 2 in the HEAP. The heap's first 2 indexs are not used.

If x <= -2 then CS.P(x) returns CS.heap().P(-x)

Every CS must have a HEAP, which is used like heap memory (compared to stack memory).
Multiple CSs can share the same HEAP or each could have its own.
Only nonnegative P indexs are used for the heap,
but they're usually mapped to negative indexs in the CS(s) that use this HEAP.

Usually HEAPs contain reflected java functions for the class of the CS that contains this HEAP.
Some HEAPs might contain other variables.

prevL

The function prevL() does not fit well into this interface.
If it had a Class parameter, it would take too much instance space and time.
If it has no Class parameter, it might not match the Object you're comparing to.

The functions L(Class) Z B C S I J D and F should set the values that these PREV functions return.

Other PREV functions return every other type.
There are 9 PREV functions. All 9 are about the same one variable, which can be ANY type.
Any one of these functions reads or writes the value of the other 8.

setMyFuel

myFuel

Returns how many times this CS may EXECUTE before it needs to trade some CS fuel for int fuel.
When it runs out, it can trade to get more fuel, or it can stop executing and return its previous value instead.
Example, the previous double value is prevD().

myFuel() is for this specific CS. fuel() can be shared between CSs and has more complex behaviors.
Should always be 0 or positive. If 0, this CS should not EXECUTE, but it is the PROXY's job to enforce that.

I

J

Execute this CS and cast to long.
Most subclasses should override JForProxy() instead of J(), or neither.WARNING: by default, like the other execute functions, J() calls D() and casts to J's type.
long is the only primitive type that double has problems with.
double maps to long correctly for all values between at least -(2^51) and 2^51 - 1.
Past that, accuracy is less than integer precision.

L

Optionally execute this CS, and definitely try to CAST it to the specified Java type.
If fail, throw a ClassCastException.

Should I change this from throwing a CSCastException to return null instead?

It is preferred not to return CSs from this function.
If you have a CS to return, the standard is to put it in param0... setP(0,returnValue),
where the function caller should get the output from... P(0).

The functions: V L Z B C S I J F and D, usually EXECUTE this CS
and CAST its value to the specified type.
L does not have to execute this CS, but all the others do.
The other difference is L can throw a CSCastException (extends ClassCastException),
which is a RuntimeException so you do not have to use try/catch if you trust it.

No pattern of L()'s behavior is guaranteed.
The L's of some some CSs are more predictable than others, often written about in javadoc.
If it casts correctly, it could fail later. If it fails many times,
and you try again, it could still succeed.

Example: new int[7][6][5].getClass().getName() returns "[[[I".
These 9 function names (not 10 because excludes Void) are also
used by a very important part of Java (but not as function names):
java.lang.Class.name() .

L

same as L(Class) except only uses a subset of param indexs.
Like many other L functions, allows optimizations of converting CSs to specific Object types.
Example: new S("abcdefg").L(2,String.class,3) returns "cde".

Execute this CS and cast to double.
D() is the main EXECUTE function. D() uses DForProxy().
DForProxy() is the main action of every CS, the most important function.
By default, all other primitive EXECUTE functions defer to D.
Functions that EXECUTE this CS: L(Class) L(int,Class,int) Z() B() C() S() I() J() F() D() V()

LForProxy

The "?ForProxy" functions should only be called by a PROXY CS.
They skip the proxy. Example: B() calls the PROXY on this CS, then that PROXY calls thisCS.BForProxy().
Generally, subclasses of CS should reimplement only the ?ForProxy functions.