Add more docs to standard namespaces

candid82 · Dec 20, 2016 · 713a132 · 713a132
1 parent 546a4cf
commit 713a132
Show file tree

Hide file tree

Showing 11 changed files with 109 additions and 65 deletions.
diff --git a/base64/base64.go b/base64/base64.go
@@ -16,11 +16,10 @@ var base64DecodeString Proc = func(args []Object) Object {
 
 var base64Namespace = GLOBAL_ENV.EnsureNamespace(MakeSymbol("base64"))
 
-func internBase64(name string, proc Proc) {
-	base64Namespace.Intern(MakeSymbol(name)).Value = proc
-}
-
 func init() {
-	base64Namespace.ResetMeta(MakeMeta("Implements base64 encoding as specified by RFC 4648.", "1.0"))
-	internBase64("decode-string", base64DecodeString)
+	base64Namespace.ResetMeta(MakeMeta(nil, "Implements base64 encoding as specified by RFC 4648.", "1.0"))
+	base64Namespace.InternVar("decode-string", base64DecodeString,
+		MakeMeta(
+			NewListFrom(NewVectorFrom(MakeSymbol("s"))),
+			"Returns the bytes represented by the base64 string s.", "1.0"))
 }
diff --git a/core/environment.go b/core/environment.go
@@ -24,7 +24,7 @@ func NewEnv(currentNs Symbol, stdout *os.File, stdin *os.File, stderr *os.File)
 		Namespaces: make(map[*string]*Namespace),
 	}
 	res.CoreNamespace = res.EnsureNamespace(MakeSymbol("core"))
-	res.CoreNamespace.meta = MakeMeta("Core library of Joker.", "1.0")
+	res.CoreNamespace.meta = MakeMeta(nil, "Core library of Joker.", "1.0")
 	res.ns = res.CoreNamespace.Intern(MakeSymbol("*ns*"))
 	res.ns.Value = res.EnsureNamespace(currentNs)
 	res.stdout = res.CoreNamespace.Intern(MakeSymbol("*out*"))
@@ -36,10 +36,10 @@ func NewEnv(currentNs Symbol, stdout *os.File, stdin *os.File, stderr *os.File)
 	res.file = res.CoreNamespace.Intern(MakeSymbol("*file*"))
 	res.args = res.CoreNamespace.Intern(MakeSymbol("*command-line-args*"))
 	args := EmptyVector
