Common Lisp Package: EVOL

README:

FUNCTION

Public

DEFAULT-SOURCEFN (TARGET MODIFIER)

default-sourcefn target modifier => string Default source computing function that does nothing but ignoring all arguments and always returns an empty string.

GETENV (VAR &KEY (ENV *ENVIRONMENT*) (EXPANDED T) (DEFAULT ))

getenv var &key env expanded default => mixed Return object stored for key var from hash :env and :expand the object for external command use if desired.

PATHNAME-CHANGE-SUFFIX (SUFFIX PATHSPEC)

pathname-change-suffix suffix pathspec => string Change suffix of path name string pathspec; adds suffix if none present yet.

PATHNAME-SUFFIX-P (SUFFIX PATHSPEC)

pathname-suffix-p suffix pathspec => boolean Predicate whether pathspec has file name suffix.

REPL

repl => quit Top-level function used for the standalone executable created through bootstrapping evol. Heads-up: Quits CL after execution.

RUN-COMMAND (CMD &KEY (VERBOSE T) (FATAL NIL))

run-command cmd &key verbose fatal => (integer string string) Run command line list CMD (blocking), returning VALUES of exit status of invocation and strings of stdout and stderr output. If FATAL is non-nil and exit status is not 0, signal COMMAND-FAILURE instead. Side-effect: Print CMD prior to invocation and command output if VERBOSE is non-nil.

Private

ARGUMENT-OPTION (ARGUMENT)

argument-option argument => option Find option owning ARGUMENT (command line option).

CL-LOAD-OPS (LIST)

cl-load-ops list => list Prepares a list of ASDF:LOAD-op forms for op in input LIST.

CL-RUN-COMMAND (IMPLEMENTATION PACKAGES CMD &KEY (VERBOSE T) (FATAL NIL))

cl-run-command implementation packages cmd &key verbose fatal => (integer string string) Run CL command sequence CMD with the appropriate IMPLEMENTATION. Load all PACKAGES with ASDF first. Wrap CMD in an implicit PROGN and HANDLER-CASE.

DEFLATE-STRING (LIST &OPTIONAL (SEPARATOR ))

deflate-string list &optional separator => string|object Splice list of strings into merged string having elements separated with string seperator.

DEPENDENCY-NODE (NAMEFN DEPENDENCYFN OBJECT)

dependency-node namefn dependencyfn object => node Transform OBJECT into a node (list) by appending the results of calling NAMEFN and DEPENDENCYFN against it.

DEPENDENCY-NODES-HASHTABLE (PREDICATE NAMEFN DEPENDENCYFN ENV)

dependency-nodes-hashtable predicate namefn dependencyfn env => node-list Filter out all values satisfying PREDICATE from hashtable ENV and return result list of transforming each one into a node list by calling NAMEFN and DEPENDENCYFN.

EVOLUTION-ARGUMENTS (ARGS)

evolution-arguments args => list List of what to evolve based on list of command line args, default evolution and - as a last resort - the first defined evolvable.

EVOLVABLE-P (OBJECT)

evolvable-p object => boolean Tell whether OBJECT is an EVOLVABLE.

EXPAND-$-MATCH (MATCH)

expand-$-match match => string Lookup match in the environment CL was started in returning the result.

EXPAND-%-MATCH (MATCH TARGET SOURCEFN ENVIRONMENT)

expand-%-match match target sourcefn environment => string Act depending on string match: - % returns % - @ returns target - < returns result of invoking sourcefn against target and modifier - Any other sequence will be looked up in evol's environment returning the result, defaulting to an empty string - In case of @ and <, if target respectively sourcefn invocation returns a list, it will be auto-deflated to a string with spaces as element seperator. To modify the deflation seperator, simply pass any non-whitespace character sequence after @ or <, e.g. [@,] for target := (foo bar baz) => "foo,bar,baz"

FIND-NODE (NAME NODES)

find-node name nodes => node Find and return node designated by NAME in NODES.

FORMAT-OPTION (STREAM STRING &OPTIONAL (ARGUMENT NIL))

format-option stream string argument => result Print option STRING with optional ARGUMENT to STREAM; formatting depends on whether STRING is a short or a long option, determined by its length.

