diff --git a/content/api/array.mdz b/content/api/array.mdz index 28f7333..7af95cf 100644 --- a/content/api/array.mdz +++ b/content/api/array.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "Array Module" :nav-title "array" diff --git a/content/api/buffer.mdz b/content/api/buffer.mdz index b01c7ce..2a33509 100644 --- a/content/api/buffer.mdz +++ b/content/api/buffer.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "Buffer Module" :nav-title "buffer" diff --git a/content/api/bundle.mdz b/content/api/bundle.mdz index bbdee6e..2b4be17 100644 --- a/content/api/bundle.mdz +++ b/content/api/bundle.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "Bundle Module" :nav-title "bundle" diff --git a/content/api/debug.mdz b/content/api/debug.mdz index 0e446ce..5575de6 100644 --- a/content/api/debug.mdz +++ b/content/api/debug.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "Debug Module" :nav-title "debug" diff --git a/content/api/ev.mdz b/content/api/ev.mdz index 5d33e98..c484cf0 100644 --- a/content/api/ev.mdz +++ b/content/api/ev.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "Event Module" :nav-title "ev" diff --git a/content/api/ffi.mdz b/content/api/ffi.mdz index fe88be5..4323f3e 100644 --- a/content/api/ffi.mdz +++ b/content/api/ffi.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "FFI Module" :nav-title "ffi" diff --git a/content/api/fiber.mdz b/content/api/fiber.mdz index 533553f..1bbd009 100644 --- a/content/api/fiber.mdz +++ b/content/api/fiber.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "Fiber Module" :nav-title "fiber" diff --git a/content/api/file.mdz b/content/api/file.mdz index 4414027..cb4eab8 100644 --- a/content/api/file.mdz +++ b/content/api/file.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "File Module" :nav-title "file" diff --git a/content/api/filewatch.mdz b/content/api/filewatch.mdz new file mode 100644 index 0000000..2886150 --- /dev/null +++ b/content/api/filewatch.mdz @@ -0,0 +1,10 @@ +(import ../gen-docs :as gen-docs) + +{:title "Filewatch Module" + :nav-title "filewatch" + :template "docpage.html"} +--- + +## Index + +@gen-docs/gen-prefix[filewatch/] diff --git a/content/api/index.mdz b/content/api/index.mdz index a8f7148..ae025bb 100644 --- a/content/api/index.mdz +++ b/content/api/index.mdz @@ -1,7 +1,7 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "Core API" - :nav-title "API" + :nav-title "Core API" :order 3 :template "docpage.html" :permalinks ["doc.html"] } diff --git a/content/api/int.mdz b/content/api/int.mdz index 4c103b6..ff84ed2 100644 --- a/content/api/int.mdz +++ b/content/api/int.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "Integer Types Module" :nav-title "int" diff --git a/content/api/janet.mdz b/content/api/janet.mdz new file mode 100644 index 0000000..6f1c563 --- /dev/null +++ b/content/api/janet.mdz @@ -0,0 +1,11 @@ +(import ../gen-docs :as gen-docs) + +{:title "Janet Module" + :nav-title "janet" + :template "docpage.html"} +--- + +## Index + +@gen-docs/gen-prefix[janet/] + diff --git a/content/api/math.mdz b/content/api/math.mdz index 43f5cb9..ed70f0b 100644 --- a/content/api/math.mdz +++ b/content/api/math.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "Math Module" :nav-title "math" diff --git a/content/api/misc.mdz b/content/api/misc.mdz index adf88ef..6524bd3 100644 --- a/content/api/misc.mdz +++ b/content/api/misc.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "Top Level Bindings" :nav-title "misc" diff --git a/content/api/module.mdz b/content/api/module.mdz index 4261ef0..de14226 100644 --- a/content/api/module.mdz +++ b/content/api/module.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "Module Module" :nav-title "module" diff --git a/content/api/net.mdz b/content/api/net.mdz index e134176..c1b6030 100644 --- a/content/api/net.mdz +++ b/content/api/net.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "Net Module" :nav-title "net" diff --git a/content/api/os.mdz b/content/api/os.mdz index 2b93afd..bc89392 100644 --- a/content/api/os.mdz +++ b/content/api/os.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "OS Module" :nav-title "os" diff --git a/content/api/parser.mdz b/content/api/parser.mdz index 213f5c7..8441b05 100644 --- a/content/api/parser.mdz +++ b/content/api/parser.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "Parser Module" :nav-title "parser" diff --git a/content/api/peg.mdz b/content/api/peg.mdz index 3057579..b6dcc73 100644 --- a/content/api/peg.mdz +++ b/content/api/peg.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "PEG Module" :nav-title "peg" diff --git a/content/api/spork/argparse.mdz b/content/api/spork/argparse.mdz deleted file mode 100644 index 8d2cffc..0000000 --- a/content/api/spork/argparse.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/argparse :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "Argument Parsing" - :nav-title "argparse" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[argparse/] diff --git a/content/api/spork/base64.mdz b/content/api/spork/base64.mdz deleted file mode 100644 index 8ff76a5..0000000 --- a/content/api/spork/base64.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/base64 :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "Base64" - :nav-title "base64" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[base64/] diff --git a/content/api/spork/cjanet.mdz b/content/api/spork/cjanet.mdz deleted file mode 100644 index 78f27b2..0000000 --- a/content/api/spork/cjanet.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/cjanet :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "C-Janet" - :nav-title "cjanet" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[cjanet/] diff --git a/content/api/spork/cron.mdz b/content/api/spork/cron.mdz deleted file mode 100644 index b64a667..0000000 --- a/content/api/spork/cron.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/cron :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "Cron" - :nav-title "cron" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[cron/] diff --git a/content/api/spork/data.mdz b/content/api/spork/data.mdz deleted file mode 100644 index 7d4e3be..0000000 --- a/content/api/spork/data.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/data :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "Data" - :nav-title "data" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[data/] diff --git a/content/api/spork/fmt.mdz b/content/api/spork/fmt.mdz deleted file mode 100644 index c17fa3f..0000000 --- a/content/api/spork/fmt.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/fmt :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "Format" - :nav-title "fmt" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[fmt/] diff --git a/content/api/spork/generators.mdz b/content/api/spork/generators.mdz deleted file mode 100644 index 4bcd7d6..0000000 --- a/content/api/spork/generators.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/generators :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "Generators" - :nav-title "generators" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[generators/] diff --git a/content/api/spork/htmlgen.mdz b/content/api/spork/htmlgen.mdz deleted file mode 100644 index 7f1c1c8..0000000 --- a/content/api/spork/htmlgen.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/htmlgen :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "HTML Generation" - :nav-title "htmlgen" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[htmlgen/] diff --git a/content/api/spork/http.mdz b/content/api/spork/http.mdz deleted file mode 100644 index 1cb79cf..0000000 --- a/content/api/spork/http.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/http :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "HTTP" - :nav-title "http" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[http/] diff --git a/content/api/spork/index.mdz b/content/api/spork/index.mdz deleted file mode 100644 index ae12053..0000000 --- a/content/api/spork/index.mdz +++ /dev/null @@ -1,22 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "Spork" - :nav-title "spork" - :template "docpage.html"} ---- - -While not part of Janet's core library, Spork is an official "contributor" library as well as a collection -of various useful utilties for Janet. - -Spork can be installed with - -@codeblock``` -jpm install spork -``` - -## Index - -@gen-docs/gen-prefix-current[spork/] diff --git a/content/api/spork/infix.mdz b/content/api/spork/infix.mdz deleted file mode 100644 index 0a81a1c..0000000 --- a/content/api/spork/infix.mdz +++ /dev/null @@ -1,73 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/infix :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "Infix Syntax" - :nav-title "infix" - :template "docpage.html"} ---- - -A macro for infix syntax in Janet. Useful for math. - -@codeblock[janet]``` - ($$ a + b ** 2) ---> (+ a (math/pow b 2)) - ($$ (a + b) ** 2) ---> (math/pow (+ a b) 2) - ($$ y[2] + y[3]) ---> (+ (in y 2) (in y 3)) - ($$ a > b and ,(good? z)) ---> (and (> a b) (good? z)) -``` - -Syntax is as follows: - -Binary operators <<, >>, >>>, =, !=, <, <=, >, >=, &, ^, bor, band, and, or, -+, -, *, /, %, ** are supported. Operator precedence is in the -`precedence table below (higher means more tightly binding). All -operators are left associative except ** (math/pow), which is right -associative. - -Unary prefix operators !, -, bnot, not, ++, -- are supported. -No unary postfix operators are supported. - -Square brackets can be used for indexing. - -Normal parentheses are used for making subgroups - -You can "escape" infix syntax use a quote or unquote (comma) - -### Precedence Table - -@codeblock[janet]``` -(def- precedence - {'>> 9 - '<< 9 - '>>> 9 - '= 8 - '!= 8 - 'not= 8 - '< 8 - '<= 8 - '>= 8 - '> 8 - '& 7 - '^ 6 - 'bor 5 - 'band 5 - 'and 4 - 'or 3 - '+ 10 - '- 10 - '* 20 - '/ 20 - '% 20 - '** 30 - '! 40 - 'not 40 - 'bnot 40 - '++ 40 - '-- 40}) -``` - - -## Index - -@gen-docs/gen-prefix-current[infix/] diff --git a/content/api/spork/misc.mdz b/content/api/spork/misc.mdz deleted file mode 100644 index c7ed69d..0000000 --- a/content/api/spork/misc.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/misc :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "Miscellaneous Functions" - :nav-title "misc" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[misc/] diff --git a/content/api/spork/msg.mdz b/content/api/spork/msg.mdz deleted file mode 100644 index 0dcfc3e..0000000 --- a/content/api/spork/msg.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/msg :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "Simple Messaging Protocol" - :nav-title "msg" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[msg/] diff --git a/content/api/spork/netrepl.mdz b/content/api/spork/netrepl.mdz deleted file mode 100644 index 91628a8..0000000 --- a/content/api/spork/netrepl.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/netrepl :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "NetREPL" - :nav-title "netrepl" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[netrepl/] diff --git a/content/api/spork/path.mdz b/content/api/spork/path.mdz deleted file mode 100644 index 03ff227..0000000 --- a/content/api/spork/path.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/path :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "Path Utilities" - :nav-title "path" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[path/] diff --git a/content/api/spork/randgen.mdz b/content/api/spork/randgen.mdz deleted file mode 100644 index 650b5d8..0000000 --- a/content/api/spork/randgen.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/randgen :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "Random Number Generation" - :nav-title "randgen" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[randgen/] diff --git a/content/api/spork/regex.mdz b/content/api/spork/regex.mdz deleted file mode 100644 index 482701b..0000000 --- a/content/api/spork/regex.mdz +++ /dev/null @@ -1,16 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/regex :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "Regular Expression PEG Syntax" - :nav-title "regex" - :template "docpage.html"} ---- - -Spork's regex module is not actually a traditional regular expression -module - instead, it is a regex-like syntax for Janet's PEG functionality. - -## Index - -@gen-docs/gen-prefix-current[regex/] diff --git a/content/api/spork/rpc.mdz b/content/api/spork/rpc.mdz deleted file mode 100644 index 4a5f629..0000000 --- a/content/api/spork/rpc.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/rpc :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "Remote Procedure Calls" - :nav-title "rpc" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[rpc/] diff --git a/content/api/spork/schema.mdz b/content/api/spork/schema.mdz deleted file mode 100644 index bcd9fdc..0000000 --- a/content/api/spork/schema.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/schema :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "Schema" - :nav-title "schema" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[schema/] diff --git a/content/api/spork/temple.mdz b/content/api/spork/temple.mdz deleted file mode 100644 index 0cbb82d..0000000 --- a/content/api/spork/temple.mdz +++ /dev/null @@ -1,13 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/temple :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/tasker" gen-docs/spork-version)) -(setdyn :no-community-examples true) - -{:title "Temple Templates" - :nav-title "temple" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[temple/] diff --git a/content/api/spork/utf8.mdz b/content/api/spork/utf8.mdz deleted file mode 100644 index 868e64b..0000000 --- a/content/api/spork/utf8.mdz +++ /dev/null @@ -1,12 +0,0 @@ -(import ../gen-docs :as gen-docs) -(import spork/utf8 :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) - -{:title "UTF8" - :nav-title "utf8" - :template "docpage.html"} ---- - -## Index - -@gen-docs/gen-prefix-current[utf8/] \ No newline at end of file diff --git a/content/api/string.mdz b/content/api/string.mdz index 22a5102..f7da470 100644 --- a/content/api/string.mdz +++ b/content/api/string.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "String Module" :nav-title "string" diff --git a/content/api/table.mdz b/content/api/table.mdz index a8f7993..31bb403 100644 --- a/content/api/table.mdz +++ b/content/api/table.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "Table Module" :nav-title "table" diff --git a/content/api/tuple.mdz b/content/api/tuple.mdz index 43d326c..fd29492 100644 --- a/content/api/tuple.mdz +++ b/content/api/tuple.mdz @@ -1,4 +1,4 @@ -(import ./gen-docs :as gen-docs) +(import ../gen-docs :as gen-docs) {:title "Tuple Module" :nav-title "tuple" diff --git a/content/docs/jpm.mdz b/content/docs/jpm.mdz deleted file mode 100644 index a5bae23..0000000 --- a/content/docs/jpm.mdz +++ /dev/null @@ -1,350 +0,0 @@ -{:title "jpm" - :template "docpage.html" - :order 24} ---- - -JPM is a build tool that can be installed along with Janet to help build and install -libraries for Janet. The main uses are installing dependencies, compiling C/C++ to native libraries, and -other project management tasks. The source code for JPM -can be found at @link[https://github.com/janet-lang/jpm.git][https://github.com/janet-lang/jpm.git]. -With janet already installed, JPM is also self bootstrapping. - -@codeblock``` -git clone --depth=1 https://github.com/janet-lang/jpm.git -cd jpm -sudo janet bootstrap.janet -``` - -The bootstrap script can also be configured to install jpm to -different directories by setting the @code`DESTDIR` environment -variable. Ideally, jpm should be installed to the same tree as Janet, -although this is not strictly required. See the README in jpm's -repository for more information. - -## Updating JPM - -Once installed and configured, JPM can update itself from the git repository at any time. - -@codeblock``` -sudo jpm install jpm -``` - -@p{@code`jpm`'s main functions are installing dependencies and building native - Janet modules, but it is meant to be used for much of the life-cycle for - Janet projects. Since Janet code doesn't usually need to be compiled, you - don't always need @code`jpm`, especially for scripts, but @code`jpm` comes - with some functionality that is difficult to duplicate, like compiling Janet - source code and all imported modules into a statically linked executable for - distribution. -} - -## Glossary - -A self-contained unit of Janet source code as recognized by @code`jpm` -is called a project. A project is a directory containing a -@code`project.janet` file, which contains build recipes. Often, a -project will correspond to a single git repository, and contain a -single library. However, a project's @code`project.janet` file can -contain build recipes for as many libraries, native extensions, and -executables as it wants. Each of these recipes builds an -artifact. Artifacts are the output files that will either be -distributed or installed on the end-user or developer's machine. - -## Building projects with @code`jpm` - -Once you have the project on your machine, building the various artifacts should -be pretty simple. - -#### Global install - -@codeblock``` -sudo jpm deps -jpm build -jpm test -sudo jpm install -``` - -\(On Windows, @code`sudo` is not required. Use of @code`sudo` on POSIX systems -depends on whether you installed @code`janet` to a directory owned by the root -user.) - -#### User local install - -The JANET_TREE environment variable can be used to set the tree the jpm installs things to. -By default, running @code`janet` from the command line separately will not use modules in -the custom tree, so you will likely want to modify JANET_PATH as well. - -@codeblock``` -export JANET_TREE=$HOME/.local/jpm_tree -jpm deps -jpm build -jpm test -jpm install -# alternative: jpm --tree=$HOME/.local/jpm_tree deps -``` - -#### Project local install - -JPM also has some flags to install dependencies to a tree local to a project. Dependencies will -be installed to ./jpm_tree/lib (and binaries installed to ./jpm_tree/bin) when passing the @code`-l` -flag to jpm. - -@codeblock``` -jpm -l deps -jpm -l build -jpm -l test -# Run a janet interpreter in the local environment with access to all dependencies installed. -jpm -l janet -``` - -### Dependencies - -@p{@code`jpm deps` is a command that installs Janet libraries that the project - depends on recursively. It will automatically fetch, build, and install all - required dependencies for you. As of August 2019, this only works with git, - which you need to have installed on your machine to install dependencies. If - you don't have git you are free to manually obtain the requisite - dependencies and install them manually with @code`sudo jpm install`. -} - -### Building - -Next, we use the @code`jpm build` command to build artifacts. All built -artifacts will be created in the @code`build` subdirectory of the current -project. Therefore, it is probably a good idea to exclude the @code`build` -directory from source control. For building executables and native modules, you -will need to have a C compiler on your PATH where you run @code`jpm build`. For -POSIX systems, the compiler is @code`cc`. - -If you make changes to the source code after building once, @code`jpm` will try -to only rebuild what is needed on a rebuild. If this fails for any reason, you -can delete the entire build directory with @code`jpm clean` to reset things. - -#### Windows - -For Windows, the C compiler used by @code`jpm` is @code`cl.exe`, which is part -of MSVC. You can get it with Visual Studio, or standalone with the C and C++ -Build Tools from Microsoft. You will then need to run @code`jpm build` in a -Developer Command Prompt, or source @code`vcvars64.bat` in your shell to add -@code`cl.exe` to the PATH. - -### Testing - -Once we have built our software, it is a good idea to test it to verify that it -works on the current machine. @code`jpm test` will run all Janet scripts in the -@code`test` directory of the project and return a non-zero exit code if any -fail. - -### Installing - -Finally, once we have built our software and tested that it works, we can -install it on our system. For an executable, this means copying it to the -@code`bin` directory, and for libraries it means copying them to the global -syspath. You can optionally install into any directory if you don't want to -pollute your system or you don't have permission to write to the directory where -@code`janet` itself was installed. You can specify the path to install modules -to via the @code`--modpath` option, and the path to install binaries to with the -@code`--binpath` option. These need to be given before the subcommand -@code`install`. - -## The @code`project.janet` file - -To create your own software in Janet, it is a good idea to understand what the -@code`project.janet` file is and how it defines rules for building, testing, and -installing software. The code in @code`project.janet` is normal Janet source -code that is run in a special environment. - -A @code`project.janet` file is loaded by @code`jpm` and evaluated to create -various recipes, or rules. For example, @code`declare-project` creates several -rules, including @code`"install"`, @code`"build"`, @code`"clean"`, and -@code`"test"`. These are a few of the rules that @code`jpm` expects -@code`project.janet` to create when executed. - -### Declaring a project - -Use the @code`declare-project` as the first @code`declare-` macro towards the -beginning of your @code`project.janet` file. You can also pass in any metadata -about your project that you want, and add dependencies on other Janet projects -here. - -@codeblock[janet]``` -(declare-project - :name "mylib" # required - :description "a library that does things" # some example metadata. - - # Optional urls to git repositories that contain required artifacts. - :dependencies ["https://github.com/janet-lang/json.git"]) -``` - -### Creating a module - -A 100% Janet library is the easiest kind of software to distribute in Janet. -Since it does not need to be built and since installing it means simply moving -the files to a system directory, we only need to specify the files that comprise -the library in @code`project.janet`. - -@codeblock[janet]``` -(declare-source - # :source is an array or tuple that can contain - # source files and directories that will be installed. - # Often will just be a single file or single directory. - :source ["mylib.janet"]) -``` - -For information on writing modules, see @link[/docs/modules.html]{the modules docpage}. - -### Creating a native module - -Once you have written your C code that defines your native module (see the -@link[/capi/embedding.html]{embedding} page on how to do this), you must declare -it in @code`project.janet` in order for @code`jpm` to build the native modules -for you. - -@codeblock[janet]``` -(declare-native - :name "mynative" - :source ["mynative.c" "mysupport.c"] - :embedded ["extra-functions.janet"]) -``` - -This makes @code`jpm` create a native module called @code`mynative` when -@code`jpm build` is run, the arguments for which should be pretty -straightforward. The @code`:embedded` argument is Janet source code that will be -embedded as an array of bytes directly into the C source code. It is not -recommended to use the @code`:embedded` argument, as one can simply create -multiple artifacts, one for a pure C native module and one for Janet source -code. - -### Creating an executable - -The declaration for an executable file is pretty simple. - -@codeblock[janet]``` -(declare-executable - :name "myexec" - :entry "main.janet" - :install true) -``` - -@p{@code`jpm` is smart enough to figure out from the one entry file what - libraries and other code your executable depends on, and bundles them into - the final application for you. The final executable will be located at - @code`build/myexec`, or @code`build\myexec.exe` on Windows.} - -If the optional key-value pair @code`:install true` is specified in the -@code`declare-executable` form, by default, the appropriate @code`jpm install` -command will install the resulting executable to the @code`JANET_BINPATH` -\(but see the jpm man page for further details). - -Also note that the entry of an executable file should look different than a -normal Janet script. It should define a @code`main` function that can receive a -variable number of parameters, the command-line arguments. It will be called as -the entry point to your executable. - -@codeblock[janet]``` -(import mylib1) -(import mylib2) - -# This will be printed when you run `jpm build` -(print "build time!") - -(defn main - [& args] - # You can also get command-line arguments through (dyn :args) - (print "args: " ;(interpose ", " args)) - (mylib1/do-thing) - (mylib2/do-thing)) -``` - -It's important to remember that code at the top level will run when you invoke -@code`jpm build`, not at executable runtime. This is because in order to create -the executable, we marshal the @code`main` function of the app and write it to -an image. In order to create the main function, we need to actually compile and -run everything that it references, in the above case @code`mylib1` and -@code`mylib2`. - -This has a number of benefits, but the largest is that we only include bytecode -for the functions that our application uses. If we only use one function from a -library of 1000 functions, our final executable will not include the bytecode -for the other 999 functions (unless our one function references some of those -other functions, of course). This feature, called tree-shaking, only works -for Janet code. Native modules will be linked to the final executable statically -in full if they are used at all. A native module is considered "used" if is -imported at any time during @code`jpm build`. This may change, but it is -currently the most reliable way to check if a native modules needs to be linked -into the final executable. - -There are some limitations to this approach. Any dynamically required modules -will not always be linked into the final executable. If @code`require` or -@code`import` is not called during @code`jpm build`, then the code will not be -linked into the executable. The module can still be required if it is available -at runtime, though. - -For an example Janet executable built with @code`jpm`, see -@link[https://github.com/bakpakin/littleserver][https://github.com/bakpakin/littleserver]. - -### Other @code`declare-` callables - -Some additional @code`declare-` callables are: - -@ul{@li{@code`declare-bin` - - @p{Declare a generic file to be installed as an - executable. Specify file path via @code`:main`.}} - - @li{@code`declare-binscript` - - @p{Declare a janet file to be installed as an executable - script. Creates a shim on windows. If - @code`:hardcode-syspath` is true, will insert code into the - script such that it will run correctly even when - @code`JANET_PATH` is changed. If @code`:is-janet` is - truthy, will also automatically insert a correct shebang - line if jpm's configuration is set with - @code`:auto-shebang` as truthy.}} - - @li{@code`declare-headers` - - @p{Declare headers for a library installation. Installed - headers can be used by other native libraries. Specify - paths via @code`:headers` and prefix via @code`:prefix`.}} - - @li{@code`declare-manpage` - - @p{Mark a manpage for installation.}}} - -## Custom Trees - -For per-project or per-user development (as opposed to system-wide development), you can use -custom jpm trees rather than a system default by passing the @code`--tree=` argument -all jpm commands or setting the @code`JANET_TREE` environment variable. This will set the location -where jpm will install modules, headers, scripts, and other data to. For project local development in -a tree @code`./jpm_tree`, you can use the @code`--local` or @code`-l` shorthand for this. - -@codeblock``` -jpm --tree=/opt/jpm_tree deps -jpm --tree=/opt/jpm_tree install spork -jpm -l deps -jpm -l test -``` - -## Versioning and Library Bundling - -JPM does not do any semantic version resolution at the moment. Instead, it is recommended to make all changes -to libraries as backwards-compatible as possible, and release new libraries for breaking changes in almost all -cases. For creators of executable programs (versus a library author), it is recommended to use a local tree -and lockfiles to pin versions for consistent builds. - -As a matter of style, it is also recommended to group small libraries -together into "bundles" that are updated, tested, and deployed -together. Since Janet libraries are often quite small, the cost of -downloading more functionality that one might need isn't particularly -high, and JPM can remove unused functions and bindings from generated -standalone binaries and images, so there is no runtime cost either. By -avoiding a plethora of tiny libraries, users of libraries do not -manage as many dependencies, and modules are more likely to work -together they can be tested together. - -While @code`jpm` may superficially resemble @code`npm`, it is the -author's opinion that it is suited to a different style of -development. diff --git a/content/api/gen-docs.janet b/content/gen-docs.janet similarity index 100% rename from content/api/gen-docs.janet rename to content/gen-docs.janet diff --git a/content/api/jpm/cc.mdz b/content/jpm/api/cc.mdz similarity index 88% rename from content/api/jpm/cc.mdz rename to content/jpm/api/cc.mdz index c012d7d..eeb4eb9 100644 --- a/content/api/jpm/cc.mdz +++ b/content/jpm/api/cc.mdz @@ -1,4 +1,4 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import jpm/cc :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/jpm" gen-docs/jpm-version)) (setdyn :no-community-examples true) diff --git a/content/api/jpm/cgen.mdz b/content/jpm/api/cgen.mdz similarity index 88% rename from content/api/jpm/cgen.mdz rename to content/jpm/api/cgen.mdz index e3616c0..e12cfac 100644 --- a/content/api/jpm/cgen.mdz +++ b/content/jpm/api/cgen.mdz @@ -1,4 +1,4 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import jpm/cgen :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/jpm" gen-docs/jpm-version)) (setdyn :no-community-examples true) diff --git a/content/api/jpm/cli.mdz b/content/jpm/api/cli.mdz similarity index 88% rename from content/api/jpm/cli.mdz rename to content/jpm/api/cli.mdz index d204444..0fe6a7a 100644 --- a/content/api/jpm/cli.mdz +++ b/content/jpm/api/cli.mdz @@ -1,4 +1,4 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import jpm/cli :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/jpm" gen-docs/jpm-version)) (setdyn :no-community-examples true) diff --git a/content/api/jpm/commands.mdz b/content/jpm/api/commands.mdz similarity index 88% rename from content/api/jpm/commands.mdz rename to content/jpm/api/commands.mdz index f7a57e2..0d55be7 100644 --- a/content/api/jpm/commands.mdz +++ b/content/jpm/api/commands.mdz @@ -1,4 +1,4 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import jpm/commands :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/jpm" gen-docs/jpm-version)) (setdyn :no-community-examples true) diff --git a/content/api/jpm/config.mdz b/content/jpm/api/config.mdz similarity index 88% rename from content/api/jpm/config.mdz rename to content/jpm/api/config.mdz index a561dec..b69dc88 100644 --- a/content/api/jpm/config.mdz +++ b/content/jpm/api/config.mdz @@ -1,4 +1,4 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import jpm/config :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/jpm" gen-docs/jpm-version)) (setdyn :no-community-examples true) diff --git a/content/api/jpm/dagbuild.mdz b/content/jpm/api/dagbuild.mdz similarity index 89% rename from content/api/jpm/dagbuild.mdz rename to content/jpm/api/dagbuild.mdz index 8a7b13a..f829e39 100644 --- a/content/api/jpm/dagbuild.mdz +++ b/content/jpm/api/dagbuild.mdz @@ -1,4 +1,4 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import jpm/dagbuild :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/jpm" gen-docs/jpm-version)) (setdyn :no-community-examples true) diff --git a/content/api/jpm/index.mdz b/content/jpm/api/index.mdz similarity index 51% rename from content/api/jpm/index.mdz rename to content/jpm/api/index.mdz index bb49fe0..b2d7409 100644 --- a/content/api/jpm/index.mdz +++ b/content/jpm/api/index.mdz @@ -1,13 +1,14 @@ -(import ../gen-docs :as gen-docs) -(import jpm :export true) +(import ../../gen-docs :as gen-docs) +(import jpm :prefix "" :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/jpm" gen-docs/jpm-version)) (setdyn :no-community-examples true) {:title "JPM" - :nav-title "jpm" - :template "docpage.html"} + :nav-title "API" + :template "docpage.html" + :order 5} --- ## Index -@gen-docs/gen-prefix-current[jpm/] +@gen-docs/gen-prefix-current[] diff --git a/content/api/jpm/make-config.mdz b/content/jpm/api/make-config.mdz similarity index 89% rename from content/api/jpm/make-config.mdz rename to content/jpm/api/make-config.mdz index db16894..8610c1b 100644 --- a/content/api/jpm/make-config.mdz +++ b/content/jpm/api/make-config.mdz @@ -1,4 +1,4 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import jpm/make-config :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/jpm" gen-docs/jpm-version)) (setdyn :no-community-examples true) diff --git a/content/api/jpm/pm.mdz b/content/jpm/api/pm.mdz similarity index 88% rename from content/api/jpm/pm.mdz rename to content/jpm/api/pm.mdz index ce24022..49060b8 100644 --- a/content/api/jpm/pm.mdz +++ b/content/jpm/api/pm.mdz @@ -1,4 +1,4 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import jpm/pm :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/jpm" gen-docs/jpm-version)) (setdyn :no-community-examples true) diff --git a/content/api/jpm/rules.mdz b/content/jpm/api/rules.mdz similarity index 88% rename from content/api/jpm/rules.mdz rename to content/jpm/api/rules.mdz index c0846de..7369960 100644 --- a/content/api/jpm/rules.mdz +++ b/content/jpm/api/rules.mdz @@ -1,4 +1,4 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import jpm/rules :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/jpm" gen-docs/jpm-version)) (setdyn :no-community-examples true) diff --git a/content/api/jpm/scaffold.mdz b/content/jpm/api/scaffold.mdz similarity index 89% rename from content/api/jpm/scaffold.mdz rename to content/jpm/api/scaffold.mdz index cd23a3f..419c907 100644 --- a/content/api/jpm/scaffold.mdz +++ b/content/jpm/api/scaffold.mdz @@ -1,4 +1,4 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import jpm/scaffold :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/jpm" gen-docs/jpm-version)) (setdyn :no-community-examples true) diff --git a/content/api/jpm/shutil.mdz b/content/jpm/api/shutil.mdz similarity index 89% rename from content/api/jpm/shutil.mdz rename to content/jpm/api/shutil.mdz index a5667e5..6fbf27b 100644 --- a/content/api/jpm/shutil.mdz +++ b/content/jpm/api/shutil.mdz @@ -1,4 +1,4 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import jpm/shutil :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/jpm" gen-docs/jpm-version)) (setdyn :no-community-examples true) diff --git a/content/jpm/building-projects.mdz b/content/jpm/building-projects.mdz new file mode 100644 index 0000000..d23e7c0 --- /dev/null +++ b/content/jpm/building-projects.mdz @@ -0,0 +1,101 @@ +{:title "Building Projects" + :template "docpage.html" + :order 1} +--- + +## Building projects with @code`jpm` + +Once you have the project on your machine, building the various artifacts should +be pretty simple. + +#### Global install + +@codeblock``` +sudo jpm deps +jpm build +jpm test +sudo jpm install +``` + +\(On Windows, @code`sudo` is not required. Use of @code`sudo` on POSIX systems +depends on whether you installed @code`janet` to a directory owned by the root +user.) + +#### User local install + +The JANET_TREE environment variable can be used to set the tree the jpm installs things to. +By default, running @code`janet` from the command line separately will not use modules in +the custom tree, so you will likely want to modify JANET_PATH as well. + +@codeblock``` +export JANET_TREE=$HOME/.local/jpm_tree +jpm deps +jpm build +jpm test +jpm install +# alternative: jpm --tree=$HOME/.local/jpm_tree deps +``` + +#### Project local install + +JPM also has some flags to install dependencies to a tree local to a project. Dependencies will +be installed to ./jpm_tree/lib (and binaries installed to ./jpm_tree/bin) when passing the @code`-l` +flag to jpm. + +@codeblock``` +jpm -l deps +jpm -l build +jpm -l test +# Run a janet interpreter in the local environment with access to all dependencies installed. +jpm -l janet +``` + +### Dependencies + +@p{@code`jpm deps` is a command that installs Janet libraries that the project + depends on recursively. It will automatically fetch, build, and install all + required dependencies for you. As of August 2019, this only works with git, + which you need to have installed on your machine to install dependencies. If + you don't have git you are free to manually obtain the requisite + dependencies and install them manually with @code`sudo jpm install`. +} + +### Building + +Next, we use the @code`jpm build` command to build artifacts. All built +artifacts will be created in the @code`build` subdirectory of the current +project. Therefore, it is probably a good idea to exclude the @code`build` +directory from source control. For building executables and native modules, you +will need to have a C compiler on your PATH where you run @code`jpm build`. For +POSIX systems, the compiler is @code`cc`. + +If you make changes to the source code after building once, @code`jpm` will try +to only rebuild what is needed on a rebuild. If this fails for any reason, you +can delete the entire build directory with @code`jpm clean` to reset things. + +#### Windows + +For Windows, the C compiler used by @code`jpm` is @code`cl.exe`, which is part +of MSVC. You can get it with Visual Studio, or standalone with the C and C++ +Build Tools from Microsoft. You will then need to run @code`jpm build` in a +Developer Command Prompt, or source @code`vcvars64.bat` in your shell to add +@code`cl.exe` to the PATH. + +### Testing + +Once we have built our software, it is a good idea to test it to verify that it +works on the current machine. @code`jpm test` will run all Janet scripts in the +@code`test` directory of the project and return a non-zero exit code if any +fail. + +### Installing + +Finally, once we have built our software and tested that it works, we can +install it on our system. For an executable, this means copying it to the +@code`bin` directory, and for libraries it means copying them to the global +syspath. You can optionally install into any directory if you don't want to +pollute your system or you don't have permission to write to the directory where +@code`janet` itself was installed. You can specify the path to install modules +to via the @code`--modpath` option, and the path to install binaries to with the +@code`--binpath` option. These need to be given before the subcommand +@code`install`. diff --git a/content/jpm/index.mdz b/content/jpm/index.mdz new file mode 100644 index 0000000..7042e31 --- /dev/null +++ b/content/jpm/index.mdz @@ -0,0 +1,52 @@ +{:title "The Janet Project Manager (jpm)" + :nav-title "JPM" + :template "docpage.html" + :order 5} +--- + +JPM is a build tool that can be installed along with Janet to help build and install +libraries for Janet. The main uses are installing dependencies, compiling C/C++ to native libraries, and +other project management tasks. The source code for JPM +can be found at @link[https://github.com/janet-lang/jpm.git][https://github.com/janet-lang/jpm.git]. +With janet already installed, JPM is also self bootstrapping. + +@codeblock``` +git clone --depth=1 https://github.com/janet-lang/jpm.git +cd jpm +sudo janet bootstrap.janet +``` + +The bootstrap script can also be configured to install jpm to +different directories by setting the @code`DESTDIR` environment +variable. Ideally, jpm should be installed to the same tree as Janet, +although this is not strictly required. See the README in jpm's +repository for more information. + +## Updating JPM + +Once installed and configured, JPM can update itself from the git repository at any time. + +@codeblock``` +sudo jpm install jpm +``` + +@p{@code`jpm`'s main functions are installing dependencies and building native + Janet modules, but it is meant to be used for much of the life-cycle for + Janet projects. Since Janet code doesn't usually need to be compiled, you + don't always need @code`jpm`, especially for scripts, but @code`jpm` comes + with some functionality that is difficult to duplicate, like compiling Janet + source code and all imported modules into a statically linked executable for + distribution. +} + +## Glossary + +A self-contained unit of Janet source code as recognized by @code`jpm` +is called a project. A project is a directory containing a +@code`project.janet` file, which contains build recipes. Often, a +project will correspond to a single git repository, and contain a +single library. However, a project's @code`project.janet` file can +contain build recipes for as many libraries, native extensions, and +executables as it wants. Each of these recipes builds an +artifact. Artifacts are the output files that will either be +distributed or installed on the end-user or developer's machine. diff --git a/content/jpm/local-install.mdz b/content/jpm/local-install.mdz new file mode 100644 index 0000000..af35adb --- /dev/null +++ b/content/jpm/local-install.mdz @@ -0,0 +1,19 @@ +{:title "Local Install" + :template "docpage.html" + :order 3} +--- + +## Local Installation, aka Custom Trees + +For per-project or per-user development (as opposed to system-wide development), you can use +custom jpm trees rather than a system default by passing the @code`--tree=` argument +all jpm commands or setting the @code`JANET_TREE` environment variable. This will set the location +where jpm will install modules, headers, scripts, and other data to. For project local development in +a tree @code`./jpm_tree`, you can use the @code`--local` or @code`-l` shorthand for this. + +@codeblock``` +jpm --tree=/opt/jpm_tree deps +jpm --tree=/opt/jpm_tree install spork +jpm -l deps +jpm -l test +``` \ No newline at end of file diff --git a/content/jpm/project.janet.mdz b/content/jpm/project.janet.mdz new file mode 100644 index 0000000..bc7d28d --- /dev/null +++ b/content/jpm/project.janet.mdz @@ -0,0 +1,170 @@ +{:title "Project.janet" + :template "docpage.html" + :order 2} +--- + +## The @code`project.janet` file + +To create your own software in Janet, it is a good idea to understand what the +@code`project.janet` file is and how it defines rules for building, testing, and +installing software. The code in @code`project.janet` is normal Janet source +code that is run in a special environment. + +A @code`project.janet` file is loaded by @code`jpm` and evaluated to create +various recipes, or rules. For example, @code`declare-project` creates several +rules, including @code`"install"`, @code`"build"`, @code`"clean"`, and +@code`"test"`. These are a few of the rules that @code`jpm` expects +@code`project.janet` to create when executed. + +### Declaring a project + +Use the @code`declare-project` as the first @code`declare-` macro towards the +beginning of your @code`project.janet` file. You can also pass in any metadata +about your project that you want, and add dependencies on other Janet projects +here. + +@codeblock[janet]``` +(declare-project + :name "mylib" # required + :description "a library that does things" # some example metadata. + + # Optional urls to git repositories that contain required artifacts. + :dependencies ["https://github.com/janet-lang/json.git"]) +``` + +### Creating a module + +A 100% Janet library is the easiest kind of software to distribute in Janet. +Since it does not need to be built and since installing it means simply moving +the files to a system directory, we only need to specify the files that comprise +the library in @code`project.janet`. + +@codeblock[janet]``` +(declare-source + # :source is an array or tuple that can contain + # source files and directories that will be installed. + # Often will just be a single file or single directory. + :source ["mylib.janet"]) +``` + +For information on writing modules, see @link[/docs/modules.html]{the modules docpage}. + +### Creating a native module + +Once you have written your C code that defines your native module (see the +@link[/capi/embedding.html]{embedding} page on how to do this), you must declare +it in @code`project.janet` in order for @code`jpm` to build the native modules +for you. + +@codeblock[janet]``` +(declare-native + :name "mynative" + :source ["mynative.c" "mysupport.c"] + :embedded ["extra-functions.janet"]) +``` + +This makes @code`jpm` create a native module called @code`mynative` when +@code`jpm build` is run, the arguments for which should be pretty +straightforward. The @code`:embedded` argument is Janet source code that will be +embedded as an array of bytes directly into the C source code. It is not +recommended to use the @code`:embedded` argument, as one can simply create +multiple artifacts, one for a pure C native module and one for Janet source +code. + +### Creating an executable + +The declaration for an executable file is pretty simple. + +@codeblock[janet]``` +(declare-executable + :name "myexec" + :entry "main.janet" + :install true) +``` + +@p{@code`jpm` is smart enough to figure out from the one entry file what + libraries and other code your executable depends on, and bundles them into + the final application for you. The final executable will be located at + @code`build/myexec`, or @code`build\myexec.exe` on Windows.} + +If the optional key-value pair @code`:install true` is specified in the +@code`declare-executable` form, by default, the appropriate @code`jpm install` +command will install the resulting executable to the @code`JANET_BINPATH` +\(but see the jpm man page for further details). + +Also note that the entry of an executable file should look different than a +normal Janet script. It should define a @code`main` function that can receive a +variable number of parameters, the command-line arguments. It will be called as +the entry point to your executable. + +@codeblock[janet]``` +(import mylib1) +(import mylib2) + +# This will be printed when you run `jpm build` +(print "build time!") + +(defn main + [& args] + # You can also get command-line arguments through (dyn :args) + (print "args: " ;(interpose ", " args)) + (mylib1/do-thing) + (mylib2/do-thing)) +``` + +It's important to remember that code at the top level will run when you invoke +@code`jpm build`, not at executable runtime. This is because in order to create +the executable, we marshal the @code`main` function of the app and write it to +an image. In order to create the main function, we need to actually compile and +run everything that it references, in the above case @code`mylib1` and +@code`mylib2`. + +This has a number of benefits, but the largest is that we only include bytecode +for the functions that our application uses. If we only use one function from a +library of 1000 functions, our final executable will not include the bytecode +for the other 999 functions (unless our one function references some of those +other functions, of course). This feature, called tree-shaking, only works +for Janet code. Native modules will be linked to the final executable statically +in full if they are used at all. A native module is considered "used" if is +imported at any time during @code`jpm build`. This may change, but it is +currently the most reliable way to check if a native modules needs to be linked +into the final executable. + +There are some limitations to this approach. Any dynamically required modules +will not always be linked into the final executable. If @code`require` or +@code`import` is not called during @code`jpm build`, then the code will not be +linked into the executable. The module can still be required if it is available +at runtime, though. + +For an example Janet executable built with @code`jpm`, see +@link[https://github.com/bakpakin/littleserver][https://github.com/bakpakin/littleserver]. + +### Other @code`declare-` callables + +Some additional @code`declare-` callables are: + +@ul{@li{@code`declare-bin` + + @p{Declare a generic file to be installed as an + executable. Specify file path via @code`:main`.}} + + @li{@code`declare-binscript` + + @p{Declare a janet file to be installed as an executable + script. Creates a shim on windows. If + @code`:hardcode-syspath` is true, will insert code into the + script such that it will run correctly even when + @code`JANET_PATH` is changed. If @code`:is-janet` is + truthy, will also automatically insert a correct shebang + line if jpm's configuration is set with + @code`:auto-shebang` as truthy.}} + + @li{@code`declare-headers` + + @p{Declare headers for a library installation. Installed + headers can be used by other native libraries. Specify + paths via @code`:headers` and prefix via @code`:prefix`.}} + + @li{@code`declare-manpage` + + @p{Mark a manpage for installation.}}} diff --git a/content/jpm/versioning.mdz b/content/jpm/versioning.mdz new file mode 100644 index 0000000..cf4509f --- /dev/null +++ b/content/jpm/versioning.mdz @@ -0,0 +1,25 @@ +{:title "Versioning and Bundling" + :template "docpage.html" + :order 4} +--- + +## Versioning and Library Bundling + +JPM does not do any semantic version resolution at the moment. Instead, it is recommended to make all changes +to libraries as backwards-compatible as possible, and release new libraries for breaking changes in almost all +cases. For creators of executable programs (versus a library author), it is recommended to use a local tree +and lockfiles to pin versions for consistent builds. + +As a matter of style, it is also recommended to group small libraries +together into "bundles" that are updated, tested, and deployed +together. Since Janet libraries are often quite small, the cost of +downloading more functionality that one might need isn't particularly +high, and JPM can remove unused functions and bindings from generated +standalone binaries and images, so there is no runtime cost either. By +avoiding a plethora of tiny libraries, users of libraries do not +manage as many dependencies, and modules are more likely to work +together they can be tested together. + +While @code`jpm` may superficially resemble @code`npm`, it is the +author's opinion that it is suited to a different style of +development. diff --git a/content/spork/api/argparse.mdz b/content/spork/api/argparse.mdz new file mode 100644 index 0000000..bb0803c --- /dev/null +++ b/content/spork/api/argparse.mdz @@ -0,0 +1,69 @@ +(import ../../gen-docs :as gen-docs) +(import spork/argparse :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "argparse" + :author "Calvin Rose" + :license "MIT" + :template "docpage.html"} +--- + +A moderately opinionated argument parser for +@link[https://janet-lang.org][janet]. Use this for writing +CLI scripts that need to have UNIX style switches and +options. + +## Sample + +@codeblock[janet]``` +#!/usr/bin/env janet + +(import spork/argparse :prefix "") + +(def argparse-params + ["A simple CLI tool. An example to show the capabilities of argparse." + "debug" {:kind :flag + :short "d" + :help "Set debug mode."} + "verbose" {:kind :multi + :short "v" + :help "Print debug information to stdout."} + "key" {:kind :option + :short "k" + :help "An API key for getting stuff from a server." + :required true} + "expr" {:kind :accumulate + :short "e" + :help "Search for all patterns given."} + "thing" {:kind :option + :help "Some option?" + :default "123"}]) + +(let [res (argparse ;argparse-params)] + (unless res + (os/exit 1)) + (pp res)) +``` + +## Usage + +Call @code`argparse/argparse` to attempt to parse the command line args +(available at @code`(dyn :args)`). + +The first argument should be a description to be displayed as help +text. + +All subsequent options should be alternating keys and values where the +keys are options to accept and the values are definitions of each option. + +To accept positional arguments, include a definition for the special +value @code`:default`. For instance, to gather all positional arguments +into an array, include @code`:default {:kind :accumulate}` in your +arguments to @code`argparse`. + +Run @code`(doc argparse/argparse)` after importing for more information. + +## Reference + +@gen-docs/gen-prefix-current[argparse/] diff --git a/content/spork/api/base64.mdz b/content/spork/api/base64.mdz new file mode 100644 index 0000000..762fb74 --- /dev/null +++ b/content/spork/api/base64.mdz @@ -0,0 +1,37 @@ +(import ../../gen-docs :as gen-docs) +(import spork/base64 :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "base64" + :author "Josef Pospíšil" + :license "MIT" + :template "docpage.html"} +--- + +This module contains Base64 utilities. + +## Examples + +### base64/encode + +Converts a string of any format (UTF-8, binary, ..) to base64 encoding. + +@codeblock[janet]``` +(misc/base64/encode "this is a test") +# => "dGhpcyBpcyBhIHRlc3Q=" +``` + +### base64/decode + +Converts a base64 encoded string to its binary representation of any format +(UTF-8, binary, ...). + +@codeblock[janet]``` +(misc/base64/decode "dGhpcyBpcyBhIHRlc3Q=") +# => "this is a test" +``` + +## Reference + +@gen-docs/gen-prefix-current[base64/] diff --git a/content/api/spork/build-rules.mdz b/content/spork/api/build-rules.mdz similarity index 61% rename from content/api/spork/build-rules.mdz rename to content/spork/api/build-rules.mdz index 1f2ac47..28a106e 100644 --- a/content/api/spork/build-rules.mdz +++ b/content/spork/api/build-rules.mdz @@ -1,13 +1,16 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import spork/build-rules :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "Parallel Building" - :nav-title "build-rules" +{:title "build-rules" :template "docpage.html"} --- -## Index +Run commands that produce files in an incremental manner. +Use to implement a build system. + +## Reference @gen-docs/gen-prefix-current[build-rules/] + diff --git a/content/spork/api/cc.mdz b/content/spork/api/cc.mdz new file mode 100644 index 0000000..ed8db99 --- /dev/null +++ b/content/spork/api/cc.mdz @@ -0,0 +1,33 @@ +(import ../../gen-docs :as gen-docs) +(import spork/cc :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "cc" + :template "docpage.html"} + --- + +Improved version of the C Compiler abstraction from JPM that should be more correct, composable, and +have less configuration. + +Wrapper around the system C compiler for compiling Janet native modules and executables. +Opinionated and optimized for use with Janet, and does not actually run +commands unless specified with (dyn *visit*). Also included is package config integration. +Headers, static libraries, and dynamic libraries can all be used from `(dyn *syspath*)`. + +## Example usage + +@codeblock[janet]``` +(use spork/cc) + +(search-static-libraries "m" "rt" "dl") +(search-dynamic-libraries "janet") +(pkg-config "sdl2" "vulkan") +(with-dyns [*defines* {"GAME_BUILD" "devel-0.0"} + *visit* visit-execute-if-stale] + (compile-and-link-executable "game" "main.c" "sound.c" "graphics.c")) +``` + +## Reference + +@gen-docs/gen-prefix-current[cc/] diff --git a/content/api/spork/channel.mdz b/content/spork/api/channel.mdz similarity index 70% rename from content/api/spork/channel.mdz rename to content/spork/api/channel.mdz index cb3081f..12652a1 100644 --- a/content/api/spork/channel.mdz +++ b/content/spork/api/channel.mdz @@ -1,13 +1,14 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import spork/channel :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "Channel Extras" - :nav-title "channel" +{:title "channel" :template "docpage.html"} ---- + --- -## Index +Channel utilities for Janet. + +## Reference @gen-docs/gen-prefix-current[channel/] diff --git a/content/spork/api/cjanet.mdz b/content/spork/api/cjanet.mdz new file mode 100644 index 0000000..8513ff9 --- /dev/null +++ b/content/spork/api/cjanet.mdz @@ -0,0 +1,19 @@ +(import ../../gen-docs :as gen-docs) +(import spork/cjanet :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "cjanet" + :template "docpage.html"} + --- + +A DSL that compiles to C. + Improved version of jpm/cgen that is more amenable to Janet integration, macros, and meta-programming. + +The semantics of the language are basically the +same as C so a higher level language (or type system) should be built on top of this. + This IR emits a very useful subset of valid C 99. + +## Reference + +@gen-docs/gen-prefix-current[cjanet/] diff --git a/content/api/spork/crc.mdz b/content/spork/api/cmath.mdz similarity index 54% rename from content/api/spork/crc.mdz rename to content/spork/api/cmath.mdz index 055605d..53c89da 100644 --- a/content/api/spork/crc.mdz +++ b/content/spork/api/cmath.mdz @@ -1,13 +1,12 @@ -(import ../gen-docs :as gen-docs) -(import spork/crc :export true) +(import ../../gen-docs :as gen-docs) +(import spork/cmath :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "CRC" - :nav-title "crc" +{:title "cmath" :template "docpage.html"} ---- + --- -## Index +## Reference -@gen-docs/gen-prefix-current[crc/] +@gen-docs/gen-prefix-current[cmath/] diff --git a/content/spork/api/crc.mdz b/content/spork/api/crc.mdz new file mode 100644 index 0000000..829eb43 --- /dev/null +++ b/content/spork/api/crc.mdz @@ -0,0 +1,16 @@ +(import ../../gen-docs :as gen-docs) +(import spork/crc :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "crc" + :template "docpage.html"} + --- + +Generate CRC (Cyclic Redundancy Check) variants. + Rather than compile separate variants, we have code to generate the needed tables. + Keeps build simple, footprint small but with many variants accessible. + +## Reference + +@gen-docs/gen-prefix-current[crc/] diff --git a/content/spork/api/cron.mdz b/content/spork/api/cron.mdz new file mode 100644 index 0000000..d9cae46 --- /dev/null +++ b/content/spork/api/cron.mdz @@ -0,0 +1,43 @@ +(import ../../gen-docs :as gen-docs) +(import spork/cron :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "cron" + :template "docpage.html"} + --- + +Timer library for interfacing with the UNIX crontab format. + +The cron format support is based on the unix cron syntax, with an optional seconds field. + Each field can be a comma separated list of individual values or a range of values. + +A range has three variants as follows: +@ol{ + @li{Two values with a "-" between them, optionally followed by a "/" and a step value.} + @li{An asterisk ("*") followed by a "/" and a step value. This implies every "step" value.} + @li{A single value followed by a "/" and a step value. This implies every "step" value starting with the single value. I.e., 2/3 implies every 3 units from 2 to max units.}} + +A single asterisk ("*") can be used to denote all possible values. + +The fields: +@ul{ + @li{minutes: 0-5 } + @li{hours: 0-2 } + @li{day of month: 1-3 } + @li{month: 1-12. Also allowed are the following month codes in any case } + jan,feb,mar,apr,may,jun,jul,aug,sep,oct,nov,dec + @li{day of week: 0-7, where 0 or 7 is sunday, monday is 1, etc. allows the following day codes (any case)} + sun,mon,tue,wed,thu,fri,sat + @li{ seconds (optional): 0-5}} + +Cron schedules are represented as tuples of 7 values, a string representation, followed +by 6 bitmaps representing matching timestamps. Bitmaps are represented as any byte sequence. + +@codeblock`[string-rep minutes hours day-of-month month day-of-week seconds]` + +Note that we have second precision here as opposed to minute precision. + +## Reference + +@gen-docs/gen-prefix-current[cron/] diff --git a/content/spork/api/data.mdz b/content/spork/api/data.mdz new file mode 100644 index 0000000..0250823 --- /dev/null +++ b/content/spork/api/data.mdz @@ -0,0 +1,46 @@ +(import ../../gen-docs :as gen-docs) +(import spork/data :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "data" + :author "Caleb Figgers" + :license "MIT" + :template "docpage.html"} +--- + +@p{@link[https://clojure.org/]{Clojure} contains a very useful core library (or "namespace" in Clojure parlance) called @link[https://clojure.github.io/clojure/clojure.data-api.html]{clojure.data} (@link[https://github.com/clojure/clojure/blob/51c6d7a70912a8f65e81a8e11ae6f56c94920725/src/clj/clojure/data.clj]{source}). It contains one "exported" function: @code`clojure.data/diff`. This addition to spork, @code`data.janet`, should exactly replicate the behavior of @code`clojure.data/diff` using Janet tables, structs, arrays, and tuples in place of their Clojure equivalents.} + +## Function + +The @code`diff` function recursively compares the structure and contents of two data structures (struct, table, tuple, array) and returns an array with three elements: + +@codeblock[janet]`@[things-only-in-a things-only-in-b things-in-both]` + +In the case of nested associative data structures (i.e., tables and structs), the comparison is recursive and the data structures are neatly partitioned into the same @code`@[things-only-in-a things-only-in-b things-in-both]` structure, but arbitrary levels deep in the two original associative data structures. + +This function makes comparing two structs or tables for changes trivial. (An example use case: compare the decoded JSON returned from a REST API call made seconds ago against the version of that same decoded JSON from that same API that was returned from the same call made an hour ago and stored locally in a database for comparison an hour later.) + +## Example + +So for example, @code`diff`'ing the two nested structs @code`{:a 1 :b 2 :c {:d 3 :e 4}}` and @code`{:a 4 :b 2 :c {:d 3 :e 5 :f 6}}` looks like this: + +@codeblock[janet]``` +repl:1:> (import spork/data :as d) +repl:2:> (d/diff {:a 1 :b 2 :c {:d 3 :e 4}} {:a 4 :b 2 :c {:d 3 :e 5 :f 6}}) +@[@{:a 1 :c @{:e 4}} @{:a 4 :c @{:e 5 :f 6}} @{:b 2 :c @{:d 3}}] +``` + +The return is @code`@[@{:a 1 :c @{:e 4}} @{:a 4 :c @{:e 5 :f 6}} @{:b 2 :c @{:d 3}}]` because: + +@ul{ + @li{the value for @code`:a` appears in both and is different in each one (so @code`:a` is a key in both the first and second returned table, with each value set as seen in the first and second original structs)} + @li{the value for @code`:b` appears in both and is the same in each (so @code`:b` is a key only in the third returned table, containing the shared value in both original strucs)} + @li{the nested value of @code`:d` appears in both and is the same in each (so @code`:c` is a key in the third returned table, containing the value of @code`:d` that is shared in both original structs)} + @li{the nested value of @code`:e` appears in both and is different in each one (so @code`:c` is a key in both the first and second returned table, containing the value @code`:e` with with each value set as seen in the first and second original structs), and} + @li{the key/value pair @code`:f` 6 only appears in the latter original struct (so only the second returned table contains @code`:f` and its value).} +} + +## Reference + +@gen-docs/gen-prefix-current[data/] diff --git a/content/api/spork/ev-utils.mdz b/content/spork/api/ev-utils.mdz similarity index 66% rename from content/api/spork/ev-utils.mdz rename to content/spork/api/ev-utils.mdz index cc7c24f..50b585c 100644 --- a/content/api/spork/ev-utils.mdz +++ b/content/spork/api/ev-utils.mdz @@ -1,13 +1,14 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import spork/ev-utils :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "EV Utilities" - :nav-title "ev-utils" +{:title "ev-utils" :template "docpage.html"} ---- + --- -## Index +Module for parallel execution utilities with Janet. + +## Reference @gen-docs/gen-prefix-current[ev-utils/] diff --git a/content/spork/api/fmt.mdz b/content/spork/api/fmt.mdz new file mode 100644 index 0000000..a361ca5 --- /dev/null +++ b/content/spork/api/fmt.mdz @@ -0,0 +1,34 @@ +(import ../../gen-docs :as gen-docs) +(import spork/fmt :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "fmt" + :author "Calvin Rose" + :license "MIT" + :template "docpage.html"} +--- + +Provides a way to format Janet code strings and files. + +## Examples + +### Strings + +@codeblock[janet]``` +(import spork/fmt) + +(fmt/format "(def a\n 3 )") => @"(def a\n 3)\n" +``` + +### Files + +@codeblock[janet]``` +(import spork/fmt) + +(fmt/format-file "main.janet") +``` + +## Reference + +@gen-docs/gen-prefix-current[fmt/] diff --git a/content/spork/api/generators.mdz b/content/spork/api/generators.mdz new file mode 100644 index 0000000..a96fe38 --- /dev/null +++ b/content/spork/api/generators.mdz @@ -0,0 +1,25 @@ +(import ../../gen-docs :as gen-docs) +(import spork/generators :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "generators" + :author "Z. D. Smith" + :license "BSD3" + :template "docpage.html"} +--- + +A @strong[generator] is an iterable data structure which yields individual values whenever called, potentially until its internal values are exhausted, at which point it's considered dead. + +This operation makes them very useful for: + +@ul{@li{Asynchronous behaviour} + @li{Memory-sensitive applications, where it's not necessary to keep an entire sequence in memory at once} + @li{Infinite sequences}} + +NB: Certain functions (specifically @code`run` and @code`to-array`) will create an infinite loop if their argument is an infinite generator! + +## Reference + +@gen-docs/gen-prefix-current[generators/] + diff --git a/content/api/spork/getline.mdz b/content/spork/api/getline.mdz similarity index 57% rename from content/api/spork/getline.mdz rename to content/spork/api/getline.mdz index 6d12f31..7d73c7b 100644 --- a/content/api/spork/getline.mdz +++ b/content/spork/api/getline.mdz @@ -1,13 +1,14 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import spork/getline :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "Getline" - :nav-title "getline" +{:title "getline" :template "docpage.html"} ---- + --- -## Index +Module for fiber-based sequence combinators rather than array-based combinators, as are in the core library. + +## Reference @gen-docs/gen-prefix-current[getline/] diff --git a/content/spork/api/htmlgen.mdz b/content/spork/api/htmlgen.mdz new file mode 100644 index 0000000..22bcabc --- /dev/null +++ b/content/spork/api/htmlgen.mdz @@ -0,0 +1,60 @@ +(import ../../gen-docs :as gen-docs) +(import spork/htmlgen :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "htmlgen" + :author "Calvin Rose" + :license "MIT" + :template "docpage.html"} +--- + +HTMLgen is a rendering engine that can render plain data structures into +an HTML string. Its API has only one constant and two functions: + +@ul{ + @li{constant @code`doctype` is a string with html5 doctype header} + @li{function @code`raw` returns the function that will add the raw string, passed as an argument to the function, to the output, when rendered, without any escaping.} + @li{function @code`html` has one required argument @code`data` with the data structure rendered into bytes with HTML code. And optional @code`buf` to which function renders final bytes. If you do not provide the @code`buf`, it will create a new one.} } + +## Rules for rendering data structures + +Example: + +@codeblock[janet]``` +(use spork/htmlgen) +(defn append-year [buf] (buffer/push buf (string ((os/date) :year)))) +(html + @[[:head + @[[:meta {:charset "htf-8"}] + [:title "Spork"]]] + [:body + @[[:header "Menu"] + [:main [:section "News"]] + [:footer "All right reserved " append-year]]]]) + +=> @"Spork
Menu
News
All right reserved 2022
" +``` + +We will show how HTMLgen renders from the data structure by dissecting +the example above: + +@ul{ + @li{`array` (and @code`fiber` which is not in the example) each member of + the sequence renders by one of these rules.} + @li{@code`tuple` represents the HTML tag. The first member must be the name of + the HTML tag. The second member can be a dictionary with HTML attributes + for the HTML tag. All the other members are children of the tag and renders + according to these rules.} + @li{@code`string`, @code`buffer`, @code`number` and @code`boolean` coerces to string and, + if necessary, escaped and pushed to the buffer.} + @li{@code`function` gets the buffer, with which it can do whatever it wants to, + presumably push some more content, but anything.} + @li{@code`nil` do not do anything to the buffer.} +} + +As you may see, the rules are straightforward, yet with the @code`fiber` and @code`function` types you have pretty endless possibilities when constructing the HTML code from data structures. + +## Reference + +@gen-docs/gen-prefix-current[htmlgen/] diff --git a/content/spork/api/http.mdz b/content/spork/api/http.mdz new file mode 100644 index 0000000..90c0e92 --- /dev/null +++ b/content/spork/api/http.mdz @@ -0,0 +1,46 @@ +(import ../../gen-docs :as gen-docs) +(import spork/http :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "http" + :author "Calvin Rose" + :license "MIT" + :template "docpage.html"} +--- + +The @code`http` module is an HTTP/1.1 parser, server and client module. It proves a simple server implementation, client, support for chunked encoding. +The @code`http` module is also non-blocking, so a single thread can run +many clients, servers, and connections at once. + +## Examples + +### Server + +@codeblock[janet]``` +(import spork/http) + +(defn handler + [req] + (def method (get req :method)) + (case method + "GET" {:status 200 :body (get req :path)} + "POST" {:status 400 :body (http/read-body req)} + {:status 404})) + +(http/server handler "127.0.0.1" "9000") +``` + +### Client + +@codeblock[janet]``` +(import spork/http) + +(def response (http/request "GET" "http://www.example.com")) +(def body (http/read-body response)) +(print body) +``` + +## Reference + +@gen-docs/gen-prefix-current[http/] diff --git a/content/api/spork/httpf.mdz b/content/spork/api/httpf.mdz similarity index 52% rename from content/api/spork/httpf.mdz rename to content/spork/api/httpf.mdz index fc2ec07..ace4a52 100644 --- a/content/api/spork/httpf.mdz +++ b/content/spork/api/httpf.mdz @@ -1,13 +1,16 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import spork/httpf :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "HTTP Framework" - :nav-title "httpf" +{:title "httpf" :template "docpage.html"} ---- + --- -## Index +A simple, opinionated HTTP framework for HTML, JDN, and JSON servers. +Servers can easily be configured from defn bindings with +appropriate metadata. + +## Reference @gen-docs/gen-prefix-current[httpf/] diff --git a/content/api/spork/test.mdz b/content/spork/api/index.mdz similarity index 60% rename from content/api/spork/test.mdz rename to content/spork/api/index.mdz index 1fff2b4..1956e17 100644 --- a/content/api/spork/test.mdz +++ b/content/spork/api/index.mdz @@ -1,13 +1,13 @@ -(import ../gen-docs :as gen-docs) -(import spork/test :export true) +(import ../../gen-docs :as gen-docs) +(import spork :prefix "" :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "Test" - :nav-title "test" +{:title "Spork API" + :nav-title "API" :template "docpage.html"} --- ## Index -@gen-docs/gen-prefix-current[test/] +@gen-docs/gen-prefix-current[] \ No newline at end of file diff --git a/content/spork/api/infix.mdz b/content/spork/api/infix.mdz new file mode 100644 index 0000000..333e647 --- /dev/null +++ b/content/spork/api/infix.mdz @@ -0,0 +1,42 @@ +(import ../../gen-docs :as gen-docs) +(import spork/infix :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "infix" + :template "docpage.html"} + --- + +A macro for infix syntax in Janet. Useful for math. + +## Examples + +@codeblock[janet]``` + ($$ a + b ** 2) ---> (+ a (math/pow b 2)) + ($$ (a + b) ** 2) ---> (math/pow (+ a b) 2) + ($$ y[2] + y[3]) ---> (+ (in y 2) (in y 3)) + ($$ a > b and ,(good? z)) ---> (and (> a b) (good? z)) +``` + +## Syntax + +Syntax is as follows: + + Binary operators <<, >>, >>>, =, !=, <, <=, >, >=, &, ^, bor, band, and, or, + +, -, *, /, %, ** are supported. Operator precedence is in the + `precedence table below (higher means more tightly binding). All + operators are left associative except ** (math/pow), which is right + associative. + + Unary prefix operators !, -, bnot, not, ++, -- are supported. + No unary postfix operators are supported. + + Square brackets can be used for indexing. + + Normal parentheses are used for making subgroups + + You can "escape" infix syntax use a quote or unquote (comma) + +## Reference + +@gen-docs/gen-prefix-current[infix/] diff --git a/content/api/spork/json.mdz b/content/spork/api/json.mdz similarity index 68% rename from content/api/spork/json.mdz rename to content/spork/api/json.mdz index 919b42b..4845bc7 100644 --- a/content/api/spork/json.mdz +++ b/content/spork/api/json.mdz @@ -1,13 +1,14 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import spork/json :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "JSON" - :nav-title "json" +{:title "json" :template "docpage.html"} ---- + --- -## Index +JSON encoding and decoding for Janet. + +## Reference @gen-docs/gen-prefix-current[json/] diff --git a/content/api/spork/math.mdz b/content/spork/api/math.mdz similarity index 54% rename from content/api/spork/math.mdz rename to content/spork/api/math.mdz index 99740d5..279dee4 100644 --- a/content/api/spork/math.mdz +++ b/content/spork/api/math.mdz @@ -1,13 +1,17 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import spork/math :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "Math extended" - :nav-title "math" +{:title "math" + :author "Josef Pospíšil" + :license "MIT" :template "docpage.html"} --- -## Index +The math module deals with two main areas of mathematics: statistics and linear algebra. + +## Reference @gen-docs/gen-prefix-current[math/] + diff --git a/content/api/spork/mdz.mdz b/content/spork/api/mdz.mdz similarity index 63% rename from content/api/spork/mdz.mdz rename to content/spork/api/mdz.mdz index 88444a4..dd2cde9 100644 --- a/content/api/spork/mdz.mdz +++ b/content/spork/api/mdz.mdz @@ -1,13 +1,14 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import spork/mdz :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "MDZ Document Generation" - :nav-title "mdz" +{:title "mdz" :template "docpage.html"} ---- + --- -## Index +Re-implementation of mendoza markup. Designed to work with htmlgen. + +## Reference @gen-docs/gen-prefix-current[mdz/] diff --git a/content/spork/api/misc.mdz b/content/spork/api/misc.mdz new file mode 100644 index 0000000..36b754b --- /dev/null +++ b/content/spork/api/misc.mdz @@ -0,0 +1,334 @@ +(import ../../gen-docs :as gen-docs) +(import spork/misc :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "misc" + :author "Calvin Rose" + :license "MIT" + :template "docpage.html"} +--- + +Miscellaneous utilities for Janet. + +## Dedent + +Remove indentation after concatenating the arguments. + +@codeblock[janet]``` +(misc/dedent `` + ho + hoho + hohoho +``))))) => "ho\n hoho\n hohoho" +``` + +## set* + +Allow parallel mutation of multiple mutable variables. (All right +hand sides are computed before setting the left hand sides.) + +@codeblock[janet]``` +# you can use it with vars +(var a 2) +(var b 3) +(misc/set* [a b] [b (+ a b)]) +[a b] => [3 5] + +# or you can use it with arrays, for example: +(def x @[2 3]) +(misc/set* [[x 0] [x 1]] [(in x 1) (+ (in x 0) (in x 1))]) +x => @[3 5] +``` + +## print-table + +Given a list of tables containing column keys with corresponding row +values, print its content to stdout in a human-readable tabular +layout. For example: + +@codeblock[janet]``` +(misc/print-table [ + {:x "abc" :y "123"} + {:x "hello" :y "world"} + {:x "banana" :y "orange"} + {:x "cat" :y "dog"}]) + +``` + +produces: + +@codeblock``` +x y +════════════════ + abc 123 + hello world + banana orange + cat dog +``` + +## map-keys + +Returns new table with function applied to table's keys recursively. + +@codeblock[janet]``` +(misc/map-keys string {1 2 3 4}) +# => @{"1" 2 "3" 4} +``` + +## map-vals + +Returns new table with function applied to table's values. + +@codeblock[janet]``` +(misc/map-vals string {1 2 3 4}) +# => @{1 "2" 3 "4"} +``` + +## select-keys + +Returns new table with selected keys from dictionary. + +@codeblock[janet]``` +(misc/select-keys {1 2 3 4 5 6} [1 5]) +# => @{1 2 5 6} +``` + +## cond-> + +Threading conditional macro. It takes value to mutate, and clauses pairs with a +condition and a operation to which the value is put as the first argument. All +conditions are tried and for truthy conditions the operation is performed. + +Returns the value mutated if any condition is truthy. + +@codeblock[janet]``` +(misc/cond-> @{:a :b} + (pos? 1) (put :a :c) + (pos? 0) (put :a :d)) +# => @{:a :c} +``` + +## cond->> + +Threading conditional macro. It takes value to mutate, and clauses pairs of a +condition and a operation to which the value, is put as the last argument. All +conditions are tried and for truthy the operation is performed. + +Returns mutated value if any condition is truthy. + +@codeblock[janet]``` +(misc/cond->> @{:a :b} + (pos? 1) (merge {:d :e}) + (pos? 0) (merge {:e :f})) +# => @{:a :b :d :e} +``` + +## make + +Convenience macro for creating new table from even number of kvs pairs in a variadic +pairs arguments and setting its prototype to prototype. + +Factory function for creating new objects from prototypes. + +@codeblock[janet]``` +(def Proto @{:greet (fn [self] (string "Hello " (self :name)))}) +(def t (misc/make Proto :name "pepe")) +(:greet t) +# => "Hello pepe" +``` + +## do-var + +Convenience macro for defining varible with value before body and returning +it after evaluating body, that presumably modifies variable. + +@codeblock[janet]``` +(misc/do-var res 0 (set res 100) (++ res)) +# => 101 +``` + +## do-def + +Convenience macro for defining constant with value before body and returning it +after evaluating body, that presumably modifies the const refered content. For +example buffer, table or array. + +@codeblock[janet]``` +(misc/do-def res @"" (buffer/push res "a")) +# => @"a" +``` + +## capout + +Captures the standart output of the variadic body and returns it as a buffer. + +@codeblock[janet]``` +(misc/capout + (def p "HOHOHO") + (prin p)) +# => @"HOHOHO" +``` + +## caperr + +Captures the standart error output of the variadic body and returns it as +a buffer. + +@codeblock[janet]``` +(misc/caperr + (def p "HOHOHO") + (eprin p)) +# => @"HOHOHO" +``` + +## vars + +Defines many variables as in let bindings, but without creating new scope. + +@codeblock[janet]``` +(do (misc/vars a 2 b 1) a) +# => 2 +``` + +## always + +Return a function that discards any arguments and always returns its argument. + +@codeblock[janet]``` +(def always-true (misc/always true)) +(always-true) +# => true +(always-true) +# => true +(always-true 1 2 3) +# => true +``` + +## second + +Get the second element from an indexed data structure. + +@codeblock[janet]``` +(misc/second [1 2 3]) +# => 2 +``` + +## third + +Get the third element from an indexed data structure. + +@codeblock[janet]``` +(misc/third [1 2 3]) +# => 3 +``` + +## penultimate + +Get the second-to-last element from an indexed data structure. + +@codeblock[janet]``` +(misc/penultimate [1 2 3 4 5]) +# => 4 +``` + +## antepenultimate + +Get the third-to-last element from an indexed data structure. + +@codeblock[janet]``` +(misc/antepenultimate [1 2 3 4 5]) +# => 3 +``` + +## int/ + +Perform an integer division. + +@codeblock[janet]``` +(misc/int/ 11 3) 3 +``` + +## gett + +Recursive macro get. Similar to get-in, but keys are variadic argument. + +@codeblock[janet]``` +(misc/gett {:a {:b {:c :c}}} :a :b :c) +# => :c +``` + +## until +Repeat the body while the condition is false. + +Equivalent to `(while (not cnd) ;body)`. + +@codeblock[janet]``` +(misc/do-var res 0 (misc/until (> res 3) (++ res))) +# => 4 +``` + +## table-filter + +Filter a key-value structure info a table. Semantics are the same as for +built-in filter, except that predicate takes two arguments (key and value.) + +Does not consider prototypes. + +@codeblock[janet]``` +(misc/table-filter |(even? $1) @{:zero 0 :one 1 :two 2 :three 3}) +# => @{:zero 0 :two 2} +``` + +## buffer/reverse + +Reverse a buffer in-place. + +@codeblock[janet]``` +(misc/buffer/reverse @"abcd") +# => @"dcba" +``` + +## string->int + +Parses an integer in the given base. Defaults to decimal (base 10). Differs +from scan-number in that this does not recognize floating point notation. + +@codeblock[janet]``` +(misc/string->int "101" 2) +# => 2r101 +``` + +## int->string + +Stringify an integer in a particular base. Defaults to decimal (base 10). + +@codeblock[janet]``` +(misc/int->string 2r11011011 2) +# => "11011011" +``` + +## insert-sorted + +Insert elements in array such that it remains sorted by the comparator. If +array is not sorted beforehand, the results are undefined. Returns array. + +@codeblock[janet]``` +(misc/insert-sorted @[1 2 3 5] < 4) +# => @[1 2 3 4 5] +``` + +## insert-sorted-by + +Insert elements in array such that it remains sorted by the value returned +when function is called with the element, comparing the values with <. If the +array is not sorted beforehand, the results are undefined. Returns the array. + +@codeblock[janet]``` +(misc/insert-sorted-by @[1 2 3 5] identity 4) +# => @[1 2 3 4 5] +``` + +## Reference + +@gen-docs/gen-prefix-current[misc/] diff --git a/content/spork/api/msg.mdz b/content/spork/api/msg.mdz new file mode 100644 index 0000000..353c4e8 --- /dev/null +++ b/content/spork/api/msg.mdz @@ -0,0 +1,32 @@ +(import ../../gen-docs :as gen-docs) +(import spork/msg :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "msg" + :author "Calvin Rose" + :license "MIT" + :template "docpage.html"} +--- + +Provide a symmetric way to send and receive seqential messages over a +networked stream. Useful for building more complicated application +level protocols on top of TCP. + +## Examples + +@codeblock[janet]``` +(import spork/msg) + +(def stream (net/connect "http://example.com" "1234")) + +(def send (msg/make-send stream)) +(def recv (msg/make-recv stream)) + +(send "blob1") +(def blob-respose (recv)) +``` + +## Reference + +@gen-docs/gen-prefix-current[msg/] diff --git a/content/spork/api/netrepl.mdz b/content/spork/api/netrepl.mdz new file mode 100644 index 0000000..e010ea6 --- /dev/null +++ b/content/spork/api/netrepl.mdz @@ -0,0 +1,79 @@ +(import ../../gen-docs :as gen-docs) +(import spork/netrepl :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "netrepl" + :template "docpage.html"} + --- + +A simple async networked repl (both client and server) with a remote debugger +and the ability to repl into existing environments. + + +## Specifying the Environment + +Provide various ways to produce the environment to repl into. +@ol{ + @li{an environment factory function, called for each connection.} + @li{an env (table value) - this means every connection will share the same environment} + @li{default env, made via make-env with nice printing for each new connection.} +} + +## NETREPL Protocol + +Clients don't need to support steps 4. and 5. if they never send messages prefixed with 0xFF or 0xFE bytes. These bytes should not occur in normal Janet source code and are not even valid utf8. + +Any message received by the client that begins with 0xFF should result in printing the message to a console, but not otherwise interrupt the flow of the protocol. + This easily allows for partial results. A server should not send messages leading with 0xFF to the client unless the client is created with the :auto-flush connection setting. + +Any message received by the client that begins with 0xFE will discard this first byte and continue processing as usual. + +@ol{ + @li{server <- {connection settings, including client name@code[}] <- client + @ol{@li{If msg starts with 0xFF, parse message as (-> msg (slice 1) parse) and extract the :name key as the name. Other connection settings can be stored here.} + @li{If msg does not start with 0xFF, the message is treated as the client name. Other options are considered nil.}}} + @li{server -> {repl prompt (no newline)@code[}] -> client} + @li{server <- {one chunk of input (msg)@code[}] <- client} + @li{If (= (msg 0) 0xFF) + @ol{@li{(def result (-> msg (slice 1) parse eval protect))} + @li{server -> result -> client} + @li{goto 3.}}} + @li{If (= (msg 0) 0xFE)} + @ol{@li{Return msg as either: + @ol{@li{a keyword if the msg contains a command (e.g. :cancel)} + @li{an array if the msg contains a command and arguments (e.g. @code`@[:source "path/to/source"]`}} + @li{goto 6b.}}} + @li{Otherwise + @ol{@li{Send chunk to repl input stream} + @li{Unless auto-flush is enabled, server -> {(dyn :out) and (dyn :err) (empty at first)@code[}] -> client} + @li{goto 2.}}} +} + +## Examples + +Launch a networked REPL server on one machine and connect to it from another machine or process. + +### Server + +@codeblock[janet]``` +(import spork/netrepl) + +(def some-def 10) + +# Serve a repl into the current environment (@code`some-def` will be visible). +(netrepl/server "127.0.0.1" "9000" (fiber/getenv (fiber/current))) +``` + +### Client + +@codeblock[janet]``` +(import spork/netrepl) + +# Starts a nice terminal repl. +(netrepl/client "127.0.0.1" "9000" "bob") +``` + +## Reference + +@gen-docs/gen-prefix-current[netrepl/] diff --git a/content/spork/api/path.mdz b/content/spork/api/path.mdz new file mode 100644 index 0000000..86737b4 --- /dev/null +++ b/content/spork/api/path.mdz @@ -0,0 +1,46 @@ +(import ../../gen-docs :as gen-docs) +(import spork/path :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "path" + :author "Calvin Rose" + :license "MIT" + :template "docpage.html"} +--- + +Simple path manipulation module for Janet. Supports manipulation both +windows and posix paths on any platform, and provides functions that +work according to the current host platform. + +All functions have three forms, under @code`path`, @code`path/win`, and +@code`path/posix`. The prefix indicates which type of path the function +manipulates. + +## Example + +@codeblock[janet]``` + +(import spork/path) + +# Examples for a non-windows system, use path/win/ for windows and +# path/posix/ for posix. + +(path/ext "my/long/path.txt") # -> ".txt" +path/sep # -> "/" on posix, "\\" on windows +path/delim # -> ":" on posix, ";" on windows +(path/basename "some/path.txt") # -> "path.txt" +(path/dirname "some/path.txt") # -> "some/" +(path/parts "some/path/file.txt") # -> ["some" "path" "file.txt"] +(path/normalize "some/.././thing/file.txt") # -> "thing/file.txt" +(path/join "some/path" "../thing/file.txt") # -> "some/thing/file.txt" +(path/abspath? "/home/blah") # -> true +(path/abspath "file.txt") # -> "/home/me/cwd/file.txt" +(path/relpath + "a/nested/directory/with/a/few/children" + "a/nested/directory/with/different/children") # -> "../../../different/children" +``` + +## Reference + +@gen-docs/gen-prefix-current[path/] diff --git a/content/api/spork/pgp.mdz b/content/spork/api/pgp.mdz similarity index 58% rename from content/api/spork/pgp.mdz rename to content/spork/api/pgp.mdz index 760ea65..2c6a4bc 100644 --- a/content/api/spork/pgp.mdz +++ b/content/spork/api/pgp.mdz @@ -1,13 +1,17 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import spork/pgp :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "PGP" - :nav-title "pgp" +{:title "pgp" + :author "Josef Pospíšil" + :license "MIT" :template "docpage.html"} --- -## Index +This module contains PGP utils. For now only PGP words and hexs. + +## Reference @gen-docs/gen-prefix-current[pgp/] + diff --git a/content/spork/api/randgen.mdz b/content/spork/api/randgen.mdz new file mode 100644 index 0000000..708812a --- /dev/null +++ b/content/spork/api/randgen.mdz @@ -0,0 +1,32 @@ +(import ../../gen-docs :as gen-docs) +(import spork/randgen :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "randgen" + :author "Calvin Rose" + :license "MIT" + :template "docpage.html"} +--- + +A small utility for random number generation, especially with a focus on +discrete numbers. The most powerful idea here is the ability to have branches +that execute in a probabilistic manner - i.e. one branch is taken half the time +randomly, and another is taken otherwise. + +## Example + +@codeblock[janet]``` +# Print either a, b, or c +(import spork/randgen) +(randgen/rand-path + (print "a") + (print "b") + (print "c")) +``` + +## Reference + +@gen-docs/gen-prefix-current[randgen/] + + diff --git a/content/api/spork/rawterm.mdz b/content/spork/api/rawterm.mdz similarity index 69% rename from content/api/spork/rawterm.mdz rename to content/spork/api/rawterm.mdz index db4b602..5fc957e 100644 --- a/content/api/spork/rawterm.mdz +++ b/content/spork/api/rawterm.mdz @@ -1,13 +1,14 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import spork/rawterm :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "Raw Terminal Functionality" - :nav-title "rawterm" +{:title "rawterm" :template "docpage.html"} ---- + --- -## Index +Raw terminal utilities for Janet. + +## Reference @gen-docs/gen-prefix-current[rawterm/] diff --git a/content/spork/api/regex.mdz b/content/spork/api/regex.mdz new file mode 100644 index 0000000..abd665b --- /dev/null +++ b/content/spork/api/regex.mdz @@ -0,0 +1,36 @@ +(import ../../gen-docs :as gen-docs) +(import spork/regex :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "regex" + :author "Calvin Rose" + :license "MIT" + :template "docpage.html"} +--- + +A module for compiling a subset of regexes to Janet PEGs. + All regex are considered to be anchored, and performance is not going to be competitive with a native regex engine. + + +Supported regex features: + +@ul{ + @li{ single bytes} + @li{ escape characters} + @li{ @code`+`, @code`*`, @code`?`, @code`.`} + @li{ Repetitions, e.g. @code`a{1}`, @code`a{1,3}`. Repetitions are eagerly evaluated.} + @li{ Ranges, e.g. @code`[A-Za-z]`} + @li{ Character classes, inverted character classes, e.g. @code`[abc]`, @code`[^abc]`} + @li{ Alteration (choice), except alteration is ordered, as in pegs -- e.g. @code`a|b|c`} + @li{ Captures using parentheses, e.g. @code`(abc)`} + @li{ Non-capture groups, e.g. @code`(?:abc)`} +} + +Features found in other regex may never be added - for more complex usage, use Janet's native PEG library. + +## Reference + +@gen-docs/gen-prefix-current[regex/] + + diff --git a/content/spork/api/rpc.mdz b/content/spork/api/rpc.mdz new file mode 100644 index 0000000..dbd9d7b --- /dev/null +++ b/content/spork/api/rpc.mdz @@ -0,0 +1,46 @@ +(import ../../gen-docs :as gen-docs) +(import spork/rpc :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "rpc" + :author "Calvin Rose" + :license "MIT" + :template "docpage.html"} +--- + +A simple remote procedure call tool for Janet. + +## Server + +@codeblock[janet]``` +(import spork/rpc) + +(def functions + @{:print (fn [self x] (print "remote print: " x)) + :add (fn [self & xs] (sum xs))}) + +(rpc/server functions "127.0.0.1" "9001") +``` + + +## Client + +@codeblock[janet]``` +(import spork/rpc) + +(def c (rpc/client "127.0.0.1" "9001" "joe")) + +# Will print on server +(:print c "Hello from client!") + +(:add c 1 3 5 7 9) # -> 25 + +# Close the underlying connection +(:close c) +``` + +## Reference + +@gen-docs/gen-prefix-current[rpc/] + diff --git a/content/spork/api/schema.mdz b/content/spork/api/schema.mdz new file mode 100644 index 0000000..d68368b --- /dev/null +++ b/content/spork/api/schema.mdz @@ -0,0 +1,48 @@ +(import ../../gen-docs :as gen-docs) +(import spork/schema :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "schema" + :template "docpage.html"} + --- + +Simple schema validation library. Specify structure declaratively, and get +functions that will check that structure and either raise an error or return a boolean. +While reasonably general, use is intended for data such as one would find +in configuration files or network protocols. + +Currently does not support more advanced features such as: +@ul{ + @li{Recursive schemas} + @li{Full error reporting (only a single error is reported)} + @li{PEG style grammars (used to enable recursion in PEGs)} + @li{Unification (such as in the @code`(match)` macro)} + @li{Parsing/data extraction} +} + +Syntax: +@ul{ +@li{@code`:keyword` - match any value of that type} +@li{Tuples are used to match various combinators: +@ul{ + @li{@code`(any)` - match any one value} + @li{@code`(enum & options)` - match any of the option values} + @li{@code`(or & schemas)` - similar to enum, but each option is considered a schema.} + @li{@code`(and & schemas)` - Only matches if all clauses match} + @li{@code`(values schema)` - Matches only if schema matches all values in a data structure.} + @li{@code`(keys schema)` - Matches only if schema matches all keys in a data structure.} + @li{@code`(props & k v)` - Takes a sequence of keys and values (alternating in order). Only matches} + the data if, for a key, the corresponding schema `v` matches. + @li{@code`(length l)` - Only match if the data has a length of l. Uses of the length combinator should assert the data type before doing a length check.} + @li{@code`(length min max)` - Only match lengths between min and max inclusive} + @li{@code`(peg pattern)` - Matches only if the peg matches} + @li{@code`(not pattern)` - Only matches if pattern does not match} + @li{@code`(pred predicate)` - Use a predicate function (function of 1 argument) to check if the data is valid.} +}} +@li{anything else - match that value literally} +} + +## Reference + +@gen-docs/gen-prefix-current[schema/] diff --git a/content/spork/api/services.mdz b/content/spork/api/services.mdz new file mode 100644 index 0000000..4e4bf63 --- /dev/null +++ b/content/spork/api/services.mdz @@ -0,0 +1,17 @@ +(import ../../gen-docs :as gen-docs) +(import spork/services :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "services" + :template "docpage.html"} + --- + +Module for running a number of background processes in a controlled manner. + Similar to @link[ev-utils.html][ev-utils], but more involved with defaults for IO and naming fibers for debugging purposes. + +Services can also implicitly launch sibling or child services if needed. + +## Reference + +@gen-docs/gen-prefix-current[services/] diff --git a/content/api/spork/sh.mdz b/content/spork/api/sh.mdz similarity index 71% rename from content/api/spork/sh.mdz rename to content/spork/api/sh.mdz index 1e01a7d..3d217b7 100644 --- a/content/api/spork/sh.mdz +++ b/content/spork/api/sh.mdz @@ -1,13 +1,14 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import spork/sh :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "Shell Utilities" - :nav-title "sh" +{:title "sh" :template "docpage.html"} ---- + --- -## Index +Shell utilities for Janet. + +## Reference @gen-docs/gen-prefix-current[sh/] diff --git a/content/api/spork/stream.mdz b/content/spork/api/stream.mdz similarity index 70% rename from content/api/spork/stream.mdz rename to content/spork/api/stream.mdz index 5a32928..b58b6be 100644 --- a/content/api/spork/stream.mdz +++ b/content/spork/api/stream.mdz @@ -1,13 +1,14 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import spork/stream :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "Stream Utilities" - :nav-title "stream" +{:title "stream" :template "docpage.html"} ---- + --- -## Index +Stream utilities for Janet. + +## Reference @gen-docs/gen-prefix-current[stream/] diff --git a/content/api/spork/tarray.mdz b/content/spork/api/tarray.mdz similarity index 70% rename from content/api/spork/tarray.mdz rename to content/spork/api/tarray.mdz index 1576a96..a8b381b 100644 --- a/content/api/spork/tarray.mdz +++ b/content/spork/api/tarray.mdz @@ -1,13 +1,15 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import spork/tarray :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "Typed Arrays" - :nav-title "tarray" +{:title "tarray" :template "docpage.html"} ---- + --- -## Index +Typed array abstract type. + +## Reference @gen-docs/gen-prefix-current[tarray/] + diff --git a/content/api/spork/tasker.mdz b/content/spork/api/tasker.mdz similarity index 56% rename from content/api/spork/tasker.mdz rename to content/spork/api/tasker.mdz index a26f0df..af88641 100644 --- a/content/api/spork/tasker.mdz +++ b/content/spork/api/tasker.mdz @@ -1,13 +1,14 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import spork/tasker :export true) -(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/tasker" gen-docs/spork-version)) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "Task Runner (Batch Job Scheduler)" - :nav-title "tasker" +{:title "tasker" :template "docpage.html"} ---- + --- -## Index +A simple task executor library/server. + +## Reference @gen-docs/gen-prefix-current[tasker/] diff --git a/content/spork/api/temple.mdz b/content/spork/api/temple.mdz new file mode 100644 index 0000000..828ed0f --- /dev/null +++ b/content/spork/api/temple.mdz @@ -0,0 +1,59 @@ +(import ../../gen-docs :as gen-docs) +(import spork/temple :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "temple" + :author "Calvin Rose" + :license "MIT" + :template "docpage.html"} +--- + +HTML templates for Janet. + +Simplified version of Mendoza's template system that is cleaner and +easier to use. Templates can be used recursively, and output is +printed via @code`print`, so goes to @code`(dyn :out)`. + +Expands on the mendoza templates with the @code`{-` ... @code`-}` +brackets, which do non-escaped substitution, so temple can be used for +formats besides HTML. Also exposes the @code`escape` function inside +templates for HTML escaping if you want to manually print to template +output. + + +## Example + +### foo.temple + +@codeblock``` +{$ (def n 20) # Run at template compile time $} + + + {{ (string/repeat "<>" n) # HTML escaped }} + + {- (string/repeat "1" n) # Not HTML escaped -} + + +``` + +### main.janet + +@codeblock[janet]``` +(import temple) +(temple/add-loader) + +(import ./foo :as foo) +(foo/render :a "hello") +``` + +There is one more involved example in +/janet-lang/spork/examples/temple/. You can run it with +@code`janet examples/temple/example.janet`. + +## Reference + +@gen-docs/gen-prefix-current[temple/] + diff --git a/content/spork/api/test.mdz b/content/spork/api/test.mdz new file mode 100644 index 0000000..3dbb197 --- /dev/null +++ b/content/spork/api/test.mdz @@ -0,0 +1,162 @@ +(import ../../gen-docs :as gen-docs) +(import spork/test :export true) +(setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) +(setdyn :no-community-examples true) + +{:title "test" + :author "Calvin Rose" + :license "MIT" + :template "docpage.html"} +--- + +This module contains a simple test helper when you do not need a specialized +library. + +## Examples + +### assert + +Modified version of `assert`, with some nice error handling. + +@codeblock[janet]``` +(test/assert false "How is this?") +# => ✘ How is this? +(test/assert true "OK") +# => ✔true +``` + + +### assert-not + +Invert assert. + +@codeblock[janet]``` +(test/assert-not false "OK") +# => ✔true +``` + + +### assert-error + +Test passes if forms throw errors. + +@codeblock[janet]``` +(test/assert-error "To err is natural" (error "Bad")) +# => ✔true +``` + + +### assert-no-error + +Test passes if forms throw errors. + +@codeblock[janet]``` +(test/assert-no-error "To not err is desired" (do "Good")) +# => ✔true +``` + + +### start-suite + +Starts test suite, which counts all and passed tests. + + +### end-suite + +Ends test suite, prints summary and exits if any have failed. + + +### All together + +Example of simple test suite. + +@codeblock[janet]``` +(import spork/test) + +(test/start-suite 0) + +(test/assert true "is always true") +(test/assert-not false "is always false") +(test/assert-error "To err is natural" (error "Bad")) +(test/assert-no-error "To not err is desired" (do "Good")) + +(test/end-suite) + +# => + +Test suite 0 finished in 0.000 soconds +4 of 4 tests passed. +``` + + +### timeit + +Time code execution using os/clock, and print the result. +Returns the value of the timed expression. + +@codeblock[janet]``` +repl> (test/timeit (sum (seq [i :range [1 1000000]] (math/sqrt i)))) +Elapsed time: 0.0718288 seconds +6.66666e+08 +``` + + +### capture-stdout + +Runs the body and captures stdout. Returns tuple with result and captured +stdout in string. + +@codeblock[janet]``` +(capture-stdout + (print "Interesting output") + true) +# => (true "Interesting output") +``` + + +### capture-stderr + +Runs the body and captures stderr. Returns tuple with result and captured +stderr in string. + +@codeblock[janet]``` +(capture-stderr + (print "Interesting output") + true) +# => (true "Interesting output") +``` + + +### supress-stdout + +Runs the form, but supresses its stdout. + +@codeblock[janet]``` +(suppress-stdout (print "Hello world!")) +# => nil +``` + + +### supress-stderr + +Runs the form, but supresses its stderr. + +@codeblock[janet]``` +(suppress-stderr (eprint "Hello world!")) +# => nil +``` + +### assert-docs + +Asserts that all public bindings from the environment have docstring, +when the `path` is required. + +@codeblock[janet]``` +(assert-doc "/spork/test") +✘ suppress-stderr does not have proper doc +``` + +## Reference + +@gen-docs/gen-prefix-current[test/] + diff --git a/content/api/spork/cc.mdz b/content/spork/api/utf8.mdz similarity index 50% rename from content/api/spork/cc.mdz rename to content/spork/api/utf8.mdz index 0b9a0b9..5a1e850 100644 --- a/content/api/spork/cc.mdz +++ b/content/spork/api/utf8.mdz @@ -1,13 +1,14 @@ -(import ../gen-docs :as gen-docs) -(import spork/cc :export true) +(import ../../gen-docs :as gen-docs) +(import spork/utf8 :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "C Compiler Wrapper" - :nav-title "cc" +{:title "utf8" :template "docpage.html"} ---- + --- -## Index +UTF-8 utilities for Janet. -@gen-docs/gen-prefix-current[cc/] +## Reference + +@gen-docs/gen-prefix-current[utf8/] diff --git a/content/api/spork/zip.mdz b/content/spork/api/zip.mdz similarity index 66% rename from content/api/spork/zip.mdz rename to content/spork/api/zip.mdz index 1912b33..6202243 100644 --- a/content/api/spork/zip.mdz +++ b/content/spork/api/zip.mdz @@ -1,13 +1,14 @@ -(import ../gen-docs :as gen-docs) +(import ../../gen-docs :as gen-docs) (import spork/zip :export true) (setdyn :source-linker (partial gen-docs/github-source-linker "janet-lang/spork" gen-docs/spork-version)) (setdyn :no-community-examples true) -{:title "Zip Files" - :nav-title "zip" +{:title "zip" :template "docpage.html"} ---- + --- -## Index +Wrapper around miniz for compression functionality. + +## Reference @gen-docs/gen-prefix-current[zip/] diff --git a/content/spork/index.mdz b/content/spork/index.mdz new file mode 100644 index 0000000..fa82290 --- /dev/null +++ b/content/spork/index.mdz @@ -0,0 +1,42 @@ +{:title "Spork" + :template "docpage.html" + :order 6} +--- + +Spork is a utility library for Janet. It contains a number of small +modules that should be useful for general programming in Janet but do +not "make the cut" for inclusion in the standard library. You can +think of spork as a sort of extended standard library for Janet. + + +## Source code + +@p{@link[https://github.com/janet-lang/spork]} + + +## Install + +@codeblock``` +$ [sudo] jpm install spork +``` + +## Usage + +Every binding in the spork library will be imported if you @code`(import spork)` in either a Janet source file or at a Janet REPL: + +@codeblock``` +Janet 1.35.2-fda0a081 linux/x64/gcc - '(doc)' for help +repl:1:> (import spork) +@{_ @{:value } spork/argparse/argparse @{:private true} spork/base64/decode @{:private true} spork/base64/encode @{:private true} spork/crc/make-variant @{:private true} spork/crc/named-variant @{:private true} spork/cron/check @{:private true} spork/cron/next-timestamp @{:private true} spork/cron/parse-cron @{:private true} ...} +repl:2:> +``` + +However, it's usually more practical to only import the specific module you want using @code`(import spork/[module])`, replacing @code`[module]` as appropriate. For example: + +@codeblock``` +Janet 1.35.2-fda0a081 linux/x64/gcc - '(doc)' for help +repl:1:> (import spork/netrepl) +@{_ @{:value } netrepl/client @{:private true} netrepl/default-host @{:private true} netrepl/default-port @{:private true} netrepl/server @{:private true} netrepl/server-single @{:private true}} +repl:2:> +``` +