X-Git-Url: https://code.consxy.com/gitweb/?a=blobdiff_plain;f=src%2Fmain%2Fbase.lisp;h=74b35a2c37945ff696d336140369ea090b9389ac;hb=3f51764d1e808faae658768fd01e4fff87a5ab01;hp=e47c0fb8858318e145c107b349f0253fc9eff3bf;hpb=90a0214bc3b5136af1c0d88ca11e5afe3564c1fc;p=candle

diff --git a/src/main/base.lisp b/src/main/base.lisp
index e47c0fb..74b35a2 100644
--- a/src/main/base.lisp
+++ b/src/main/base.lisp
@@ -1,6 +1,67 @@
 (in-package #:candle)
 
-(defvar *candle-dir*)
+(defvar *candle-dir* nil
+ "*CANDLE-DIR*
+
+VALUE TYPE:
+
+  A pathname or pathstring
+
+INITIAL VALUE:
+
+  NIL
+
+DESCRIPTION:
+
+  The main directory for all candle work to be done in.  When the server is running
+  in local mode, this is also the place that builds are built in")
+
+(defvar *environment* :local
+ "*ENVIRONMENT*
+
+VALUE TYPE:
+
+  A keyword
+
+INITIAL VALUE:
+
+  :LOCAL
+
+DESCRIPTION:
+
+  The environment that candle is currently running.  Useful to do switching in tests
+  or in the .candle file to do extra boot up processing.")
+
+(define-condition candle-error (error)
+ ((reason :initarg :reason :reader candle-error-reason))
+ (:documentation
+  "An error on the server that needs to be handled in the client.
+
+This error is usually because some input was incorrect.  The response will
+have a reason that is a keyword that must be handled.  The current used keywords
+are:
+
+- :project-does-not-exist - if the project isn't in the database
+- :invalid-project-name - the specified name doesn't match the requirements
+- :invlides-project-uri - the uri isn't reachable by git
+- :project-name-taken - name is a duplicate
+- :project-failed-to-get-branches - when refreshing fails
+- :job-does-not-exist - the specified job can't be found"))
+
+(setf (documentation 'candle-error-reason 'function)
+ "CANDLE-ERROR-REASON CANDLE-ERROR => REASON
+
+ARGUMENTS AND VALUES:
+
+  CANDLE-ERROR: the error for the reason
+  REASON: a keyword representing the reason
+
+DESCRIPTION:
+
+  Returns the reason for this candle error.  See the documentation of
+  the candle-error condition for possible values")
+
+(defun raise-candle-error (reason) (error (make-instance 'candle-error :reason reason)))
 
 (lame-db:defdbstruct project name src)
 
@@ -10,11 +71,46 @@
 ; - :succeeded - job succeeded
 ; - :no-candle-file - no candle file was found
 ; - :in-progress - job is running
-(lame-db:defdbstruct job status sha when-run (project :join project))
+(lame-db:defdbstruct job status sha create-date log (project :join project))
+
+(setf (documentation 'job-project 'function)
+ "JOB-PROJECT JOB => PROJECT
+
+ARGUMENTS AND VALUES:
+
+  JOB: a job
+  PROJECT: the project for this job
+
+DESCRIPTION:
+
+  Returns the project for the job in question.")
 
 ; in-git here refers to whether the branch exists in git.  As branches get deleted,
 ; this will get set to nil but we keep them around for historical reference
 (lame-db:defdbstruct branch name in-git (project :join project) (job :join job))
 
+(setf (documentation 'project-name 'function)
+ "PROJECT-NAME PROJECT => NAME
+
+ARGUMENTS AND VALUES:
+
+  PROJECT: the project
+  NAME: a string, the name of the job
+
+DESCRIPTION:
+
+  Returns the name of the project in question.")
+
 (defun project-dir (project)
+ "PROJECT-DIR PROJECT => DIR
+
+ARGUMENTS AND VALUES:
+
+  PROJECT: the project
+  DIR: the working directory for the project
+
+DESCRIPTION:
+
+  Returns the checked out directory for this project, specifically for use
+  in candle.  Resides in the *CANDLE-DIR*."
  (format nil "~Arepos/~A/" *candle-dir* (project-name project)))