mirror of
https://github.com/janet-lang/janet
synced 2025-01-10 23:50:26 +00:00
Add a lot of documentation for functions.
This commit is contained in:
Calvin Rose
parent
c9f76d2673
commit
945b72468c
3
Makefile
3
Makefile
@ -31,8 +31,7 @@ JANET_VERSION?="\"commit-$(shell git log --pretty=format:'%h' -n 1)\""
|
||||
|
||||
#CFLAGS=-std=c99 -Wall -Wextra -Isrc/include -fpic -g
|
||||
CFLAGS=-std=c99 -Wall -Wextra -Isrc/include -fpic -O2 -fvisibility=hidden \
|
||||
-DJANET_VERSION=$(JANET_VERSION) \
|
||||
-DJANET_NONANBOX
|
||||
-DJANET_VERSION=$(JANET_VERSION)
|
||||
CLIBS=-lm -ldl
|
||||
JANET_TARGET=janet
|
||||
JANET_LIBRARY=libjanet.so
|
||||
|
||||
@ -231,12 +231,12 @@ static int cfun_concat(JanetArgs args) {
|
||||
static const JanetReg cfuns[] = {
|
||||
{"array.new", cfun_new,
|
||||
"(array.new capacity)\n\n"
|
||||
"Creates a new empty array with a preallocated capacity. The same as\n"
|
||||
"Creates a new empty array with a preallocated capacity. The same as "
|
||||
"(array) but can be more efficient if the maximum size of an array is known."
|
||||
},
|
||||
{"array.pop", cfun_pop,
|
||||
"(array.pop arr)\n\n"
|
||||
"Remove the last element of the array and return it. If the array is empty, will return nil. Modifies\n"
|
||||
"Remove the last element of the array and return it. If the array is empty, will return nil. Modifies "
|
||||
"the input array."
|
||||
},
|
||||
{"array.peek", cfun_peek,
|
||||
@ -249,28 +249,28 @@ static const JanetReg cfuns[] = {
|
||||
},
|
||||
{"array.ensure", cfun_ensure,
|
||||
"(array.ensure arr capacity)\n\n"
|
||||
"Ensures that the memory backing the array has enough memory for capacity\n"
|
||||
"items. Capacity must be an integer. If the backing capacity is already enough,\n"
|
||||
"then this function does nothing. Otherwise, the backing memory will be reallocated\n"
|
||||
"Ensures that the memory backing the array has enough memory for capacity "
|
||||
"items. Capacity must be an integer. If the backing capacity is already enough, "
|
||||
"then this function does nothing. Otherwise, the backing memory will be reallocated "
|
||||
"so that there is enough space."
|
||||
},
|
||||
{"array.slice", cfun_slice,
|
||||
"(array.slice arrtup)\n\n"
|
||||
"Returns a copy of an array or tuple.\n\n"
|
||||
"(array.slice arrtup start)\n\n"
|
||||
"Takes a slice of an array or tuple from the index start to the last element. Indexes\n"
|
||||
"are from 0, or can be negative to index from the end of the array, Where -1 is the last\n"
|
||||
"Takes a slice of an array or tuple from the index start to the last element. Indexes "
|
||||
"are from 0, or can be negative to index from the end of the array, Where -1 is the last "
|
||||
"element of the array. Returns a new array.\n\n"
|
||||
"(array.slice arrtup start end)\n\n"
|
||||
"Takes a slice of array or tuple from start to end. The range is half open,\n"
|
||||
"[start, end). Indexes can also be negative, indicating indexing from the end of the\n"
|
||||
"Takes a slice of array or tuple from start to end. The range is half open, "
|
||||
"[start, end). Indexes can also be negative, indicating indexing from the end of the "
|
||||
"end of the array. Returns a new array."
|
||||
},
|
||||
{"array.concat", cfun_concat,
|
||||
"(array.concat arr & parts)\n\n"
|
||||
"Concatenates a variadic number of arrays (and tuples) into the first argument\n"
|
||||
"which must an array. If any of the parts are arrays or tuples, their elements will\n"
|
||||
"be inserted into the array. Otherwise, each part in parts will be appended to arr in order.\n"
|
||||
"Concatenates a variadic number of arrays (and tuples) into the first argument "
|
||||
"which must an array. If any of the parts are arrays or tuples, their elements will "
|
||||
"be inserted into the array. Otherwise, each part in parts will be appended to arr in order. "
|
||||
"Return the modified array arr."
|
||||
},
|
||||
{NULL, NULL, NULL}
|
||||
|
||||
@ -225,6 +225,7 @@ static int cfun_popn(JanetArgs args) {
|
||||
JANET_FIXARITY(args, 2);
|
||||
JANET_ARG_BUFFER(buffer, args, 0);
|
||||
JANET_ARG_INTEGER(n, args, 1);
|
||||
if (n < 0) JANET_THROW(args, "n must be non-negative");
|
||||
if (buffer->count < n) {
|
||||
buffer->count = 0;
|
||||
} else {
|
||||
@ -267,13 +268,49 @@ static int cfun_slice(JanetArgs args) {
|
||||
}
|
||||
|
||||
static const JanetReg cfuns[] = {
|
||||
{"buffer.new", cfun_new, NULL},
|
||||
{"buffer.push-byte", cfun_u8, NULL},
|
||||
{"buffer.push-integer", cfun_int, NULL},
|
||||
{"buffer.push-string", cfun_chars, NULL},
|
||||
{"buffer.popn", cfun_popn, NULL},
|
||||
{"buffer.clear", cfun_clear, NULL},
|
||||
{"buffer.slice", cfun_slice, NULL},
|
||||
{"buffer.new", cfun_new,
|
||||
"(buffer.new capacity)\n\n"
|
||||
"Creates a new, empty buffer with enough memory for capacity bytes. "
|
||||
"Returns a new buffer."
|
||||
},
|
||||
{"buffer.push-byte", cfun_u8,
|
||||
"(buffer.push-byte buffer x)\n\n"
|
||||
"Append a byte to a buffer. Will expand the buffer as necessary. "
|
||||
"Returns the modified buffer. Will throw an error if the buffer overflows."
|
||||
},
|
||||
{"buffer.push-integer", cfun_int,
|
||||
"(buffer.push-integer buffer x)\n\n"
|
||||
"Append an integer to a buffer. The 4 bytes of the integer are appended "
|
||||
"in twos complement, big endian order. Returns the modified buffer. Will "
|
||||
"throw an error if the buffer overflows."
|
||||
},
|
||||
{"buffer.push-string", cfun_chars,
|
||||
"(buffer.push-string buffer str)\n\n"
|
||||
"Push a string onto the end of a buffer. Non string values will be converted "
|
||||
"to strings before being pushed. Returns the modified buffer. "
|
||||
"Will throw an error if the buffer overflows."
|
||||
},
|
||||
{"buffer.popn", cfun_popn,
|
||||
"(buffer.popn buffer n)\n\n"
|
||||
"Removes the last n bytes from the buffer. Returns the modified buffer."
|
||||
},
|
||||
{"buffer.clear", cfun_clear,
|
||||
"(buffer.clear buffer)\n\n"
|
||||
"Sets the size of a buffer to 0 and empties it. The buffer retains "
|
||||
"its memory so it can be efficiently refilled. Returns the modified buffer."
|
||||
},
|
||||
{"buffer.slice", cfun_slice,
|
||||
"(buffer.slice bytes)\n\n"
|
||||
"Returns a copy of a buffer, string or symbol.\n\n"
|
||||
"(buffer.slice bytes start)\n\n"
|
||||
"Takes a slice of a byte sequence from the index start to the last element. Indexes "
|
||||
"are from 0, or can be negative to index from the end of the array, Where -1 is the last "
|
||||
"element of the array. Returns a new buffer.\n\n"
|
||||
"(buffer.slice bytes start end)\n\n"
|
||||
"Takes a slice of a byte sequence from start to end. The range is half open, "
|
||||
"[start, end). Indexes can also be negative, indicating indexing from the end of the "
|
||||
"end of the array. Returns a new buffer."
|
||||
},
|
||||
{NULL, NULL, NULL}
|
||||
};
|
||||
|
||||
|
||||
@ -706,7 +706,13 @@ static int cfun(JanetArgs args) {
|
||||
}
|
||||
|
||||
static const JanetReg cfuns[] = {
|
||||
{"compile", cfun, NULL},
|
||||
{"compile", cfun,
|
||||
"(compile ast)\n\n"
|
||||
"Compiles an Abstract Sytnax Tree (ast) into a janet function. "
|
||||
"Pair the compile function with parsing functionality to implement "
|
||||
"eval. Returns a janet function and does not modify ast. Throws an "
|
||||
"error if the ast cannot be compiled."
|
||||
},
|
||||
{NULL, NULL, NULL}
|
||||
};
|
||||
|
||||
|
||||
@ -25,7 +25,7 @@
|
||||
(def array? (= t :array))
|
||||
(if (if tuple? tuple? array?)
|
||||
i
|
||||
(do
|
||||
(do
|
||||
(if (= (type ith) :string)
|
||||
(:= docstr ith)
|
||||
(array.push modifiers ith))
|
||||
@ -94,7 +94,7 @@
|
||||
(defn fiber? "Check if x is a fiber." [x] (= (type x) :fiber))
|
||||
(defn string? "Check if x is a string." [x] (= (type x) :string))
|
||||
(defn symbol? "Check if x is a symbol." [x] (= (type x) :symbol))
|
||||
(defn keyword? "Check if x is a keyword style symbol."
|
||||
(defn keyword? "Check if x is a keyword style symbol."
|
||||
[x]
|
||||
(if (not= (type x) :symbol) nil (= 58 (get x 0))))
|
||||
(defn buffer? "Check if x is a buffer." [x] (= (type x) :buffer))
|
||||
@ -190,21 +190,6 @@
|
||||
(aux (+ i 2))))))
|
||||
(aux 0))
|
||||
|
||||
(defn doc*
|
||||
"Get the documentation for a symbol in a given environment."
|
||||
[env sym]
|
||||
(def x (get env sym))
|
||||
(if (not x)
|
||||
(print "symbol " sym " not found.")
|
||||
(do
|
||||
(def d (get x :doc))
|
||||
(print "\n" (if d d "no documentation found.") "\n"))))
|
||||
|
||||
(defmacro doc
|
||||
"Shows documentation for the given symbol."
|
||||
[sym]
|
||||
(tuple doc* '_env (tuple 'quote sym)))
|
||||
|
||||
(defmacro case
|
||||
"Select the body that equals the dispatch value. When pairs
|
||||
has an odd number of arguments, the last is the default expression.
|
||||
@ -917,6 +902,69 @@ value, one key will be ignored."
|
||||
(file.write file buf)
|
||||
nil)
|
||||
|
||||
###
|
||||
###
|
||||
### Documentation
|
||||
###
|
||||
###
|
||||
|
||||
(var *doc-width*
|
||||
"Width in columns to print documentation."
|
||||
80)
|
||||
|
||||
(defn doc-format
|
||||
"Reformat text to wrap at a given line."
|
||||
[text]
|
||||
|
||||
(def maxcol (- *doc-width* 8))
|
||||
(var buf @" ")
|
||||
(var word @"")
|
||||
(var current 0)
|
||||
|
||||
(defn pushword
|
||||
[]
|
||||
(def oldcur current)
|
||||
(def spacer
|
||||
(if (<= maxcol (+ current (length word) 1))
|
||||
(do (:= current 0) "\n ")
|
||||
(do (++ current) " ")))
|
||||
(+= current (length word))
|
||||
(if (> oldcur 0)
|
||||
(buffer.push-string buf spacer))
|
||||
(buffer.push-string buf word)
|
||||
(buffer.clear word))
|
||||
|
||||
(loop [b :in text]
|
||||
(if (and (not= b 10) (not= b 32))
|
||||
(if (= b 9)
|
||||
(buffer.push-string word " ")
|
||||
(buffer.push-byte word b))
|
||||
(do
|
||||
(if (> (length word) 0) (pushword))
|
||||
(when (= b 10)
|
||||
(buffer.push-string buf "\n ")
|
||||
(:= current 0)))))
|
||||
|
||||
# Last word
|
||||
(pushword)
|
||||
|
||||
buf)
|
||||
|
||||
(defn doc*
|
||||
"Get the documentation for a symbol in a given environment."
|
||||
[env sym]
|
||||
(def x (get env sym))
|
||||
(if (not x)
|
||||
(print "symbol " sym " not found.")
|
||||
(do
|
||||
(def d (get x :doc))
|
||||
(print "\n\n" (if d (doc-format d) "no documentation found.") "\n\n"))))
|
||||
|
||||
(defmacro doc
|
||||
"Shows documentation for the given symbol."
|
||||
[sym]
|
||||
(tuple doc* '_env (tuple 'quote sym)))
|
||||
|
||||
###
|
||||
###
|
||||
### Macro Expansion
|
||||
@ -946,8 +994,8 @@ value, one key will be ignored."
|
||||
(defn expanddef [t]
|
||||
(def last (get t (- (length t) 1)))
|
||||
(def bound (get t 1))
|
||||
(tuple.slice
|
||||
(array.concat
|
||||
(tuple.slice
|
||||
(array.concat
|
||||
@[(get t 0) (expand-bindings bound)]
|
||||
(tuple.slice t 2 -2)
|
||||
@[(macroexpand-1 last)])
|
||||
|
||||
@ -155,9 +155,6 @@ static int janet_core_scannumber(JanetArgs args) {
|
||||
JANET_FIXARITY(args, 1);
|
||||
JANET_ARG_BYTES(data, len, args, 0);
|
||||
x = janet_scan_number(data, len);
|
||||
if (janet_checktype(x, JANET_NIL)) {
|
||||
JANET_THROW(args, "error parsing number");
|
||||
}
|
||||
JANET_RETURN(args, x);
|
||||
}
|
||||
|
||||
@ -169,7 +166,7 @@ static int janet_core_scaninteger(JanetArgs args) {
|
||||
JANET_ARG_BYTES(data, len, args, 0);
|
||||
ret = janet_scan_integer(data, len, &err);
|
||||
if (err) {
|
||||
JANET_THROW(args, "error parsing integer");
|
||||
JANET_RETURN_NIL(args);
|
||||
}
|
||||
JANET_RETURN_INTEGER(args, ret);
|
||||
}
|
||||
@ -183,7 +180,7 @@ static int janet_core_scanreal(JanetArgs args) {
|
||||
JANET_ARG_BYTES(data, len, args, 0);
|
||||
ret = janet_scan_real(data, len, &err);
|
||||
if (err) {
|
||||
JANET_THROW(args, "error parsing real");
|
||||
JANET_RETURN_NIL(args);
|
||||
}
|
||||
JANET_RETURN_REAL(args, ret);
|
||||
}
|
||||
@ -287,27 +284,136 @@ static int janet_core_hash(JanetArgs args) {
|
||||
}
|
||||
|
||||
static const JanetReg cfuns[] = {
|
||||
{"native", janet_core_native, NULL},
|
||||
{"print", janet_core_print, NULL},
|
||||
{"describe", janet_core_describe, NULL},
|
||||
{"string", janet_core_string, NULL},
|
||||
{"symbol", janet_core_symbol, NULL},
|
||||
{"buffer", janet_core_buffer, NULL},
|
||||
{"table", janet_core_table, NULL},
|
||||
{"array", janet_core_array, NULL},
|
||||
{"scan-number", janet_core_scannumber, NULL},
|
||||
{"scan-integer", janet_core_scaninteger, NULL},
|
||||
{"scan-real", janet_core_scanreal, NULL},
|
||||
{"tuple", janet_core_tuple, NULL},
|
||||
{"struct", janet_core_struct, NULL},
|
||||
{"buffer", janet_core_buffer, NULL},
|
||||
{"gensym", janet_core_gensym, NULL},
|
||||
{"gccollect", janet_core_gccollect, NULL},
|
||||
{"gcsetinterval", janet_core_gcsetinterval, NULL},
|
||||
{"gcinterval", janet_core_gcinterval, NULL},
|
||||
{"type", janet_core_type, NULL},
|
||||
{"next", janet_core_next, NULL},
|
||||
{"hash", janet_core_hash, NULL},
|
||||
{"native", janet_core_native,
|
||||
"(native path)\n\n"
|
||||
"Load a native module from the given path. The path "
|
||||
"must be an absolute or relative path on the filesystem, and is "
|
||||
"usually a .so file on unix systems, and a .dll file on Windows. "
|
||||
"Returns an environment table that contains functions and other values "
|
||||
"from the native module."
|
||||
},
|
||||
{"print", janet_core_print,
|
||||
"(print & xs)\n\n"
|
||||
"Print values to the console (standard out). Value are converted "
|
||||
"to strings if they are not already. After printing all values, a "
|
||||
"newline character is printed. Returns nil."
|
||||
},
|
||||
{"describe", janet_core_describe,
|
||||
"(describe x)\n\n"
|
||||
"Returns a string that is a human readable description of a value x."
|
||||
},
|
||||
{"string", janet_core_string,
|
||||
"(string & parts)\n\n"
|
||||
"Creates a string by concatenating values together. Values are "
|
||||
"converted to bytes via describe if they are not byte sequences. "
|
||||
"Returns the new string."
|
||||
},
|
||||
{"symbol", janet_core_symbol,
|
||||
"(symbol & xs)\n\n"
|
||||
"Creates a symbol by concatenating values together. Values are "
|
||||
"converted to bytes via describe if they are not byte sequences. Returns "
|
||||
"the new symbol."
|
||||
},
|
||||
{"buffer", janet_core_buffer,
|
||||
"(buffer & xs)\n\n"
|
||||
"Creates a new buffer by concatenating values together. Values are "
|
||||
"converted to bytes via describe if they are not byte sequences. Returns "
|
||||
"the new symbol."
|
||||
},
|
||||
{"table", janet_core_table,
|
||||
"(table & kvs)\n\n"
|
||||
"Creates a new table from a variadic number of keys and values. "
|
||||
"kvs is a sequence k1, v1, k2, v2, k3, v3, ... If kvs has "
|
||||
"an odd number of elements, an error will be thrown. Returns the "
|
||||
"new table."
|
||||
},
|
||||
{"array", janet_core_array,
|
||||
"(array & items)\n\n"
|
||||
"Create a new array that contains items. Returns the new array."
|
||||
},
|
||||
{"scan-number", janet_core_scannumber,
|
||||
"(scan-number str)\n\n"
|
||||
"Parse a number from a byte sequence an return that number, either and integer "
|
||||
"or a real. The number "
|
||||
"must be in the same format as numbers in janet source code. Will return nil "
|
||||
"on an invalid number."
|
||||
},
|
||||
{"scan-integer", janet_core_scaninteger,
|
||||
"(scan-integer str)\n\n"
|
||||
"Parse an integer from a byte sequence an return that number. The integer "
|
||||
"must be in the same format as integers in janet source code. Will return nil "
|
||||
"on an invalid integer."
|
||||
},
|
||||
{"scan-real", janet_core_scanreal,
|
||||
"(scan-real str)\n\n"
|
||||
"Parse a real number from a byte sequence an return that number. The number "
|
||||
"must be in the same format as numbers in janet source code. Will return nil "
|
||||
"on an invalid number."
|
||||
},
|
||||
{"tuple", janet_core_tuple,
|
||||
"(tuple & items)\n\n"
|
||||
"Creates a new tuple that contains items. Returns the new tuple."
|
||||
},
|
||||
{"struct", janet_core_struct,
|
||||
"(struct & kvs)\n\n"
|
||||
"Create a new struct from a sequence of key value pairs. "
|
||||
"kvs is a sequence k1, v1, k2, v2, k3, v3, ... If kvs has "
|
||||
"an odd number of elements, an error will be thrown. Returns the "
|
||||
"new struct."
|
||||
},
|
||||
{"gensym", janet_core_gensym,
|
||||
"(gensym)\n\n"
|
||||
"Returns a new symbol that is unique across the runtime. This means it "
|
||||
"will not collide with any already created symbols during compilation, so "
|
||||
"it can be used in macros to generate automatic bindings."
|
||||
},
|
||||
{"gccollect", janet_core_gccollect,
|
||||
"(gccollect)\n\n"
|
||||
"Run garbage collection. You should probably not call this manually."
|
||||
},
|
||||
{"gcsetinterval", janet_core_gcsetinterval,
|
||||
"(gcsetinterval interval)\n\n"
|
||||
"Set an integer number of bytes to allocate before running garbage collection. "
|
||||
"Low values interval will be slower but use less memory. "
|
||||
"High values will be faster but use more memory."
|
||||
},
|
||||
{"gcinterval", janet_core_gcinterval,
|
||||
"(gcinterval)\n\n"
|
||||
"Returns the integer number of bytes to allocate before running an iteration "
|
||||
"of garbage collection."
|
||||
},
|
||||
{"type", janet_core_type,
|
||||
"(type x)\n\n"
|
||||
"Returns the type of x as a keyword symbol. x is one of\n"
|
||||
"\t:nil\n"
|
||||
"\t:boolean\n"
|
||||
"\t:integer\n"
|
||||
"\t:real\n"
|
||||
"\t:array\n"
|
||||
"\t:tuple\n"
|
||||
"\t:table\n"
|
||||
"\t:struct\n"
|
||||
"\t:string\n"
|
||||
"\t:buffer\n"
|
||||
"\t:symbol\n"
|
||||
"\t:abstract\n"
|
||||
"\t:function\n"
|
||||
"\t:cfunction"
|
||||
},
|
||||
{"next", janet_core_next,
|
||||
"(next dict key)\n\n"
|
||||
"Gets the next key in a struct or table. Can be used to iterate through "
|
||||
"the keys of a data structure in an unspecified order. Keys are guaranteed "
|
||||
"to be seen only once per iteration if they data structure is not mutated "
|
||||
"during iteration. If key is nil, next returns the first key. If next "
|
||||
"returns nil, there are no more keys to iterate through. "
|
||||
},
|
||||
{"hash", janet_core_hash,
|
||||
"(hash value)\n\n"
|
||||
"Gets a hash value for any janet value. The hash is an integer can be used "
|
||||
"as a cheap hash function for all janet objects. If two values are strictly equal, "
|
||||
"then they will have the same hash value."
|
||||
},
|
||||
{NULL, NULL, NULL}
|
||||
};
|
||||
|
||||
|
||||
@ -455,13 +455,71 @@ static int cfun_setmaxstack(JanetArgs args) {
|
||||
}
|
||||
|
||||
static const JanetReg cfuns[] = {
|
||||
{"fiber.new", cfun_new, NULL},
|
||||
{"fiber.status", cfun_status, NULL},
|
||||
{"fiber.stack", cfun_stack, NULL},
|
||||
{"fiber.current", cfun_current, NULL},
|
||||
{"fiber.lineage", cfun_lineage, NULL},
|
||||
{"fiber.maxstack", cfun_maxstack, NULL},
|
||||
{"fiber.setmaxstack", cfun_setmaxstack, NULL},
|
||||
{"fiber.new", cfun_new,
|
||||
"(fiber.new func [,sigmask])\n\n"
|
||||
"Create a new fiber with function body func. Can optionally "
|
||||
"take a set of signals to block from the current parent fiber "
|
||||
"when called. The mask is specified as symbol where each character "
|
||||
"is used to indicate a signal to block. "
|
||||
"For example, \n\n"
|
||||
"\t(fiber.new myfun :e123)\n\n"
|
||||
"blocks error signals and user signals 1, 2 and 3. The signals are "
|
||||
"as follows: \n\n"
|
||||
"\ta - block all signals\n"
|
||||
"\td - block debug signals\n"
|
||||
"\te - block error signals\n"
|
||||
"\tu - block user signals\n"
|
||||
"\ty - block yield signals\n"
|
||||
"\t0-9 - block a specific user signal"
|
||||
},
|
||||
{"fiber.status", cfun_status,
|
||||
"(fiber.status fib)\n\n"
|
||||
"Get the status of a fiber. The status will be one of:\n\n"
|
||||
"\t:dead - the fiber has finished\n"
|
||||
"\t:error - the fiber has errored out\n"
|
||||
"\t:debug - the fiber is suspended in debug mode\n"
|
||||
"\t:pending - the fiber has been yielded\n"
|
||||
"\t:user(0-9) - the fiber is suspended by a user signal\n"
|
||||
"\t:alive - the fiber is currently running and cannot be resumed\n"
|
||||
"\t:new - the fiber has just been created and not yet run\n"
|
||||
},
|
||||
{"fiber.stack", cfun_stack,
|
||||
"(fiber.stack fib)\n\n"
|
||||
"Gets information about the stack as an array of tables. Each table "
|
||||
"in the array contains information about a stack frame. The top most, current "
|
||||
"stack frame is the first table in the array, and the bottom most stack frame "
|
||||
"is the last value. Each stack frame contains some of the following attributes:\n\n"
|
||||
"\t:c - true if the stack frame is a c function invokation\n"
|
||||
"\t:column - the current source column of the stack frame\n"
|
||||
"\t:function - the function that the stack frame represents\n"
|
||||
"\t:line - the current source line of the stack frame\n"
|
||||
"\t:name - the human friendly name of the function\n"
|
||||
"\t:pc - integer indicating the location of the program counter\n"
|
||||
"\t:source - string with filename or other identifier for the source code\n"
|
||||
"\t:tail - boolean indicating a tail call\n"
|
||||
},
|
||||
{"fiber.current", cfun_current,
|
||||
"(fiber.current)\n\n"
|
||||
"Returns the currently running fiber."
|
||||
},
|
||||
{"fiber.lineage", cfun_lineage,
|
||||
"(fiber.lineage fib)\n\n"
|
||||
"Returns an array of all child fibers from a root fiber. This function "
|
||||
"is useful when a fiber signals or errors to an ancestor fiber. Using this function, "
|
||||
"the fiber handling the error can see which fiber raised the signal. This function should "
|
||||
"be used mostly for debugging purposes."
|
||||
},
|
||||
{"fiber.maxstack", cfun_maxstack,
|
||||
"(fiber.maxstack fib)\n\n"
|
||||
"Gets the maximum stack size in janet values allowed for a fiber. While memory for "
|
||||
"the fiber's stack is not allocated up front, the fiber will not allocated more "
|
||||
"than this amount and will throw a stackoverflow error if more memory is needed. "
|
||||
},
|
||||
{"fiber.setmaxstack", cfun_setmaxstack,
|
||||
"(fiber.setmaxstack fib maxstack)\n\n"
|
||||
"Sets the maximum stack size in janet values for a fiber. By default, the "
|
||||
"maximum stacksize is usually 8192."
|
||||
},
|
||||
{NULL, NULL, NULL}
|
||||
};
|
||||
|
||||
|
||||
@ -355,9 +355,9 @@ static int janet_io_fseek(JanetArgs args) {
|
||||
JANET_THROW(args, "expected one of :cur, :set, :end");
|
||||
}
|
||||
if (args.n >= 3) {
|
||||
if (!janet_checktype(args.v[2], JANET_INTEGER))
|
||||
JANET_THROW(args, "expected integer");
|
||||
offset = janet_unwrap_integer(args.v[2]);
|
||||
double doffset;
|
||||
JANET_ARG_NUMBER(doffset, args, 2);
|
||||
offset = (long int)doffset;
|
||||
}
|
||||
}
|
||||
if (fseek(iof->file, offset, whence))
|
||||
@ -366,13 +366,63 @@ static int janet_io_fseek(JanetArgs args) {
|
||||
}
|
||||
|
||||
static const JanetReg cfuns[] = {
|
||||
{"file.open", janet_io_fopen, NULL},
|
||||
{"file.close", janet_io_fclose, NULL},
|
||||
{"file.read", janet_io_fread, NULL},
|
||||
{"file.write", janet_io_fwrite, NULL},
|
||||
{"file.flush", janet_io_fflush, NULL},
|
||||
{"file.seek", janet_io_fseek, NULL},
|
||||
{"file.popen", janet_io_popen, NULL},
|
||||
{"file.open", janet_io_fopen,
|
||||
"(file.open path [,mode])\n\n"
|
||||
"Open a file. path is files absolute or relative path, and "
|
||||
"mode is a set of flags indicating the mode to open the file in. "
|
||||
"mode is a keyword where each character represents a flag. If the file "
|
||||
"cannot be opened, returns nil, otherwise returns the new file handle. "
|
||||
"Mode flags:\n\n"
|
||||
"\tr - allow reading from the file\n"
|
||||
"\tw - allow witing to the file\n"
|
||||
"\ta - append to the file\n"
|
||||
"\tb - open the file in binary mode (rather than text mode)\n"
|
||||
"\t+ - append to the file instead of overwriting it"
|
||||
},
|
||||
{"file.close", janet_io_fclose,
|
||||
"(file.close f)\n\n"
|
||||
"Close a file and release all related resources. When you are "
|
||||
"done reading a file, close it to prevent a resource leak and let "
|
||||
"other processes read the file."
|
||||
},
|
||||
{"file.read", janet_io_fread,
|
||||
"(file.read f what [,buf])\n\n"
|
||||
"Read a number of bytes from a file into a buffer. A buffer can "
|
||||
"be provided as an optional fourth argument. otherwise a new buffer "
|
||||
"is created. 'what' can either be an integer or a keyword. Returns the "
|
||||
"buffer with file contents. "
|
||||
"Values for 'what':\n\n"
|
||||
"\t:all - read the whole file\n"
|
||||
"\t:line - read up to and including the next newline character\n"
|
||||
"\tn (integer) - read up to n bytes from the file"
|
||||
},
|
||||
{"file.write", janet_io_fwrite,
|
||||
"(file.write f bytes)\n\n"
|
||||
"Writes to a file. 'bytes' must be string, buffer, or symbol. Returns the "
|
||||
"file"
|
||||
},
|
||||
{"file.flush", janet_io_fflush,
|
||||
"(file.flush f)\n\n"
|
||||
"Flush any buffered bytes to the filesystem. In most files, writes are "
|
||||
"buffered for efficiency reasons. Returns the file handle."
|
||||
},
|
||||
{"file.seek", janet_io_fseek,
|
||||
"(file.seek f [,whence [,n]])\n\n"
|
||||
"Jump to a relative location in the file. 'whence' must be one of\n\n"
|
||||
"\t:cur - jump relative to the current file location\n"
|
||||
"\t:set - jump relative to the beginning of the file\n"
|
||||
"\t:end - jump relative to the end of the file\n\n"
|
||||
"By default, 'whence' is :cur. Optionally a value n may be passed "
|
||||
"for the relative number of bytes to seek in the file. n may be a real "
|
||||
"number to handle large files of more the 4GB. Returns the file handle."
|
||||
},
|
||||
{"file.popen", janet_io_popen,
|
||||
"(file.popen path [,mode])\n\n"
|
||||
"Open a file that is backed by a process. The file must be opened in either "
|
||||
"the :r (read) or the :w (write) mode. In :r mode, the stdout of the "
|
||||
"process can be read from the file. In :w mode, the stdin of the process "
|
||||
"can be written to. Returns the new file."
|
||||
},
|
||||
{NULL, NULL, NULL}
|
||||
};
|
||||
|
||||
@ -383,15 +433,19 @@ int janet_lib_io(JanetArgs args) {
|
||||
|
||||
/* stdout */
|
||||
janet_def(env, "stdout",
|
||||
makef(stdout, IO_APPEND | IO_NOT_CLOSEABLE | IO_SERIALIZABLE), NULL);
|
||||
makef(stdout, IO_APPEND | IO_NOT_CLOSEABLE | IO_SERIALIZABLE),
|
||||
"The standard output file.");
|
||||
|
||||
|
||||
/* stderr */
|
||||
janet_def(env, "stderr",
|
||||
makef(stderr, IO_APPEND | IO_NOT_CLOSEABLE | IO_SERIALIZABLE), NULL);
|
||||
makef(stderr, IO_APPEND | IO_NOT_CLOSEABLE | IO_SERIALIZABLE),
|
||||
"The standard error file.");
|
||||
|
||||
/* stdin */
|
||||
janet_def(env, "stdin",
|
||||
makef(stdin, IO_READ | IO_NOT_CLOSEABLE | IO_SERIALIZABLE), NULL);
|
||||
makef(stdin, IO_READ | IO_NOT_CLOSEABLE | IO_SERIALIZABLE),
|
||||
"The standard input file.");
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
@ -1144,9 +1144,27 @@ static int cfun_unmarshal(JanetArgs args) {
|
||||
}
|
||||
|
||||
static const JanetReg cfuns[] = {
|
||||
{"marshal", cfun_marshal, NULL},
|
||||
{"unmarshal", cfun_unmarshal, NULL},
|
||||
{"env-lookup", cfun_env_lookup, NULL},
|
||||
{"marshal", cfun_marshal,
|
||||
"(marshal x [,reverse-lookup [,buffer]])\n\n"
|
||||
"Marshal a janet value into a buffer and return the buffer. The buffer "
|
||||
"can the later be unmarshalled to reconstruct the initial value. "
|
||||
"Optionally, one can pass in a reverse lookup table to not marshal "
|
||||
"aliased values that are found in the table. Then a forward"
|
||||
"lookup table can be used to recover the origrinal janet value when "
|
||||
"unmarshaling."
|
||||
},
|
||||
{"unmarshal", cfun_unmarshal,
|
||||
"(unmarshal buffer [,lookup])\n\n"
|
||||
"Unmarshal a janet value from a buffer. An optional lookup table "
|
||||
"can be provided to allow for aliases to be resolved. Returns the value "
|
||||
"unmarshaled from the buffer."
|
||||
},
|
||||
{"env-lookup", cfun_env_lookup,
|
||||
"(env-lookup env)\n\n"
|
||||
"Creates a forward lookup table for unmarshaling from an environment. "
|
||||
"To create a reverse lookup table, use the invert function to swap keys "
|
||||
"and values in the returned table."
|
||||
},
|
||||
{NULL, NULL, NULL}
|
||||
};
|
||||
|
||||
|
||||
102
src/core/math.c
102
src/core/math.c
@ -130,25 +130,80 @@ static int janet_not(JanetArgs args) {
|
||||
}
|
||||
|
||||
static const JanetReg cfuns[] = {
|
||||
{"%", janet_remainder, NULL},
|
||||
{"not", janet_not, NULL},
|
||||
{"int", janet_int, NULL},
|
||||
{"real", janet_real, NULL},
|
||||
{"math.random", janet_rand, NULL},
|
||||
{"math.seedrandom", janet_srand, NULL},
|
||||
{"math.cos", janet_cos, NULL},
|
||||
{"math.sin", janet_sin, NULL},
|
||||
{"math.tan", janet_tan, NULL},
|
||||
{"math.acos", janet_acos, NULL},
|
||||
{"math.asin", janet_asin, NULL},
|
||||
{"math.atan", janet_atan, NULL},
|
||||
{"math.exp", janet_exp, NULL},
|
||||
{"math.log", janet_log, NULL},
|
||||
{"math.log10", janet_log10, NULL},
|
||||
{"math.sqrt", janet_sqrt, NULL},
|
||||
{"math.floor", janet_floor, NULL},
|
||||
{"math.ceil", janet_ceil, NULL},
|
||||
{"math.pow", janet_pow, NULL},
|
||||
{"%", janet_remainder,
|
||||
"(% dividend divisor)\n\n"
|
||||
"Returns the remainder of dividend / divisor."
|
||||
},
|
||||
{"not", janet_not,
|
||||
"(not x)\n\nReturns the boolen inverse of x."
|
||||
},
|
||||
{"int", janet_int,
|
||||
"(int x)\n\nCast a number x to an integer."
|
||||
},
|
||||
{"real", janet_real,
|
||||
"(real x)\n\nCast a number x to a real number."
|
||||
},
|
||||
{"math.random", janet_rand,
|
||||
"(math.random)\n\n"
|
||||
"Returns a uniformly distrbuted random real number between 0 and 1."
|
||||
},
|
||||
{"math.seedrandom", janet_srand,
|
||||
"(math.seedrandom seed)\n\n"
|
||||
"Set the seed for the random number generator. 'seed' should be an "
|
||||
"an integer."
|
||||
},
|
||||
{"math.cos", janet_cos,
|
||||
"(math.cos x)\n\n"
|
||||
"Returns the cosine of x."
|
||||
},
|
||||
{"math.sin", janet_sin,
|
||||
"(math.sin x)\n\n"
|
||||
"Returns the sine of x."
|
||||
},
|
||||
{"math.tan", janet_tan,
|
||||
"(math.tan x)\n\n"
|
||||
"Returns the tangent of x."
|
||||
},
|
||||
{"math.acos", janet_acos,
|
||||
"(math.acos x)\n\n"
|
||||
"Returns the arccosine of x."
|
||||
},
|
||||
{"math.asin", janet_asin,
|
||||
"(math.asin x)\n\n"
|
||||
"Returns the arcsine of x."
|
||||
},
|
||||
{"math.atan", janet_atan,
|
||||
"(math.atan x)\n\n"
|
||||
"Returns the arctangent of x."
|
||||
},
|
||||
{"math.exp", janet_exp,
|
||||
"(math.exp x)\n\n"
|
||||
"Returns e to the power of x."
|
||||
},
|
||||
{"math.log", janet_log,
|
||||
"(math.log x)\n\n"
|
||||
"Returns log base 2 of x."
|
||||
},
|
||||
{"math.log10", janet_log10,
|
||||
"(math.log10 x)\n\n"
|
||||
"Returns log base 10 of x."
|
||||
},
|
||||
{"math.sqrt", janet_sqrt,
|
||||
"(math.sqrt x)\n\n"
|
||||
"Returns the square root of x."
|
||||
},
|
||||
{"math.floor", janet_floor,
|
||||
"(math.floor x)\n\n"
|
||||
"Returns the largest integer value real number that is not greater than x."
|
||||
},
|
||||
{"math.ceil", janet_ceil,
|
||||
"(math.ceil x)\n\n"
|
||||
"Returns the smallest integer value real number that is not less than x."
|
||||
},
|
||||
{"math.pow", janet_pow,
|
||||
"(math.pow a x)\n\n"
|
||||
"Return a to the power of x."
|
||||
},
|
||||
{NULL, NULL, NULL}
|
||||
};
|
||||
|
||||
@ -157,8 +212,11 @@ int janet_lib_math(JanetArgs args) {
|
||||
JanetTable *env = janet_env(args);
|
||||
janet_cfuns(env, NULL, cfuns);
|
||||
|
||||
janet_def(env, "math.pi", janet_wrap_real(3.1415926535897931), NULL);
|
||||
janet_def(env, "math.e", janet_wrap_real(2.7182818284590451), NULL);
|
||||
janet_def(env, "math.inf", janet_wrap_real(INFINITY), NULL);
|
||||
janet_def(env, "math.pi", janet_wrap_real(3.1415926535897931),
|
||||
"The value pi.");
|
||||
janet_def(env, "math.e", janet_wrap_real(2.7182818284590451),
|
||||
"The base of the natural log.");
|
||||
janet_def(env, "math.inf", janet_wrap_real(INFINITY),
|
||||
"The real number representing positive infinity");
|
||||
return 0;
|
||||
}
|
||||
|
||||
@ -265,7 +265,8 @@ static int stringchar(JanetParser *p, JanetParseState *state, uint8_t c) {
|
||||
return stringend(p, state);
|
||||
}
|
||||
/* normal char */
|
||||
push_buf(p, c);
|
||||
if (c != '\n')
|
||||
push_buf(p, c);
|
||||
return 1;
|
||||
}
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user