#12 - Add version assertion utility module and documentation

README.md

@@ -1,4 +1,4 @@
-# laserscad
+# laserscad 0.3.0
 
 A library for efficient lasercutting with OpenSCAD.
 
@@ -8,7 +8,7 @@ A library for efficient lasercutting with OpenSCAD.
 * Laser whichever shape you want
 * Model in 3D, then run one command to generate a 2D lasercutting template with all parts
 * Save time, because 2D parts are arranged automatically
-* *New in v0.2:* Add engravings to identify parts (or to make things look fancy)
+* *New in 0.2.0:* Add engravings to identify parts (or to make things look fancy)
 
 ## Installation
 
@@ -160,6 +160,19 @@ See ``docs/examples/slicing.scad``.
 ![lslice demonstration](docs/slicing.jpg)
 [Low Poly Stanford Bunny by johnny6](https://www.thingiverse.com/thing:151081) is licensed under the [Creative Commons - Attribution - Non-Commercial license](https://creativecommons.org/licenses/by-nc/3.0/).
 
+### lassert_version
+laserscad uses [semantic versioning](https://semver.org/). With `lassert_version`, one can specify the laserscad version required by a model. This is a bonus feature. It is not necessary to use `lassert_version`, but it can help to keep one's projects organized.
+
+``lassert_version(major=..., minor=...);``
+
+#### Parameters
+* *major*: the exact major version required
+* *minor*: minimum required minor version or `-1` to accept any minor version
+
+#### Examples
+* `major=0, minor=3` would accept laserscad 0.3.0, 0.3.1, 0.4.0, etc. but not 0.2.0 or 1.0.0
+* `major=1, minor=-1` would accept any laserscad 1.x.x (hence 1.0.0, 1.1.0, 1.1.1, etc.) but none of 0.x.x (0.3.0, 0.3.1, etc.)
+
 ### Other laserscad Parameters
 Advanced features of laserscad can be enabled by specifying these parameters anywhere in the global scope of a scad file.
 

dist/laserscad.scad

@@ -13,6 +13,7 @@
 // You should have received a copy of the Lesser GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+
 // 0: dev, 1: pack, 2: preview, 3: engrave, 4: cut
 _laserscad_mode = 0;
 
@@ -22,6 +23,24 @@ _lengrave_color = "MediumSpringGreen";
 _bounding_box_color = "Magenta";
 _bounding_box_alpha = 0.6;
 
+
+// ############### VERSION CHECK UTILITIES ################
+
+_laserscad_version_major = 0;
+_laserscad_version_minor = 3;
+_laserscad_version_patch = 0;
+
+// complains if major version mismatches or if minor version isn't high enough - minor version will be ignored if argument is negative
+module lassert_version(major=0, minor=-1) {
+    major_match = major == _laserscad_version_major;
+    minor_match = minor < 0 || minor <= _laserscad_version_minor;
+
+    if (!major_match || !minor_match) {
+        echo(str("WARNING: This is laserscad ", _laserscad_version_major, ".", _laserscad_version_minor, ".", _laserscad_version_patch, " but the model requires version ", major, ".", (minor < 0? "x" : minor), ".x"));
+    }
+}
+
+
 // ############### TRANSFORMATIONS ################
 
 module ltranslate(vec) {