chiark / gitweb /
bike-lipo-box: adjustments from #1306: lipo keepers diagonal (avoids cura needing...
[reprap-play.git] / commitid.scad.pl
index 3c409f5..3ea50a0 100755 (executable)
 #!/usr/bin/perl -w
-use strict;
 
-$SIG{__WARN__} = sub { die @_; };
+# commitid.scad.pl - a program for annotating solid models with commit info
+# Copyright (C)2016 Ian Jackson.  See below.  There is NO WARRANTY.
 
-#  xxx much of the comment below is TODO
-#
-# Usage:
+
+# USAGE
+# =====
 #
 #   .../commitid.scad.pl [OPTION...] [STRING...] >commitid.scad.new \
 #     && mv -f commitid.scad.new commitid.scad
 #
+# Run without arguments, commitid.scad.pl will output an openscad file
+# which contains 2D and 3D models of the current git commit count and
+# commit object id (commit hash), useful for identifying printed
+# parts.
+#
+# See below for details.  You probably want these two sections, as a
+# quick starting point:
+#    General form of provided openscad modules
+#    Autoscaling modules
+#
+# We can also generate models of short mainly-numeric strings
+# specified on the command line.
+#
+#
 # Options:
 #
-#   --git    generate git commit indications, as shown below
-#            (this is the default if no strings are requested with -t)
+#   --git    Generate git commit indications, as shown below
+#            (this is the default if no strings are requested with -t).
+#            Ie, produce the `Autoscaling modules' and `Specific layouts'.
+#
+#   --git=objid
+#            Generate git commit indication based on commit object only
+#            (ie avoid counting commits).  Ie, do not generate `Small'
+#            and `Full' layouts (and never select them for `Best').
+#
+#   -i       Do not generate `+' dirty indication if git-untracked files
+#            are present (ie, missing .gitignore entries).  The `*'
+#            dirty tree indication (for modified files) cannot be disabled.
+#
+#   [-t[LAYOUT]] TEXT
+#            Generate a layout LAYOUT containing TEXT.  TEXT can
+#            contain newlines (a final newline usually undesirable, as
+#            it will generate a blank line).  If LAYOUT is not specified,
+#            generates Arg0, Arg1, Arg2, etc., for successive such
+#            TEXTs.  The permissible character set in is TEXT is:
+#                 space 0-9 a-f + *
+#
+#
+# OPENSCAD INTERFACE
+# ==================
+#
+# Dynamic variables for configuration
+# -----------------------------------
+#
+# We honour the following variables to control various scaling factors:
+#
+#                             default value  notes
+#    $Commitid_pixelsz         0.8             \ multiplied together
+#    $Commitid_scale           1.0             /
+#    $Commitid_depth           pixelsz/2       \ multiplied together
+#    $Commitid_depth_scale     1.0             / 
+#    $Commitid_max_best_scale  2.0             limits XY scaling in *Best*
+#
+# FYI the font is nominally 3x5 pixels, with 1-pixel inter-line and
+# inter-character gaps.  (It's not strictly speaking a 3x5 bitmap
+# font, size it contains partial pixels and diagonals.)
+#
+#
+# Non-`module'-specific functions
+# -------------------------------
+#
+# We provide the following functions (which depend on the config
+# variables, but not on anything else) and compute useful values:
+#
+#   function Commitid_pixelsz()   Actual size of each nominal pixel
+#   function Commitid_depth()     Depth to use (the amount characters
+#                                  should be raised or sunken)
 #
-#   --git=object
-#            generate git commit indication based on commit object only
-#            (ie avoid counting commits)
+# General form of provided openscad modules
+# -----------------------------------------
 #
-#   -i       do not generate `+' if git-untracked files are present
+#   module Commitid_MODULE_2D(...)   Collection of polygons forming characters
+#   module Commitid_MODULE(...)      The above, extruded up and down in Z
+#   module Commitid_MODULE_M_2D(...) Mirror writing
+#   module Commitid_MODULE_M(...)    3D mirror writing
+#   function Commitid_MODULE_sz()    A 2-vector giving the X,Y size
 #
-#   [-t[FORM]] TEXT
-#            generate a form FORM containing TEXT
-#            TEXT can contain newlines (final newline usually undesirable)
-#            if FORM not specified, generates Arg0 Arg1 Arg2 in sequence
-#            character set is SPC 0-9 a-f + *
+# Except for *Best* modules, the XY origin is in the bottom left
+# corner without any margin.  Likewise Commitid_MODULE_sz does not
+# include any margin.
 #
