Browse Source

Sol Part 48: I'M THE REAL ME SHOOT THE OTHER GUY

Graham Northup 5 years ago
parent
commit
5fb468605e
Signed by: Grissess <grissess@nexusg.org> GPG Key ID: 5D000E6F539376FB
1 changed files with 46 additions and 1 deletions
  1. 46
    1
      sol.h

+ 46
- 1
sol.h View File

@@ -107,7 +107,7 @@ typedef struct {
107 107
 	sol_cfunc_t mod;
108 108
 	/** Called with [this, rhs] to perform binary exponentiation ("**"). */
109 109
 	sol_cfunc_t pow;
110
-	/** TODO: document me!*/
110
+	/** Called with [this, rhs] to perform the triple-bang operation ("!!!"), defaults to identity-swapping two objects. */
111 111
 	sol_cfunc_t tbang;
112 112
 	/** Called with [this, rhs] to perform binary bitwise AND ("&") */
113 113
 	sol_cfunc_t band;
@@ -862,28 +862,73 @@ sol_object_t *sol_f_stream_open(sol_state_t *, sol_object_t *);
862 862
 
863 863
 #define sol_has_error(state) (!sol_is_none((state), (state)->error))
864 864
 
865
+/** Creates a new singlet object with the specified name (or NULL).
866
+ *
867
+ * Singlets are special objects that are equal only by identity. They are used
868
+ * wherever a particular value has special meaning (e.g. None).  Other than
869
+ * that, their lack of function makes them difficult to manipulate, and many
870
+ * internal routines are special-cased for certain singlets.
871
+ */
865 872
 sol_object_t *sol_new_singlet(sol_state_t *, const char *);
873
+/** Creates a new integer object with the specified value. */
866 874
 sol_object_t *sol_new_int(sol_state_t *, long);
875
+/** Creates a new float object with the specified value. */
867 876
 sol_object_t *sol_new_float(sol_state_t *, double);
868 877
 
878
+/** Creates a new string object with the specified value. */
869 879
 sol_object_t *sol_new_string(sol_state_t *, const char *);
880
+/** Utility function to compare a Sol string and a C string, used often in
881
+ *   builtin and extension code. */
870 882
 int sol_string_cmp(sol_state_t *, sol_object_t *, const char *);
883
+/** Utility macro wrapping `sol_string_cmp`. */
871 884
 #define sol_string_eq(state, string, cstr) (sol_string_cmp((state), (string), (cstr))==0)
885
+/** Internal routine that returns a new Sol string that results from the
886
+ *   concatenation of two Sol strings (in the order given). */
872 887
 sol_object_t *sol_string_concat(sol_state_t *, sol_object_t *, sol_object_t *);
888
+/** Utility function for conveniently concatenating a Sol string and a C string
889
+ *   (and returning a Sol string). */
873 890
 sol_object_t *sol_string_concat_cstr(sol_state_t *, sol_object_t *, char *);
874 891
 
892
+/** Creates a new empty Sol list. */
875 893
 sol_object_t *sol_new_list(sol_state_t *);
894
+/** Creates a new Sol list populated with objects obtained by iterating over a
895
+ *   DSL sequence. */
876 896
 sol_object_t *sol_list_from_seq(sol_state_t *, dsl_seq *);
897
+/** Internal routine to get the length of a Sol list */
877 898
 int sol_list_len(sol_state_t *, sol_object_t *);
899
+/** Internal routine to return a new Sol list equivalent to its input with the
900
+ *   first n elements skipped. */
878 901
 sol_object_t *sol_list_sublist(sol_state_t *, sol_object_t *, int);
902
+/** Internal routine to get the object at the specified index in a Sol list. */
879 903
 sol_object_t *sol_list_get_index(sol_state_t *, sol_object_t *, int);
904
+/** Internal routine to set the object at the specified index in a Sol list. */
880 905
 void sol_list_set_index(sol_state_t *, sol_object_t *, int, sol_object_t *);
906
+/** Internal routine to insert an object at the specified index in a Sol list.
907
+ *
908
+ * Unlike setting, insertion may happen at the lists length, inclusive (in
909
+ * which case it appends an element). When this routine returns successfully
910
+ * (without an error on the state), the index specified should hold a reference
911
+ * to the object given as a parameter.
912
+ */
881 913
 void sol_list_insert(sol_state_t *, sol_object_t *, int, sol_object_t *);
914
+/** Internal routine to remove an object at the specified index in a Sol list,
915
+ *   returning a reference to that object. */
882 916
 sol_object_t *sol_list_remove(sol_state_t *, sol_object_t *, int);
917
+/** Internal routine to return a copy of a Sol list.
918
+ *
919
+ * Note that this performs a "shallow" copy, in that while the new list is a
920
+ * different reference, the references inside the list are the same.
921
+ */
883 922
 sol_object_t *sol_list_copy(sol_state_t *, sol_object_t *);
923
+/** Internal routine to return a new Sol list equivalent to its input up to the
924
+ *   first n elements. */
884 925
 sol_object_t *sol_list_truncate(sol_state_t *, sol_object_t *, int);
926
+/** Utility routine to insert at the end of a Sol list. */
885 927
 void sol_list_append(sol_state_t *, sol_object_t *, sol_object_t *);
928
+/** Utility macro to insert an object at the beginning of a Sol list. */
886 929
 #define sol_list_push(st, ls, obj) sol_list_insert(st, ls, 0, obj);
930
+/** Utility macro to remove and return the object at the beginning of a Sol
931
+ *   list. */
887 932
 #define sol_list_pop(st, ls) sol_list_remove(st, ls, 0);
888 933
 
889 934
 sol_object_t *sol_new_map(sol_state_t *);

Loading…
Cancel
Save