-	for _, arg := range os.Args {
+	for _, arg := range os.Args[1:] {
 		args = args.Conjoin(String{S: arg})
 	}
-	if args.Count() > 1 {
+	if args.Count() > 0 {
 		res.args.Value = args
 	} else {
 		res.args.Value = NIL

diff --git a/core/object.go b/core/object.go
@@ -1329,8 +1329,11 @@ func IsSpecialSymbol(obj Object) bool {
 	}
 }
 
-func MakeMeta(docstring string, added string) Map {
+func MakeMeta(arglists Seq, docstring string, added string) Map {
 	res := EmptyArrayMap()
+	if arglists != nil {
+		res.Add(MakeKeyword("arglists"), arglists)
+	}
 	res.Add(MakeKeyword("doc"), String{S: docstring})
 	res.Add(MakeKeyword("added"), String{S: added})
 	return res

diff --git a/core/procs.go b/core/procs.go
@@ -1304,7 +1304,7 @@ func intern(name string, proc Proc) {
 func init() {
 	rand.Seed(time.Now().UnixNano())
 	GLOBAL_ENV.CoreNamespace.InternVar("*assert*", Bool{B: true},
-		MakeMeta("When set to logical false, assert is a noop. Defaults to true.", "1.0"))
+		MakeMeta(nil, "When set to logical false, assert is a noop. Defaults to true.", "1.0"))
 
 	intern("list**", procList)
 	intern("cons*", procCons)

diff --git a/docs/base64.html b/docs/base64.html
@@ -18,9 +18,10 @@ <h2>Index</h2>
       <li>
   <h3 id="decode-string">decode-string</h3>
   <span class="var-type Function">Function</span>
-  <span class="var-added">v</span>
-  <pre class="var-usage"></pre>
-  <p class="var-docstr"></p>
+  <span class="var-added">v1.0</span>
+  <pre class="var-usage"><div><code>(decode-string s)</code></div>
+</pre>
+  <p class="var-docstr">Returns the bytes represented by the base64 string s.</p>
 </li>
 
     </ul>

diff --git a/docs/json.html b/docs/json.html
@@ -18,9 +18,10 @@ <h2>Index</h2>
       <li>
   <h3 id="read-string">read-string</h3>
   <span class="var-type Function">Function</span>
-  <span class="var-added">v</span>
-  <pre class="var-usage"></pre>
-  <p class="var-docstr"></p>
+  <span class="var-added">v1.0</span>
+  <pre class="var-usage"><div><code>(read-string s)</code></div>
+</pre>
+  <p class="var-docstr">Parses the JSON-encoded data and return the result as a Joker value.</p>
 </li>
 
     </ul>

diff --git a/docs/os.html b/docs/os.html
@@ -24,23 +24,26 @@ <h2>Index</h2>
       <li>
   <h3 id="args">args</h3>
   <span class="var-type Function">Function</span>
-  <span class="var-added">v</span>
-  <pre class="var-usage"></pre>
-  <p class="var-docstr"></p>
+  <span class="var-added">v1.0</span>
+  <pre class="var-usage"><div><code>(args)</code></div>
+</pre>
+  <p class="var-docstr">Returns a sequence of the command line arguments, starting with the program name (normally, joker).</p>
 </li>
 <li>
   <h3 id="env">env</h3>
   <span class="var-type Function">Function</span>
-  <span class="var-added">v</span>
-  <pre class="var-usage"></pre>
-  <p class="var-docstr"></p>
+  <span class="var-added">v1.0</span>
+  <pre class="var-usage"><div><code>(env)</code></div>
+</pre>
+  <p class="var-docstr">Returns a map representing the environment.</p>
 </li>
 <li>
   <h3 id="sh">sh</h3>
   <span class="var-type Function">Function</span>
-  <span class="var-added">v</span>
-  <pre class="var-usage"></pre>
-  <p class="var-docstr"></p>
+  <span class="var-added">v1.0</span>
+  <pre class="var-usage"><div><code>(sh name & args)</code></div>
+</pre>
+  <p class="var-docstr">Executes the named program with the given arguments. Returns a map with the following keys:<br>			:success - whether or not the execution was successful,<br>			:out - string capturing stdout of the program,<br>			:err - string capturing stderr of the program.</p>
 </li>
 
     </ul>

diff --git a/docs/string.html b/docs/string.html
@@ -36,51 +36,58 @@ <h2>Index</h2>
       <li>
   <h3 id="ends-with?">ends-with?</h3>
   <span class="var-type Function">Function</span>
-  <span class="var-added">v</span>
-  <pre class="var-usage"></pre>
-  <p class="var-docstr"></p>
+  <span class="var-added">v1.0</span>
+  <pre class="var-usage"><div><code>(ends-with? s substr)</code></div>
+</pre>
+  <p class="var-docstr">True if s ends with substr.</p>
 </li>
 <li>
   <h3 id="join">join</h3>
   <span class="var-type Function">Function</span>
-  <span class="var-added">v</span>
-  <pre class="var-usage"></pre>
-  <p class="var-docstr"></p>
+  <span class="var-added">v1.0</span>
+  <pre class="var-usage"><div><code>(join separator coll)</code></div>
+</pre>
+  <p class="var-docstr">Returns a string of all elements in coll, as returned by (seq coll), separated by a separator.</p>
 </li>
 <li>
   <h3 id="pad-left">pad-left</h3>
   <span class="var-type Function">Function</span>
-  <span class="var-added">v</span>
-  <pre class="var-usage"></pre>
-  <p class="var-docstr"></p>
+  <span class="var-added">v1.0</span>
+  <pre class="var-usage"><div><code>(pad-left s pad n)</code></div>
+</pre>
+  <p class="var-docstr">Returns s padded with pad at the beginning to length n.</p>
 </li>
 <li>
   <h3 id="pad-right">pad-right</h3>
   <span class="var-type Function">Function</span>
-  <span class="var-added">v</span>
-  <pre class="var-usage"></pre>
-  <p class="var-docstr"></p>
+  <span class="var-added">v1.0</span>
+  <pre class="var-usage"><div><code>(pad-right s pad n)</code></div>
+</pre>
+  <p class="var-docstr">Returns s padded with pad at the end to length n.</p>
 </li>
 <li>
   <h3 id="replace">replace</h3>
   <span class="var-type Function">Function</span>
-  <span class="var-added">v</span>
-  <pre class="var-usage"></pre>
-  <p class="var-docstr"></p>
+  <span class="var-added">v1.0</span>
+  <pre class="var-usage"><div><code>(replace s old new)</code></div>
+</pre>
+  <p class="var-docstr">Replaces all instances of string old with string new in string s.</p>
 </li>
 <li>
   <h3 id="split">split</h3>
   <span class="var-type Function">Function</span>
-  <span class="var-added">v</span>
-  <pre class="var-usage"></pre>
-  <p class="var-docstr"></p>
+  <span class="var-added">v1.0</span>
+  <pre class="var-usage"><div><code>(split s re)</code></div>
+</pre>
+  <p class="var-docstr">Splits string on a regular expression. Returns vector of the splits.</p>
 </li>
 <li>
   <h3 id="starts-with?">starts-with?</h3>
   <span class="var-type Function">Function</span>
-  <span class="var-added">v</span>
-  <pre class="var-usage"></pre>
-  <p class="var-docstr"></p>
+  <span class="var-added">v1.0</span>
+  <pre class="var-usage"><div><code>(starts-with? s substr)</code></div>
+</pre>
+  <p class="var-docstr">True if s starts with substr.</p>
 </li>
 
     </ul>

diff --git a/json/json.go b/json/json.go
@@ -44,11 +44,10 @@ var readString Proc = func(args []Object) Object {
 
 var jsonNamespace = GLOBAL_ENV.EnsureNamespace(MakeSymbol("json"))
 
-func intern(name string, proc Proc) {
-	jsonNamespace.Intern(MakeSymbol(name)).Value = proc
-}
-
 func init() {
-	jsonNamespace.ResetMeta(MakeMeta("Implements encoding and decoding of JSON as defined in RFC 4627.", "1.0"))
-	intern("read-string", readString)
+	jsonNamespace.ResetMeta(MakeMeta(nil, "Implements encoding and decoding of JSON as defined in RFC 4627.", "1.0"))
+	jsonNamespace.InternVar("read-string", readString,
+		MakeMeta(
+			NewListFrom(NewVectorFrom(MakeSymbol("s"))),
+			"Parses the JSON-encoded data and return the result as a Joker value.", "1.0"))
 }
diff --git a/os/os.go b/os/os.go
@@ -62,12 +62,22 @@ var sh Proc = func(args []Object) Object {
 var osNamespace = GLOBAL_ENV.EnsureNamespace(MakeSymbol("os"))
 
 func intern(name string, proc Proc) {
-	osNamespace.ResetMeta(MakeMeta("Provides a platform-independent interface to operating system functionality.", "1.0"))
 	osNamespace.Intern(MakeSymbol(name)).Value = proc
 }
 
 func init() {
-	intern("env", env)
-	intern("args", args)
-	intern("sh", sh)
+	osNamespace.ResetMeta(MakeMeta(nil, "Provides a platform-independent interface to operating system functionality.", "1.0"))
+	osNamespace.InternVar("env", env, MakeMeta(NewListFrom(EmptyVector), "Returns a map representing the environment.", "1.0"))
+	osNamespace.InternVar("args", args,
+		MakeMeta(
+			NewListFrom(EmptyVector),
+			"Returns a sequence of the command line arguments, starting with the program name (normally, joker).", "1.0"))
+	osNamespace.InternVar("sh", sh,
+		MakeMeta(
+			NewListFrom(
+				NewVectorFrom(MakeSymbol("name"), MakeSymbol("&"), MakeSymbol("args"))),
+			`Executes the named program with the given arguments. Returns a map with the following keys:
+			:success - whether or not the execution was successful,
+			:out - string capturing stdout of the program,
+			:err - string capturing stderr of the program.`, "1.0"))
 }
diff --git a/string/string.go b/string/string.go
@@ -92,12 +92,33 @@ var replace Proc = func(args []Object) Object {
 }
 
 func init() {
-	stringNamespace.ResetMeta(MakeMeta("Implements simple functions to manipulate strings.", "1.0"))
-	intern("pad-right", padRight)
-	intern("pad-left", padLeft)
-	intern("split", split)
-	intern("join", join)
-	intern("ends-with?", endsWith)
-	intern("starts-with?", startsWith)
-	intern("replace", replace)
+	stringNamespace.ResetMeta(MakeMeta(nil, "Implements simple functions to manipulate strings.", "1.0"))
+	stringNamespace.InternVar("pad-right", padRight,
+		MakeMeta(
+			NewListFrom(NewVectorFrom(MakeSymbol("s"), MakeSymbol("pad"), MakeSymbol("n"))),
+			"Returns s padded with pad at the end to length n.", "1.0"))
+	stringNamespace.InternVar("pad-left", padLeft,
+		MakeMeta(
+			NewListFrom(NewVectorFrom(MakeSymbol("s"), MakeSymbol("pad"), MakeSymbol("n"))),
+			"Returns s padded with pad at the beginning to length n.", "1.0"))
+	stringNamespace.InternVar("split", split,
+		MakeMeta(
+			NewListFrom(NewVectorFrom(MakeSymbol("s"), MakeSymbol("re"))),
+			"Splits string on a regular expression. Returns vector of the splits.", "1.0"))
+	stringNamespace.InternVar("join", join,
+		MakeMeta(
+			NewListFrom(NewVectorFrom(MakeSymbol("separator"), MakeSymbol("coll"))),
+			"Returns a string of all elements in coll, as returned by (seq coll), separated by a separator.", "1.0"))
+	stringNamespace.InternVar("ends-with?", endsWith,
+		MakeMeta(
+			NewListFrom(NewVectorFrom(MakeSymbol("s"), MakeSymbol("substr"))),
+			"True if s ends with substr.", "1.0"))
+	stringNamespace.InternVar("starts-with?", startsWith,
+		MakeMeta(
+			NewListFrom(NewVectorFrom(MakeSymbol("s"), MakeSymbol("substr"))),
+			"True if s starts with substr.", "1.0"))
+	stringNamespace.InternVar("replace", replace,
+		MakeMeta(
+			NewListFrom(NewVectorFrom(MakeSymbol("s"), MakeSymbol("old"), MakeSymbol("new"))),
+			"Replaces all instances of string old with string new in string s.", "1.0"))
 }