-# We generate a physical indication of which commit was used.
+# For 3D versions, the model is 2*depth deep and the XY plane bisects
+# the model.  This means it's convenient to either add or subtract from
+# a workpiece whose face is in the XY plane.
 #
-# We provide for scaling factors with dynamic variables:
-#    $Commitid_pixelsz        if not set, we use 0.8 } multiplied
-#    $Commitid_scale          if not set, we use 1.0 }  together
-#    $Commitid_depth          if not set, we use xy pixel size from above / 2
-#    $Commitid_depth_scale    if not set, we use 1.0 (multiplies depth above)
+# The _M versions are provided to avoid doing inconvenient translation
+# and rotation to get the flipped version in the right place.
 #
-# For each form we have
 #
-#    module Commitid_Form_2D() { ... }
-#    module Commitid_Form() { ... }
-#    function Commitid_Form_sz()     => [ x, y ]
+# Autoscaling modules
+# -------------------
 #
-#  These have their origin in the bottom left corner.  The 3D model
-#  is a positive, has its origin halfway through, and is twice the
-#  depth in height, so it can be added or subtracted.
+# These modules take a specification of the available XY space, and
+# select and generate a suitable specific identification layout:
+# 
+#   module Commitid_BestCount_2D  (max_sz, margin=Commitid_pixelsz())
+#   module Commitid_BestCount     (max_sz, margin=Commitid_pixelsz())
+#   module Commitid_BestCount_M_2D(max_sz, margin=Commitid_pixelsz())
+#   module Commitid_BestCount_M   (max_sz, margin=Commitid_pixelsz())
+#   module Commitid_BestObjid_2D  (max_sz, margin=Commitid_pixelsz())
+#   module Commitid_BestObjid     (max_sz, margin=Commitid_pixelsz())
+#   module Commitid_BestObjid_M_2D(max_sz, margin=Commitid_pixelsz())
+#   module Commitid_BestObjid_M   (max_sz, margin=Commitid_pixelsz())
 #
-# And we provide
+# max_sz should be [x,y].
 #
-#   function Commitid_pixelsz()    // $Commitid_pixelsz * $Commitid_scale
-#   function Commitid_depth()      // see above
+# BestCount includes (as much as it can of) the git commit count,
+# ie the result of
+#     git rev-list --first-parent --count HEAD
+# (and it may include some of the git revision ID too).
 #
-# We can generate these forms:
+# BestObjid includes as much as it can of the git commit object hash,
+# and never includes any of the count.
 #
-#  In each case:
-#    if tree is dirty, * is suffixed or prefixed to count or commitid
-#    if tree has untracked files, + is added
-#    (where it is added depends on the Form; in any case it does not
-#    change the size, but steals space from digits)
+# All of these will autoscale and autorotate the selected model, and
+# will include an internal margin of the specified size (by default,
+# one pixel around each edge).  If no margin is needed, pass margin=0.
 #
-#   Small2 Small3 ... Small10:
-#       git rev-list --first-parent --count HEAD
-#       typically 3-4 characters but we allow for up to 6
-#       padded with zeroes; if too long we reduce mod 10^n
-#       eg if the count is 123456
+# There are no `function Commitid_Best*_sz'.  If they existed they
+# would simply return max_sz.
+#
+#
+# Output format
+# -------------
+#
+# In general the output, although it may be over multiple lines,
+# is always in this order
+#     git commit object id (hash)
+#     dirty indicator
+#     git commit count
+#
+# Not all layouts have all these parts.  The commit object id may
+# sometimes be split over multiple lines, but the count will not be.
+# If both commit id and commit count appear they will be separated
+# by (at least) a newline, or a dirty indicator, or a space.
+#
+# The commit id is truncated to fit, from the right.
+#
+# The commit count is truncated from the _left_, leaving the least
+# significant decimal digits.
+#
+# The dirty indicator can be
+#
+#   *   meaning the working tree contains differences from HEAD
+#
+#   +   meaning the working tree contains untracked files
+#       (ie files you have failed to `git add' and also failed
+#       to add to gitignore).  (But see the -i option.)
+#
+#
+# Specific layouts
+# ----------------
+#
+# If you want to control the exact layout (and make space for it in
+# your design), you can use these:
+#
+#    module Commitid_LAYOUT_2D()
+#    module Commitid_LAYOUT()
+#    module Commitid_LAYOUT_M_2D()
+#    module Commitid_LAYOUT_M()
+#    function Commitid_LAYOUT_sz()
+#
+# Here LAYOUT is one of the following (giving for example, `module
+# Commitid_Full8_2D').  In the examples, we will assume that the tree
+# is dirty, the commit count is 123456, and the commit object id
+# starts abcdeffedbcaabcdef...  In the examples `_' shows where a
+# space would be printed.
+#
+#   Small2 Small3 ... Small10
+#       A single line containing as much of the count will fit, eg:
 #            Small5    3456*