INTERNIFY (NAME)

internify name => symbol Return interned symbol for arbitrarily typed name; useful for use as hash keys.

INTERPOLATE-$-ARGUMENT (ARGUMENT)

interpolate-$-argument argument => string Expand all matches of $ words in string ARGUMENT.

INTERPOLATE-%-ARGUMENT (ARGUMENT TARGET SOURCEFN ENVIRONMENT)

interpolate-%-argument argument target sourcefn environment => string Expand all matches of % words in string ARGUMENT honoring the special TARGET and SOURCEFN matches and, for the rest, the ENVIRONMENT.

INTERPOLATE-ARGUMENT (ARGUMENT TARGET SOURCEFN ENVIRONMENT)

interpolate-argument argument target sourcefn environment => list Expand all % and $ matches in string argument in turn.

INTERPOLATE-COMMANDLINE (CMD &KEY (TARGET ) (SOURCEFN #'DEFAULT-SOURCEFN) (ENVIRONMENT *ENVIRONMENT*))

interpolate-commandline cmd &key target sourcefn environment => list Interpolate split arguments of command line string CMD after grouping through Bourne shell syntax block quoting, see split-commandline for details. Unquoted quotes are stripped after interpolation, single quotes prevent interpolation of their contained argument while double quotes don't. Returns list of split and interpolated arguments.

JOBS-BREEDER (JOBS)

jobs-breeder jobs => breeder Create the appropriate BREEDER for the number of JOBS.

LEAF-NODES (NODES)

leaf-nodes nodes => node-list Return all leaf nodes in NODES. Leaf nodes are simply the ones with no dependencies at all.

LOAD-EVOLUTION (OPTIONS)

load-evolution options => void Load the evolution file based on command line OPTIONS.

MAPTHREAD (FUNCTION LIST &REST MORE-LISTS)

mapthread function list &rest more-lists => list Apply FUNCTION against each set of elements from LIST and MORE-LISTS just like MAPCAR but use a new thread for each call. Returns result list from joining all threads created that way.

NEW-RING-BUFFER (LENGTH)

new-ring-buffer length => ring-buffer Create a new RING-BUFFER containing a simple character vector of fixed size LENGTH.

PARSE-COMMANDLINE (ARGV)

parse-commandline argv => (args opts) Parse command line argument list ARGV with UNIX-OPTIONS:MAP-PARSED-OPTIONS and defined available *OPTIONS*.

POSIX-ARGV

posix-argv => list Return command line argument list. Implementation dependent.

POSIX-GETENV (NAME)

posix-getenv name => string Return value for POSIX environmental key name, empty string if nothing found.

POSIX-QUIT (&OPTIONAL CODE)

posix-quit => bye bye Quit the current running CL instance returning error CODE.

RBREF (BUFFER INDEX)

rbref buffer index => character or #Nul Return character stored at INDEX in ring BUFFER.

SETFRBREF (VALUE BUFFER INDEX)

setf (rbref buffer index) value => value SETF for RBREF. If INDEX > LENGTH of BUFFER, start over at the beginning.

READ-HEREDOC (STREAM CHAR ARG)

read-heredoc stream char arg => string Return string from STREAM up to the point where the string read first until CHAR is encountered. All evaluation is completely turned off so no quoting is required at all. Example: #>eof>Write whatever (you) "want"!eof => Write whatever (you) "want"!

READ-UNTIL-MATCH (STREAM TERMINAL)

read-until-match stream terminal => string Read characters from STREAM until a sequence equal to string TERMINAL is read. Return all characters read as string omitting TERMINAL itself. Signal error upon EOF.

REPLACE-WITH-REGION (REPLACEFN &REST ARGS)

replace-with-region replacefn &rest args => closure Create closure that is suitable for use with cl-ppcre replacement forms. Created closure invokes replacefn against the matched subsequence in the string to be searched additionally passing args.

RESET-EVOLVABLES (&OPTIONAL (ENV *ENVIRONMENT*))

reset-evolvables env => evolvables-list RESET all evolvables in hashtable ENV. Useful for development.

RESOLVE-ALL (NODES RESFN &OPTIONAL (ROOTS NODES))

resolve-all nodes resfn &optional (roots nodes) => list of dags or queues Resolve list of distinct ROOTS (or, by default, everything) in node-list NODES using resfn.

RESOLVE-DAG (ROOT NODES)

resolve root nodes => dag Try to resolve dependencies for ROOT node in NODES and return its dependency dag (directed acyclic graph). Dags are suitable for parallel building.

RESOLVE-QUEUE (ROOT NODES)

resolve-queue root nodes => queue Try to resolve dependencies for ROOT node in NODES and return its dependency queue. Queues are suitable for sequential building only.

RESOLVE-ROOTS (NODES RESFN)

resolve-roots nodes resfn => list of dags or queues Resolve node-list NODES using resfn for all its root-nodes.

RING-BUFFER-CLEAR (BUFFER)

ring-buffer-clear buffer => -1 Reset all indices of BUFFER to their initial state.

RING-BUFFER-END (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

RING-BUFFER-FLUSH (BUFFER)

ring-buffer-flush buffer => string Flush all unused characters in BUFFER.

RING-BUFFER-INSERT (BUFFER VALUE)

ring-buffer-insert buffer value => value Increment END of BUFFER inserting VALUE at the new index.

RING-BUFFER-NEW (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

RING-BUFFER-NEXT (BUFFER)

ring-buffer-next buffer => character or nil Return next match character incrementing USED in BUFFER or simply NIL if none are left.

RING-BUFFER-POP (BUFFER)

ring-buffer-pop buffer => character Increment START of BUFFER returning VALUE at the new index. Additionally, reset the BUFFER match indices.

RING-BUFFER-RESET (BUFFER)

ring-buffer-reset buffer => end-index Reset match beginning/end indices USED and NEW in BUFFER to START and END.

RING-BUFFER-START (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

RING-BUFFER-USED (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

RING-BUFFER-VECTOR (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

ROOT-NODES (NODES)

root-nodes nodes => node-list Return all root nodes in NODES. Root nodes are identified by not being referenced as a dependency by any other node. This is done by building the difference (complement of intersection) between the ones having dependencies and the complete set.

SAFE-FORMAT (LOCK DESTINATION CONTROL-STRING &REST FORMAT-ARGUMENTS)

safe-format lock control-string &rest format-arguments => nil Mutex-protected FORMAT.

SAFE-GETENV (LOCK VAR)

safe-getenv lock var => result Mutex-protected GETENV.

SPLIT-COMMANDLINE (CMD)

split-commandline cmd => list Split command line string cmd into arguments accourding to Bourne shell syntax rules honoring double quotes ["], single quotes ['] and regular whitespace.

STRINGIFY (OBJECT)

stringify object => string If OBJECT is a STRING, return it - else cast WRITE-TO-STRING.

TRIM-{} (STRING)

trim-{} string => string Trims {} brackets strings.

UNIX-OPTIONS-OPTIONS

unix-options-options => (bool-options parameter-options) Transform *OPTIONS* so that they are suitable for use with UNIX-OPTIONS:MAP-PARSED-OPTIONS.

Undocumented

COPY-RING-BUFFER (INSTANCE)

MAKE-RING-BUFFER (&KEY ((VECTOR DUM0) NIL) ((START DUM1) -1) ((USED DUM2) -1) ((NEW DUM3) -1) ((END DUM4) -1))

SETFRING-BUFFER-END (NEW-VALUE INSTANCE)

SETFRING-BUFFER-NEW (NEW-VALUE INSTANCE)

RING-BUFFER-P (OBJECT)

SETFRING-BUFFER-START (NEW-VALUE INSTANCE)

SETFRING-BUFFER-USED (NEW-VALUE INSTANCE)

SETFRING-BUFFER-VECTOR (NEW-VALUE INSTANCE)

MACRO

Public

DEFENV (VAR VAL &OPTIONAL (ENVIRONMENT '*ENVIRONMENT*))

defenv var val &optional environment => val Store val for key var in hash environment.

Private

DEFAULT (NAME)

default name => mixed Top-level syntactic sugar macro to set the default evolvable to name.

DEVOLUTION (NAME (&BODY DEPENDENCIES) &REST ARGS &KEY TYPE &ALLOW-OTHER-KEYS)

devolution name &rest args &key type &allow-other-keys => object Top-level syntactic sugar macro to create evolvables. Name will be the environmental hash key, :TYPE must be a valid class name and all other keys will be proxied to MAKE-INSTANCE.

EVAL-REVERSE-CONS ((&BODY BODY1) (&BODY BODY2))

eval-reverse-cons (&body body1) (&body body2) => cons Evaluate BODY2 and BODY1 in this order and return result cons [BODY1|BODY2].

GETF-OPTION (OPTION KEYWORD)

getf-option option keyword => result GETF for options.

RESOLVE-COND (NAME NODES SEEN (&BODY PROLOGUE) &BODY EPILOGUE)

resolve-cond name nodes seen (&body prologue) &body epilogue => context Insert COND clauses between PROLOGUE clauses and EPILOGUE final clause that check for erroneous conditions between the NAME of a node, the list of all NODES and nodes SEEN during dependency resolution and signal errors accordingly if encountered.

SYMBOLIZE (NAME)

symbolize name => symbol Quotes, transforms and interns unquoted variable names.

WITH-DEPENDENCY-NODES (VAR &BODY BODY)

with-dependency-nodes var &body body => context Evaluate BODY in scope of VAR bound to dependency node list.

WITH-NEW-LOCK-HELD (VAR &BODY BODY)

with-new-lock-held var &body body => context Evaluate BODY in locked scope of VAR bound to a new mutex with random name.

WITH-OUTPUTS-TO-STRINGS ((&REST VARS) &BODY FORMS-DECLS)

with-outputs-to-strings (&rest vars) &body forms-decls => (result string1 .. stringN) The multi-version of WITH-OUTPUT-TO-STRING preserving original return values. Evaluate FORMS-DECLS with each element in VARS bound to a fresh open stream. Return multiple VALUES of FORMS-DECLS evaluation result and one string per VARS in given argument order.

WITH-SLOT-ENHANCED-ENVIRONMENT ((SLOTS OBJECT) &BODY BODY)

with-slot-enhanced-environment (slots object) body => context Create lexical context overriding *ENVIRONMENT* with a fresh copy enhanced by all slot names/values as key/values from symbol list SLOTS in OBJECT.

GENERIC-FUNCTION

Private

BREED (BREEDER EVOLVABLE)

Breed the evolvable so it can hatch

ENQUEUE-BREEDING (SWARM EVOLVABLE)

Push breeding an evolvable into the worker queue and wait for the job to finish

EVOLVE (EVOLVABLE &REST ARGS &ALLOW-OTHER-KEYS)

Evolve this, whatever that may be

EVOLVED-P (CHECKABLE)

Check that given evolution has been evolved properly

EXPAND (STANDARD-OBJECT)

expand standard-object => string Return a suitable form of the object for %-style rule expansion. Defined here to prevent circular dependencies.

RESET (EVOLVABLE)

reset evolvable => result Reset evolution of EVOLVABLE.

Undocumented

CIRCULAR-INTER-NODES (CONDITION)

CIRCULAR-NODE (CONDITION)

COMMAND-FAILURE-CODE (CONDITION)

COMMAND-FAILURE-COMMAND (CONDITION)

COMMAND-FAILURE-STDERR (CONDITION)

COMMAND-FAILURE-STDOUT (CONDITION)

ILLEGAL-EVOLVABLE (CONDITION)

UNLOADABLE-EVOLUTION-PATHNAME (CONDITION)

UNRESOLVABLE-DEPENDENCY (CONDITION)

UNRESOLVABLE-NODE (CONDITION)

SLOT-ACCESSOR

Private

CL-PACKAGES (OBJECT)

Package to load before creating heap image.

SETFCL-PACKAGES (NEW-VALUE OBJECT)

Package to load before creating heap image.

CL-SAVE-OPTIONS (OBJECT)

Additional arguments to pass to the implementation-dependent save call.

SETFCL-SAVE-OPTIONS (NEW-VALUE OBJECT)

Additional arguments to pass to the implementation-dependent save call.

DEPENDENCIES (OBJECT)

List of evolvables this one depends on

SETFDEPENDENCIES (NEW-VALUE OBJECT)

List of evolvables this one depends on

ENV-SLOTS (OBJECT)

List of slots to lexically bind to the environment during evolution

SETFENV-SLOTS (NEW-VALUE OBJECT)

List of slots to lexically bind to the environment during evolution

HATCHED (OBJECT)

Whether evolution is finished

SETFHATCHED (NEW-VALUE OBJECT)

Whether evolution is finished

MUTEX (OBJECT)

Mutex for the wait queue

NAME (OBJECT)

The name of the evolvable, also available in evol's environment

RULE (OBJECT)

The rule used to evolve the definite

SETFRULE (NEW-VALUE OBJECT)

The rule used to evolve the definite

SOURCEFN (OBJECT)

Preinitialized for this class; returns a list of forms to first load asdf, then in turn additional asdf packages from rule and finally a form to have sbcl create a core file.

SETFSOURCEFN (NEW-VALUE OBJECT)

The function to compute the input from other slots like e.g. target and name

STREAM-LOCK (OBJECT)

Mutex to use for printing

SWARM-ERROR-STREAM (OBJECT)

Stream to use for printing errors

SWARM-STREAM (OBJECT)

Stream to use for printing

WAITQUEUE (OBJECT)

Wait queue used for multithreaded breeding

Undocumented

CL-IMPLEMENTATION (OBJECT)

SETFCL-IMPLEMENTATION (NEW-VALUE OBJECT)

VARIABLE

Public

Undocumented

*ENVIRONMENT*

Private

Undocumented

*DEFAULT-EVOLUTION*

*OPTIONS*

CLASS

Private

BREEDER

Solitary breeder class.

CHECKABLE

Evolvables derived from checkable provide a means to pre- and post-validate their evolution.

CL-CORE

This evolvable enables creation of non-standalone Common Lisp core (heap image) files. Feed rule with a list of asdf-recognized package symbols to load into the core.

CL-EXE

In line with cl-core, a complete dump is generated but with the engine fully runable contained within so the resulting file is a real executable. Feed rule with a list of asdf-recognized package symbols to load into the binary.

CL-TRANSFORMATOR

Evolution takes place here through running a freshly forked Common Lisp copy that expects rule to be a list of forms to execute in order. sourcefn is expected to return list of valid Common Lisp forms that will each be grouped as a single argument to be passed to (eval) so no special quoting aside from \" is required. Variable expansion is only performed against sourcefn's return forms.

DEFINITE

Definite evolvables define transformation rules and computation of their effective input(s) to evolve, possibly from some kind of sources.

EVOLVABLE

Base class for all evolvables.

EXECUTABLE

Executables are files that can be run on a machine's stack by either containing machince code themselves or referring to an interpreter for source code contained within. This class ensures its file is executable after creation.

FILE

Files are targets that usually lead to evolution of... files. Their existence can easily be checked through their distinct pathnames.

GENERIC

TODO

GENERIC-TRANSFORMATOR

Objects of this kind evolve through running an external program through interpolating the rule and source function contained within honoring common quoting rules in line with Bourne shell syntax.

HIVE

Hives are similar to virtuals but enable mass spawning of evolvables they auto-depend on so depending on a hive saves from declaring lots of mutual evolvables manually.

PROGRAM

TODO

RING-BUFFER

Structure defining ring buffers utilizing a simple VECTOR of fixed size and four indices: START: Index of first live value END: Index of last live value USED: Beginning of current match NEW: End of current match

SWARM

Swarms are breeders that heavily rely on threading and also derive from Patron for thread-pooled queue working.

VIRTUAL

Virtual evolvables exist for the sole purpose of beautification through grouping and/or naming by having its dependencies evolve.

CONDITION

Private

COMMAND-FAILURE

Condition signalled if invocation of an external command failed.

Undocumented

CIRCULAR-DEPENDENCY

ILLEGAL-EVOLVABLE (CONDITION)

UNEMPLOYMENT

UNLOADABLE-EVOLUTION

UNRESOLVABLE-DEPENDENCY (CONDITION)