From 6f06e388cf817e199b07d202093c3c7e9d376847 Mon Sep 17 00:00:00 2001 From: Adrian Mariano Date: Thu, 7 Apr 2022 17:28:41 -0400 Subject: [PATCH] usage messages fixes and some arg tweaks --- coords.scad | 10 ++++---- lists.scad | 53 +++++++++++++++++++++++------------------ strings.scad | 6 +++-- structs.scad | 10 ++++---- tests/test_structs.scad | 4 ++-- version.scad | 42 +++++++++++++++++++------------- 6 files changed, 71 insertions(+), 54 deletions(-) diff --git a/coords.scad b/coords.scad index 9aaeece..393af7b 100644 --- a/coords.scad +++ b/coords.scad @@ -20,7 +20,7 @@ // Returns a 2D vector/point from a 2D or 3D vector. If given a 3D point, removes the Z coordinate. // Arguments: // p = The coordinates to force into a 2D vector/point. -// fill = Value to fill missing values in vector with. +// fill = Value to fill missing values in vector with. Default: 0 function point2d(p, fill=0) = assert(is_list(p)) [for (i=[0:1]) (p[i]==undef)? fill : p[i]]; @@ -51,7 +51,7 @@ function path2d(points) = // Returns a 3D vector/point from a 2D or 3D vector. // Arguments: // p = The coordinates to force into a 3D vector/point. -// fill = Value to fill missing values in vector with. +// fill = Value to fill missing values in vector with. Default: 0 function point3d(p, fill=0) = assert(is_list(p)) [for (i=[0:2]) (p[i]==undef)? fill : p[i]]; @@ -67,7 +67,7 @@ function point3d(p, fill=0) = // by removing extra coordinates or adding the z coordinate. // Arguments: // points = A list of 2D, 3D or higher dimensional points/vectors. -// fill = Value to fill missing values in vectors with (in the 2D case) +// fill = Value to fill missing values in vectors with (in the 2D case). Default: 0 function path3d(points, fill=0) = assert(is_num(fill)) assert(is_path(points, dim=undef, fast=true), "Input to path3d is not a path") @@ -90,7 +90,7 @@ function path3d(points, fill=0) = // Returns a 4D vector/point from a 2D or 3D vector. // Arguments: // p = The coordinates to force into a 4D vector/point. -// fill = Value to fill missing values in vector with. +// fill = Value to fill missing values in vector with. Default: 0 function point4d(p, fill=0) = assert(is_list(p)) [for (i=[0:3]) (p[i]==undef)? fill : p[i]]; @@ -104,7 +104,7 @@ function point4d(p, fill=0) = assert(is_list(p)) // Returns a list of 4D vectors/points from a list of 2D or 3D vectors/points. // Arguments: // points = A list of 2D or 3D points/vectors. -// fill = Value to fill missing values in vectors with. +// fill = Value to fill missing values in vectors with. Default: 0 function path4d(points, fill=0) = assert(is_num(fill) || is_vector(fill)) assert(is_path(points, dim=undef, fast=true), "Input to path4d is not a path") diff --git a/lists.scad b/lists.scad index 3069fbe..1d220ae 100644 --- a/lists.scad +++ b/lists.scad @@ -19,7 +19,7 @@ // Function: is_homogeneous() // Alias: is_homogenous() // Usage: -// bool = is_homogeneous(list, depth); +// bool = is_homogeneous(list, [depth]); // Topics: List Handling, Type Checking // See Also: is_vector(), is_matrix() // Description: @@ -27,7 +27,7 @@ // Booleans and numbers are not distinguinshed as of distinct types. // Arguments: // l = the list to check -// depth = the lowest level the check is done +// depth = the lowest level the check is done. Default: 10 // Example: // a = is_homogeneous([[1,["a"]], [2,["b"]]]); // Returns true // b = is_homogeneous([[1,["a"]], [2,[true]]]); // Returns false @@ -233,8 +233,8 @@ function select(list, start, end) = // An index of -1 refers to the last list item. // Arguments: // list = The list to get the slice of. -// s = The index of the first item to return. -// e = The index of the last item to return. +// start = The index of the first item to return. Default: 0 +// end = The index of the last item to return. Default: -1 (last item) // See Also: select(), column(), last() // Example: // a = slice([3,4,5,6,7,8,9], 3, 5); // Returns [6,7,8] @@ -243,17 +243,17 @@ function select(list, start, end) = // d = slice([3,4,5,6,7,8,9], 5); // Returns [8,9] // e = slice([3,4,5,6,7,8,9], 2, -2); // Returns [5,6,7,8] // f = slice([3,4,5,6,7,8,9], 4, 3; // Returns [] -function slice(list,s=0,e=-1) = +function slice(list,start=0,end=-1) = assert(is_list(list)) - assert(is_int(s)) - assert(is_int(e)) + assert(is_int(start)) + assert(is_int(eend)) !list? [] : let( l = len(list), - s = constrain(s + (s<0? l : 0), 0, l-1), - e = constrain(e + (e<0? l : 0), 0, l-1) + start = constrain(start + (start<0? l : 0), 0, l-1), + end = constrain(end + (end<0? l : 0), 0, l-1) ) - [if (e>=s) for (i=[s:1:e]) list[i]]; + [if (end>=start) for (i=[start:1:end]) list[i]]; // Function: last() @@ -279,12 +279,13 @@ function last(list) = // See Also: select(), slice(), list_tail(), last() // Description: // Returns the head of the given list, from the first item up until the `to` index, inclusive. +// By default returns all but the last element of the list. // If the `to` index is negative, then the length of the list is added to it, such that // `-1` is the last list item. `-2` is the second from last. `-3` is third from last, etc. // If the list is shorter than the given index, then the full list is returned. // Arguments: // list = The list to get the head of. -// to = The last index to include. If negative, adds the list length to it. ie: -1 is the last list item. +// to = The last index to include. If negative, adds the list length to it. ie: -1 is the last list item. Default: -2 // Example: // hlist1 = list_head(["foo", "bar", "baz"]); // Returns: ["foo", "bar"] // hlist2 = list_head(["foo", "bar", "baz"], -3); // Returns: ["foo"] @@ -306,12 +307,13 @@ function list_head(list, to=-2) = // See Also: select(), slice(), list_tail(), last() // Description: // Returns the tail of the given list, from the `from` index up until the end of the list, inclusive. +// By default returns all but the first item. // If the `from` index is negative, then the length of the list is added to it, such that // `-1` is the last list item. `-2` is the second from last. `-3` is third from last, etc. // If you want it to return the last three items of the list, use `from=-3`. // Arguments: // list = The list to get the tail of. -// from = The first index to include. If negative, adds the list length to it. ie: -1 is the last list item. +// from = The first index to include. If negative, adds the list length to it. ie: -1 is the last list item. Default: 1. // Example: // tlist1 = list_tail(["foo", "bar", "baz"]); // Returns: ["bar", "baz"] // tlist2 = list_tail(["foo", "bar", "baz"], -1); // Returns: ["baz"] @@ -364,7 +366,7 @@ function bselect(list,index) = // multi-dimensional array, filled with `val`. // Arguments: // val = The value to repeat to make the list or array. -// n = The number of copies to make of `val`. +// n = The number of copies to make of `val`. Can be a list to make an array of copies. // Example: // a = repeat(1, 4); // Returns [1,1,1,1] // b = repeat(8, [2,3]); // Returns [[8,8,8], [8,8,8]] @@ -391,7 +393,7 @@ function repeat(val, n, i=0) = // Arguments: // indexset = A list of boolean values. // valuelist = The list of values to set into the returned list. -// dflt = Default value to store when the indexset item is false. +// dflt = Default value to store when the indexset item is false. Default: 0 // Example: // a = list_bset([false,true,false,true,false], [3,4]); // Returns: [0,3,0,4,0] // b = list_bset([false,true,false,true,false], [3,4], dflt=1); // Returns: [1,3,1,4,1] @@ -461,13 +463,13 @@ function force_list(value, n=1, fill) = // Description: // Reverses a list or string. // Arguments: -// x = The list or string to reverse. +// list = The list or string to reverse. // Example: // reverse([3,4,5,6]); // Returns [6,5,4,3] -function reverse(x) = - assert(is_list(x)||is_string(x), str("Input to reverse must be a list or string. Got: ",x)) - let (elems = [ for (i = [len(x)-1 : -1 : 0]) x[i] ]) - is_string(x)? str_join(elems) : elems; +function reverse(list) = + assert(is_list(list)||is_string(list), str("Input to reverse must be a list or string. Got: ",list)) + let (elems = [ for (i = [len(list)-1 : -1 : 0]) list[i] ]) + is_string(list)? str_join(elems) : elems; // Function: list_rotate() @@ -652,7 +654,12 @@ function list_set(list=[],indices,values,dflt=0,minlen=0) = // Topics: List Handling // See Also: list_set(), list_remove(), list_remove_values() // Description: -// Insert `values` into `list` before position `indices`. +// Insert `values` into `list` before position `indices`. The indices for insertion +// are based on the original list, before any insertions have occurred. +// Arguments: +// list = list to insert items into +// indices = index or list of indices where values are inserted +// values = value or list of values to insert // Example: // a = list_insert([3,6,9,12],1,5); // Returns [3,5,6,9,12] // b = list_insert([3,6,9,12],[1,3],[5,11]); // Returns [3,5,6,9,11,12] @@ -729,8 +736,7 @@ function list_remove(list, ind) = // Function: list_remove_values() // Usage: -// list = list_remove_values(list, values); -// list = list_remove_values(list, values, all=true); +// list = list_remove_values(list, values, [all]); // Topics: List Handling // See Also: list_set(), list_insert(), list_remove() // Description: @@ -806,6 +812,7 @@ function list_remove_values(list,values=[],all=false) = // Returns the range of indexes for the given list. // Arguments: // list = The list to returns the index range of. +// --- // s = The starting index. Default: 0 // e = The delta from the end of the list. Default: -1 (end of list) // step = The step size to stride through the list. Default: 1 @@ -906,7 +913,7 @@ function triplet(list, wrap=false) = // For the list `[1,2,3,4]`, with `n=3`, this will return `[[1,2,3], [1,2,4], [1,3,4], [2,3,4]]`. // Arguments: // l = The list to provide permutations for. -// n = The number of items in each permutation. Default: 2 +// n = The number of items in each combination. Default: 2 // Example: // pairs = combinations([3,4,5,6]); // Returns: [[3,4],[3,5],[3,6],[4,5],[4,6],[5,6]] // triplets = combinations([3,4,5,6],n=3); // Returns: [[3,4,5],[3,4,6],[3,5,6],[4,5,6]] diff --git a/strings.scad b/strings.scad index 06cd012..b323364 100644 --- a/strings.scad +++ b/strings.scad @@ -56,7 +56,7 @@ function suffix(str,len) = // Function: str_find() // Usage: -// str_find(str,pattern,[last],[all],[start]) +// str_find(str,pattern,[last=],[all=],[start=]) // Description: // Searches input string `str` for the string `pattern` and returns the index or indices of the matches in `str`. // By default `str_find()` returns the index of the first match in `str`. If `last` is true then it returns the index of the last match. @@ -67,6 +67,7 @@ function suffix(str,len) = // Arguments: // str = String to search. // pattern = string pattern to search for +// --- // last = set to true to return the last match. Default: false // all = set to true to return all matches as a list. Overrides last. Default: false // start = index where the search starts @@ -402,7 +403,7 @@ function parse_float(str) = // Function: parse_frac() // Usage: -// parse_frac(str,[mixed],[improper],[signed]) +// parse_frac(str,[mixed=],[improper=],[signed=]) // Description: // Converts a string fraction to a floating point number. A string fraction has the form `[-][# ][#/#]` where each `#` is one or more of the // digits 0-9, and there is an optional sign character at the beginning. @@ -414,6 +415,7 @@ function parse_float(str) = // The empty string evaluates to zero. Any invalid string evaluates to NaN. // Arguments: // str = String to convert. +// --- // mixed = set to true to accept mixed fractions, false to reject them. Default: true // improper = set to true to accept improper fractions, false to reject them. Default: true // signed = set to true to accept a leading sign character, false to reject. Default: true diff --git a/structs.scad b/structs.scad index 1b39164..72b2f96 100644 --- a/structs.scad +++ b/structs.scad @@ -94,22 +94,22 @@ function struct_val(struct, key, default=undef) = function struct_keys(struct) = column(struct,0); -// Function&Module: struct_echo() +// Function&Module: echo_struct() // Usage: -// struct_echo(struct, [name]) +// echo_struct(struct, [name]) // Description: // Displays a list of structure keys and values, one pair per line, for easier reading. // Arguments: // struct = input structure // name = optional structure name to list at the top of the output. Default: "" -function struct_echo(struct,name="") = +function echo_struct(struct,name="") = let( keylist = [for(entry=struct) str(" ",entry[0],": ",entry[1],"\n")]) echo(str("\nStructure ",name,"\n",str_join(keylist))) undef; -module struct_echo(struct,name="") { +module echo_struct(struct,name="") { no_children($children); - dummy = struct_echo(struct,name); + dummy = echo_struct(struct,name); } diff --git a/tests/test_structs.scad b/tests/test_structs.scad index 85d87b4..ac0ed98 100644 --- a/tests/test_structs.scad +++ b/tests/test_structs.scad @@ -60,10 +60,10 @@ module test_struct_keys() { test_struct_keys(); -module test_struct_echo() { +module test_echo_struct() { // Can't yet test echo output } -test_struct_echo(); +test_echo_struct(); module test_is_struct() { diff --git a/version.scad b/version.scad index 811cd60..f386b3d 100644 --- a/version.scad +++ b/version.scad @@ -52,18 +52,20 @@ function bosl_version_str() = version_to_str(BOSL_VERSION); // Module: bosl_required() // Usage: -// bosl_required(x); +// bosl_required(version); // Topics: Versioning // Description: // Given a version as a list, number, or string, asserts that the currently installed BOSL library is at least the given version. // See Also: version_to_num(), version_to_str(), version_to_list(), version_cmp() -module bosl_required(target) { +// Arguments: +// version = version required +module bosl_required(version) { no_children($children); assert( - version_cmp(bosl_version(), target) >= 0, + version_cmp(bosl_version(), version) >= 0, str( "BOSL ", bosl_version_str(), " is installed, but BOSL ", - version_to_str(target), " or better is required." + version_to_str(version), " or better is required." ) ); } @@ -89,50 +91,56 @@ function _version_split_str(x, _i=0, _out=[], _num=0) = // Description: // Given a version string, number, or list, returns the list of version integers [MAJOR,MINOR,REVISION]. // See Also: version_to_num(), version_to_str(), version_cmp(), bosl_required() +// Arguments: +// x = version to convert // Example: // v1 = version_to_list("2.1.43"); // Returns: [2,1,43] // v2 = version_to_list(2.120234); // Returns: [2,12,234] // v3 = version_to_list([2,3,4]); // Returns: [2,3,4] // v4 = version_to_list([2,3,4,5]); // Returns: [2,3,4] -function version_to_list(x) = - is_list(x)? [default(x[0],0), default(x[1],0), default(x[2],0)] : - is_string(x)? _version_split_str(x) : - is_num(x)? [floor(x), floor(x*100%100), floor(x*1000000%10000+0.5)] : - assert(is_num(x) || is_vector(x) || is_string(x)) 0; +function version_to_list(version) = + is_list(version)? [default(version[0],0), default(version[1],0), default(version[2],0)] : + is_string(version)? _version_split_str(version) : + is_num(version)? [floor(version), floor(version*100%100), floor(version*1000000%10000+0.5)] : + assert(is_num(version) || is_vector(version) || is_string(version)) 0; // Function: version_to_str() // Usage: -// str = version_to_str(x); +// str = version_to_str(version); // Topics: Versioning // Description: // Takes a version string, number, or list, and returns the properly formatter version string for it. // See Also: version_to_num(), version_to_list(), version_cmp(), bosl_required() +// Arguments: +// version = version to convert // Example: // v1 = version_to_str([2,1,43]); // Returns: "2.1.43" // v2 = version_to_str(2.010043); // Returns: "2.1.43" // v3 = version_to_str(2.340789); // Returns: "2.34.789" // v4 = version_to_str("2.3.89"); // Returns: "2.3.89" -function version_to_str(x) = - let(x = version_to_list(x)) - str(x[0],".",x[1],".",x[2]); +function version_to_str(version) = + let(version = version_to_list(version)) + str(version[0],".",version[1],".",version[2]); // Function: version_to_num() // Usage: -// str = version_to_num(x); +// str = version_to_num(version); // Topics: Versioning // Description: // Takes a version string, number, or list, and returns the properly formatter version number for it. // See Also: version_cmp(), version_to_str(), version_to_list(), bosl_required() +// Arguments: +// version = version to convert // Example: // v1 = version_to_num([2,1,43]); // Returns: 2.010043 // v2 = version_to_num([2,34,567]); // Returns: 2.340567 // v3 = version_to_num(2.120567); // Returns: 2.120567 // v4 = version_to_num("2.6.79"); // Returns: 2.060079 -function version_to_num(x) = - let(x = version_to_list(x)) - (x[0]*1000000 + x[1]*10000 + x[2])/1000000; +function version_to_num(version) = + let(version = version_to_list(version)) + (version[0]*1000000 + version[1]*10000 + version[2])/1000000; // Function: version_cmp()