-#            Small8    __123456    (where _ are spaces)
-#
-#   Small2S Small4S ... Small10S:
-#   Small3T Small9T:
-#       same but split into two lines (S) or three lines (T) eg
-#            Small4S  45     Small6T   _3
-#                     6*               45
-#                                      6*
-#
-#   Git2 Git3 ... Git10:
-#   Git4S Git6S ... Git10S:
-#   Git6T Git9T:
-#       git-rev-parse HEAD   (prefix of requested length)
-#       eg if the commitid is abcdef0123...
+#            Small8    _*123456
+#       The objectid is included if more than one character of of it
+#       will fit without makign the output ambiguous:
+#            Small9    ab*123456
+#
+#   Small2S Small4S ... Small10S
+#   Small3T Small9T
+#       Same as Small but split into two lines (S)
+#       or three lines (T).  Eg:
+#            Small4S    *4       Small6T   _*
+#                       56                 34
+#                                          56
+#   Git2 Git3 ... Git10
+#   Git4S Git6S ... Git10S
+#   Git6T Git9T
+#       Just the commit object hash, in one, two (S) or three (T)
+#       lines.  E.g.:
 #            Git5    abcd*
-
+#
 #   Full4 Full6 ... Full20:
-#       git-rev-list --first-parent --count HEAD
-#       git-rev-parse HEAD
-#       (all on two lines)
-#       eg
-#            Full6    abcdef       Full8     abcdef01
-#                     23456*                 _123456*
+#       The commit object hash plus the commit count, on
+#       separate lines, eg:
+#            Full12   abcdef     Full16    abcdeffe
+#                     *23456               _*123456
 #
 #   Full6T Full9T ... Full30T
-#       as Full but commit is split over two lines
-#       for a 3-line message; eg
-#             Full9T    abc
-#                       de*
-#                       456
+#       As Full but the commit object id is split over two lines
+#       producing a 3-line layout, eg:
+#            Full9T    abc       Full21T   abcdeff
+#                      de*                 edbcaa*
+#                      456                 _123456
+#
+# Other LAYOUTs
+# -------------
 #
 #   FontDemo
 #
-#   Arg0, Arg1, ...
-#       Strings passed on command line
+#       A demonstration of the built-in 18-character font
+#
+#   Arg0 Arg1, ...
+#
+#       Strings passed on command line (without -t, or bare -t,
+#       rather than with -tLAYOUT).
+#
+#   LAYOUT
+#
+#       Generated by passing -tLAYOUT on the command line.
+#
+
+
+# COPYRIGHT, LICENCE AND LACK-OF-WARRANTY INFORMATION
+# ===================================================
+#
+# This program is Free Software and a Free Cultural Work.
+#
+#   You can redistribute it and/or modify it under the terms of the
+#   GNU General Public License as published by the Free Software
+#   Foundation, either version 3 of the License, or (at your option)
+#   any later version.
+#
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+# Alternatively, at your option:
+#
+#   This work is licensed under the Creative Commons
+#   Attribution-ShareAlike 4.0 International License.
+#
+#   There is NO WARRANTY.
+
+
+use strict;
+
+$SIG{__WARN__} = sub { die @_; };
 
 sub p { print @_ or die $!; }
 
@@ -129,6 +290,27 @@ sub gentextmodule_demo_start_batch () {
     $gtm_demo_i++;
 }
 
+sub argl_formal (@) { join ', ', @_; }
+sub argl_actual (@) { join ',', map { m/=/ ? $` : $_ } @_; }
+
+sub gen3dmodule ($@) {
+    my ($modb,$size,@argl) = (@_);
+    $size ||= "${modb}_sz()";
+    p "module ${modb}_M_2D(".argl_formal(@argl)."){\n";
+    p "  translate([${size}[0],0])\n";
+    p "    mirror([1,0,0])\n";
+    p "    ${modb}_2D(".argl_actual(@argl).");\n";
+    p "};\n";
+    foreach my $mir ('','_M') {
+       my $mm = "${modb}${mir}";
+       p "module ${mm}(".argl_formal(@argl)."){\n";
+       p " d=Commitid_depth();\n";
+       p " translate([0,0,-d]) linear_extrude(height=d*2)\n";
+       p "  ${mm}_2D(".argl_actual(@argl).");\n";
+       p "}\n";
+    }
+}
+
 sub gentextmodule ($@) {
     my ($form, @lines) = @_;
     my $modb = "Commitid_$form";
@@ -150,10 +332,7 @@ sub gentextmodule ($@) {
     }
     p " }\n";
     p "}\n";
-    p "module ${modb}(){\n";
-    p " d=Commitid_depth();\n";
-    p " translate([0,0,-d]) linear_extrude(height=d*2) ${modb}_2D();\n";
-    p "}\n";
+    gen3dmodule($modb,'');
 
     p sprintf "function %s_sz() = Commitid__scale() * 0.1 * [ %d, %d ];\n",
        $modb, 2 * ($cols * 4 - 1), 2 * (@lines * 6 - 1);
@@ -248,28 +427,47 @@ our $do_git; # contains may chars 'c' (count) and/or 'o' (object)
 our $do_git_untracked = 1;
 our $argcounter;
 
-sub rjustt ($$;$) { # right justify and truncate (ie, pad and truncate at left)
-                    # always includes prefix
-    my ($sz, $whole, $prefix) = @_;
+our @forms;
+our %included; # 0 = not at all; 1 = truncated; 2 = full
+
+sub rjustt ($$$;$) {
+    # right justify and truncate (ie, pad and truncate at left)
+    # always includes prefix
+    # sets $included{$what}
+    my ($sz, $what, $whole, $prefix) = @_;
     $prefix //= '';
     my $lw = length $whole;
     my $spare = $sz - $lw - (length $prefix);
+    $included{$what}= 1 + ($spare > 0);
     return
        ($spare > 0 ? (' ' x $spare) : '').
        $prefix.
        substr($whole, ($spare < 0 ? -$spare : 0));
 }
 
-sub ljustt ($$;$) {
-    my ($sz, $whole, $suffix) = @_;
+sub ljustt ($$$;$) {
+    my ($sz, $what, $whole, $suffix) = @_;
     $suffix //= '';
     $sz -= length $suffix;
+    $included{$what} = 1 + ($sz >= length $whole);
     return sprintf "%-${sz}.${sz}s%s", $whole, $suffix;
 }
 
+sub genform_prep() {
+    $included{$_}=0 foreach qw(Objid Count);
+}
+
 sub genform ($@) {
     my ($form, @lines) = @_;
     gentextmodule($form, @lines);
+    my $f = {
+       Form => $form,
+       Chars => (length join '', @lines),
+       Lines => (scalar @lines),
+       Ambiguous => ($form =~ m/Full/ && !grep { m/\W/ } @lines),
+       Included => { %included },
+    };
+    push @forms, $f;
 }
 
 sub genform_q ($$$) {
@@ -342,35 +540,119 @@ sub do_git () {
     if ($do_git =~ m/o/) {
        $git_object = gitoutput qw(rev-parse HEAD);
     }
+    print STDERR join ' ', map { $_ // '?' }
+       "-- commitid", $git_object, $git_dirty, $git_count, "--\n";
 
     foreach my $sz (2..10) {
        gentextmodule_demo_start_batch();
 
-       genform_plusq("Small$sz", rjustt($sz, $git_count, $git_dirty))
-           if defined $git_count;
+       if (defined($git_count)) {
+           genform_prep();
+           my $smallstr = rjustt($sz, 'Count', $git_count, $git_dirty);
+           my $forgitobj = $sz - length($git_count) - 1;
+           if (defined($git_object) && $forgitobj >= 2) {
+               $smallstr = ljustt($forgitobj, 'Objid', $git_object).
+                   ($git_dirty || ' ').
+                   $git_count;
+           }
+           genform_plusq("Small$sz", $smallstr);
+       }
 
-       genform_plusq("Git$sz", ljustt($sz, $git_object, $git_dirty))
+       genform_prep();
+       genform_plusq("Git$sz", ljustt($sz, 'Objid', $git_object, $git_dirty))
            if defined $git_object;
 
        if (defined $git_count && defined $git_object) {
+           genform_prep();
            genform("Full".($sz*2),
-                   ljustt($sz, $git_object),
-                   rjustt($sz, $git_count, $git_dirty));
+                   ljustt($sz, 'Objid', $git_object),
+                   rjustt($sz, 'Count', $git_count, $git_dirty));
 
+           genform_prep();
            my $e = $sz;
            genform("Full".($e*3)."T",
-                   ljustt($e*2, $git_object, $git_dirty)
+                   ljustt($e*2, 'Objid', $git_object, $git_dirty)
                    =~ m/.{$e}/g,
-                   rjustt($e, $git_count));
+                   rjustt($e, 'Count', $git_count));
+       }
+    }
+}
+
+sub do_some_best ($$) {
+    my ($bestwhat, $formre) = @_;
+    my $modname = "Best$bestwhat";
+    my $fullmodname = "Commitid_${modname}_2D";
+    my @argl = qw(max_sz margin=Commitid_pixelsz());
+    p "module $fullmodname(".argl_formal(@argl).") {\n";
+    my $mbs = '$Commitid_max_best_scale';
+    p " sc_max = $mbs ? $mbs : 2;\n";
+    p " sz = max_sz - 2*[margin,margin];\n";
+    my @do;
+    foreach my $f (
+        sort {
+           $b->{Included}{$bestwhat} <=> $a->{Included}{$bestwhat} or
+           $b->{Chars} <=> $a->{Chars} or
+           $a->{Lines} <=> $b->{Chars}
+        }
+        grep {
+           $_->{Form} =~ m/$formre/ &&
+           !$_->{Ambiguous}
+       }
+        @forms
+    ) {
+       my $form = $f->{Form};
+       p " sz_$form = Commitid_${form}_sz();\n";
+       foreach my $rot (qw(0 1)) {
+           my $id = "${form}_r${rot}";
+           p " sc_$id = min(sc_max";
+           foreach my $xy (qw(0 1)) {
+               p ",sz[$xy]/sz_$form","[",(($xy xor $rot)+0),"]";
+           }
+           p ");\n";
+           push @do, " if (sc_$id >= 1.0";
+           push @do, " && sc_$id >= sc_${form}_r1" if !$rot;
+           push @do, ") {\n";
+           push @do, "  translate([margin,margin]) scale(sc_$id)\n";
+           push @do, "   rotate(90) translate([0,-sz_$form"."[1]])\n" if $rot;
+           push @do, "   Commitid_${form}_2D();\n";
+           push @do, " } else";
        }
     }
-}    
+    push @do, <<END;
+ {
+  echo("$fullmodname could not fit anything in", max_sz);
+ }
+END
+    p $_ foreach @do;
+    p "}\n";
+
+    gen3dmodule "Commitid_$modname", 'max_sz', @argl;
+}
+
+sub do_git_best () {
+    return unless $do_git;
+
+    # Auto-computer for `best fit'
+    #
+    # We have two best fit approaches: with count, and git-object-id-only
+    #
+    # For `with count', we only ever include the git object id if the
+    # result would be unambigous.  That means that at least one space
+    # or punctuation was generated.
+    #
+    # We sort the options by firstly number of characters
+    # (decreasing), and then by number of lines (increasing) and
+    # try each one both ways round.
+
+    do_some_best('Count', 'Small|Full') if $do_git =~ m/c/;
+    do_some_best('Objid', 'Git|Full') if $do_git =~ m/o/;
+}
 
 while (@ARGV) {
     $_ = shift;
     if (m/^--(no)?-git$/) {
        $do_git = $1 ? '' : 'co';
-    } elsif (m/^---git=object$/) {
+    } elsif (m/^---git=objid$/i) {
        $do_git = 'o';
     } elsif (m/^-i$/) {
        $do_git_untracked = 0;
@@ -394,6 +676,7 @@ gentextmodule_demo_start_batch();
 gentextmodule('FontDemo', @demo);
 
 do_git();
+do_git_best();
 
 p "module Commitid_2DDemo(){\n";
 p " st = Commitid__scale() * [ 10, 5 ];\n";
@@ -416,7 +699,7 @@ R 20 22 02
 
 0 1 2 3 4 5 6 7 8 9
 
-/#\  r  /#\ ##\ # # ### / ### /#\ /#\
+/#\  r  /#\ ##\ # # ### /#/ ### /#\ /#\
 # # /#    #   # # # #   #     # # # # #
 # #  #  /#/ ##< \## ##\ ##\  // >#< \##
 # #  #  #     #   #   # # #  #  # #   #