scriptorium 0.6.1 → 0.7.2

data/doc/old-posts/0016-an-in-operator-for-ruby.lt3

@@ -0,0 +1,142 @@
+.mixin liveblog
+. ^ get rid of this later
+
+.post 16
+ 
+.title An 'in' operator for Ruby
+.pubdate 2019-11-13
+.views computing
+.tags 
+ 
+.pin computing
+
+.teaser
+I have had two fairly small changes I wanted to make in Ruby. The first
+was realized years ago. 
+.end
+
+Hashes now preserve insertion order and iterate in a predictable way.
+That's fairly minor, but it did/does have some use cases, and it had no impact
+on performance.
+
+Here's another one. Personally, this is a bigger thing to me.
+
+<b>I've always believed personally that Ruby should have an `in operator.</b>
+
+I've mentioned this in speaking (including lightning talks) and in writing.
+It's not a _giant big deal for me, but it is one of my personal favorite ideas.
+Here are some details.
+
+ *[My proposal]
+
+I propose to let `[ x in y] be syntax sugar for `[y.include? x]
+
+ *[You may ask: Why?]
+
+<ul>
+  <li> `include? is backwards from common usage -- if the _item is our focus, we don't ask whether a group includes an item, but whether an item is in a group. The same is true of a container.</li>
+
+  <li>Ruby isn't English; and more generally, programming languages aren't human  languages. But programming languages are <i>based<i></i></i> on human languages and on  everyday experience. We do sometimes ask questions like "Does this container  or group include this item?" We are asking a question <i>about the group</i>.  <br><br>   `[if barrel.include? rotten\_apple       # Is barrel going bad?]   <br><br></li>
+
+  <li>But we also -- perhaps more often? -- ask questions like "Is this item part of this group?" We are asking a question <i>about the item</i>.  <br><br>    `[if fruit in [:apple, :pear, :peach\]    # Is this fruit something I like?]  <br><br>
+
+  <li> `[include?] is backwards from mathematical usage -- we ask whether a member is in a set ("epsilon"-like notation), not whether a set contains a memeber.
+
+  <li>I ran across someone else a couple of years ago (I wish I could remember who it was!) who bemoaned the absence of this operator. His argument was that he would have a "conversation" with an object, for example, when he tested it repeatedly. Here's a contrived example I just made up.
+
+.code
+    if foo == var1        ||
+       foo =~ var2        ||
+       foo < var3         ||
+       var4.include?(foo) ||  # <== This is the ugly part
+       foo > var5]
+.end
+
+To quote him as well as I remember: "I was having this perfectly nice conversation 
+with ``foo, and then `var4 interrupted it..."
+
+Better:
+
+.code
+    if foo == var1 ||
+       foo =~ var2 ||
+       foo < var3  ||
+       foo in var4 ||
+       foo > var5]
+.end
+
+  <li>I prefer to put the tested entity earlier in the statement:</li>     
+.code
+    if [GA, VA, MS, TX, MD, NC].include? state      # ehhhh
+    if state in [GA, VA, MS, TX, MD, NC]            # better</tt>
+.end
+
+  <li>Also a "variable/constant" issue -- I tend to put the variable data on the 
+      left and the constant on right; this is unlike  people who say `[if 5 == x]. 
+      (After all, `5 is only equal to `x very  rarely; `5 is <i>always</i> equal to 5, 
+      even for very large values of 5.)
+
+  <li>Also a question of focus: Whatever entity you are really dealing with, 
+      name that one first.
+
+  <li>Many languages already have an `in operator -- notably Python, Pascal, 
+      even SQL. It is familiar to users of those languages as well as those 
+      who use mathematical notation.
+
+  <li> `in is already a reserved word in Ruby -- used in the `for loop (syntax 
+      sugar for `[each]). Let's increase the justification for its presence.
+
+  <li>An `in operator would sometimes make parentheses unnecessary:</li>     
+.code
+   if (10..100).include? x   # Need parens
+   if x in 10..100           # Don't need parens -- also prettier code
+.end
+
+  <li>The newer language Elixir (which I'm happy to report occupies a lot of my 
+      time lately) also sports this operator. This is yet another reason to 
+      love that language.
+</ul>
+
+  <b>Frequently Whined Whines</b>
+  <p>
+  <ul>
+  <li><b>I'd prefer a method.</b> I understand this, but I find it to be 
+      needlessly ugly. I like less punctuation, more whitespace. And I 
+      find this inappropriate for something that is conceptually an operator.
+
+.code
+    if x.in mylist    # ugly   
+    if x.== 5         # also ugly   
+    if c1.and c2      # ugly - if it worked    
+    if x == 5         # better   
+    if c1 and c2      # better   
+    if x in mylist    # better
+.end
+
+  <li><b>I'd prefer a method with a</b> <tt>?</tt> <b>on it.</b> I understand 
+      the concept, too, but I find it inappropriate for what is inherently a relational operator.
+
+.code
+     if x.in? my\_set   # very ugly   
+     if x.==? 5         # very ugly - if it worked
+
+     if x in my\_set    # natural
+     if x == 5          # natural
+.end
+
+  <li><b>What about</b> `[for x in list] <b>? Would this evaluate as </b> 
+      `[for true] <b> or </b> `[for false] <b>?</b> Certainly not. It's a matter 
+      of parsing. The `for loop itself is just syntax sugar.
+
+  <li><b>I'll bet you like junctions, too.</b> No, in fact, I dislike junctions greatly. I don't even know Perl. Are junctions still a thing?
+
+  <li><b>If you like SQL's</b> <tt>in</tt> <b>, you must like</b> <tt>not in</tt> <b><b>also.</b></b>  No, I don't condone its use of "not in":
+
+  <tt>if item not in collection  # travesty!</tt>  <tt>if ! (item in collection)  # ok</tt>
+
+  <tt>if x not == y              # horrible Ruby travesty - if it worked</tt>    Yes, I say this even though <tt>! ( item in collection)</tt> requires parentheses.    See the comment about parentheses on ranges.
+
+<li><b>What about precedence?</b> I would place <tt>in</tt> at the same level of precedence as the (other) relational operators <tt>< > <= >=</tt> etc.</ul><b>Conclusion</b>
+<p> 
+People have ignored me on this for at least ten years. They probably still will.
+That, as they say, is life. 

data/doc/old-posts/0017-the-forgotten-mathematician.lt3

@@ -0,0 +1,129 @@
+.post 17
+
+.title The Forgotten Mathematician
+.pubdate 2019-12-25
+.views computing 
+.tags 
+
+.pin computing
+
+.teaser
+We all know his name... but many of us only "sort of" know it.
+.end
+
+.dropcap
+We all remember Boole in our own way, if at all. His work comes up in discrete
+math and in electrical engineering, among other places. But computer science students and 
+programmers in general remember him chiefly for the Boolean operators and the concept of the 
+Boolean data type.
+.end
+
+.set dash=—
+
+I decided to Google for "who was Boole"... this was the result.
+
+.image gooboo.png
+
+
+Notice the top autocomplete. This seems to suggest that "Boolean" was the person's name. I
+decided to make this blog post to set the record straight. 
+
+But that isn't the only reason I'm writing this. I want to speak up for this historical figure
+just a little and correct what I perceive as a minor injustice.
+
+Did anything look unusual in the previous sentences? Perhaps the capitalization of "Boolean"?
+It's often lowercased in the computing community, and there are reasonable historical reasons
+for this.
+
+In the old days, it was often inconvenient or impossible to type or even to render lowercase
+letters. As recently as the 1980s, I have seen terminals and printers that were strictly uppercase.
+Take a look at a textbook or manual from that era, and you will often see the same thing.
+
+On the other hand, people have always known that in English and similar languages, lowercase was
+an essential part of reality. As it became practical to use computers for applications such as
+typesetting and word processing, we started to take mixed case for granted.
+
+Somewhere in this time frame (or a little earlier), UNIX came along. And yes, we did spell it 
+in all caps at the time. This was true of most computer language names and such, many of which
+were some kind of acronym or abbreviation: FORTRAN, COBOL, BASIC. There was no particular reason
+to put PASCAL in all caps... but people often did, out of a strange kind of habit.
+
+But let's get back to UNIX. Have you ever wondered why we type ``ls, ``cp, and `mv rather than
+``list, ``copy, and `[move]? It's not just that old terminals could be slow to echo. One of the
+UNIX creators basically _[hated to type]. (I remember it as Brian Kernighan, but it may have been 
+Thompson or Ritchie.) And I argue this laziness also extended to a reluctance to type capital letters. 
+Can you think of a command flag that is capitalized (such as `[-F]) _except where the lowercase
+(such as `[-f]) was already used by something more fundamental? I can't think of one.
+
+So as we made a transition from all-caps to mixed case, programming languages that were traditionally
+written in upper case were now written in all lower case. In Pascal, we might once have written
+`[FOR I:=1 TO 10], but a little later, we wrote `[for i:=1 to 10] instead.
+
+Do you see where this is going? Where we once wrote ``BOOLEAN, we wrote `boolean instead. And
+because we saw this so often in our programs, we started writing it that way when we wrote _about
+our programs.
+
+Sometimes this is necessary. If you are using a language where identifiers are case-sensitive (like
+most or all modern languages), there may well be an actual data type named ``boolean, and it would
+be an error to capitalize it (even outside our code). 
+
+So typography matters here. For many years we have tended to write code in some kind of monospaced
+typeface, harking back to the days when we had no choice in the matter. So consider these three
+sentences, which might appear in any manual or piece of documentation:
+
+.nlist
+This function takes a `boolean parameter.
+This function takes a boolean parameter.
+This function takes a Boolean parameter.
+.end
+
+It's reasonable to use lowercase in (1), because we're presumably referring to an actual identifier 
+or reserved word in some language. As for (2) $dash I think we see that all the time, but I'm arguing 
+here it's not appropriate. The usage in (3) is more appropriate.
+
+Now, before I am misunderstood and/or flamed $dash here are the things I am _not saying:
+
+.list
+  I'm not saying we should change the compilers or interpreters.
+  I'm not saying that all the books and manuals should be rewritten.
+  I'm not saying you're ignorant or a bad person if you don't capitalize "Boolean."
+  I'm not saying we should call out people who don't capitalize it.
+.end
+
+But for comparison, let's look at some other scientists and mathematicians whose names have been 
+converted to adjectives. So far I have searched for these: Einsteinian, Newtonian, Galilean, 
+Ptolemaic, Copernican, Wronskian, Laplacian, Lagrangian, Riemannian, Euclidean, Keplerian, 
+Gaussian, Hamiltonian, Archimedean, Diophantine, Pythagorean, Darwinian, Lamarckian, Eulerian,
+Cartesian, Napierian, Bayesian, and Brownian.
+
+These terms have this in common: They are _[always capitalized]. (Interestingly, _Abelian seems
+to be an exception in many people's usage.) And yes, you may find places where these names are
+_not given capital letters, but I contend they are very few in number.
+
+Let's range further afield, into the realms of philosophers, religious figures, writers, and 
+artists. I have searched for these: Socratic, Aristotelian, Mosaic, Benedictine, Kafkaesque, 
+Epicurean, Shakespearean, Elizabethan, Edwardian, Spenserian, Petrarchan, Smithsonian, Botticellian, 
+Dickensian, Orwellian, Jungian, Freudian, and Adlerian. I've found very few uncapitalized
+names. The lowercased _kafkaesque is not unheard of, and we may informally call someone an 
+_epicurean (though we refer specifically to the _Epicurean philosophers in uppercase).
+
+It's worth noting that units of measure named after people are not capitalized:
+newton, ampere, coulomb, gauss, fermi, kelvin, henry, hertz, pascal, and watt. I can't find an
+exception to this. Sometimes, though, the person's name is tacked on as _part of the unit or 
+system of measure; we do capitalize the names when we refer to degrees Fahrenheit, degrees 
+Celsius, Richter scale, Mohs scale, and the Dobson unit. 
+
+Of course, in many cases, we just don't convert a name to a different form: Hilbert space, 
+Schwarzschild radius, Feynmann diagram, Bohr model, Fermi principle, Drake equation, Rohrschach
+test, Hall effect, and so on. Why is this so common? I think it's because an adjective form 
+might often be hard to spell or pronounce, and overall we have less of a tendency for "fancy"
+adjectives nowadays. But in any event, we'd never think of lowercasing these names.
+
+And yet Boole is shortchanged so often in our world! Mathematicians talk about Boolean algebra, 
+and even electrical engineers talk of Boolean logic; but programmers talk of _boolean data and
+_boolean operators. 
+
+Come on, guys. Give him his due. By the way, his first name was George.
+
+So I am making a pledge: Where it's possible and practical, I will capitalize _Boolean whenever 
+I write an article, a book, or a piece of documentation. I encourage you to do the same. 

data/doc/old-posts/0018-ruby-puns.lt3

@@ -0,0 +1,31 @@
+.post 18
+
+.title Ruby puns
+.pubdate 2020-01-21
+.views computing computing 
+.tags 
+
+.teaser
+These are pretty bad. You've been warned.
+.end
+
+
+.mono
+    cheese = ""           # String cheese
+    browns = {}           # Hash browns
+    hiphip   = []         # hiphip array
+    case; end             # brief case
+    foods.freeze          # frozen foods
+    love.taint            # tainted love
+    attr_writer :irish    # Irish setter
+    {"corned" => "beef"}  # corned beef hash
+    raise "hell"          # raising hell
+    $village              # global village 
+    
+    usual_suspects = 1.99
+    usual_suspects.ceil      # round up the usual suspects
+    
+    class JesusChrist < God
+      super(*)               # Jesus Christ Superstar
+    end
+.end

data/doc/old-posts/0019-custom-exceptions-via-metaprogramming.lt3

@@ -0,0 +1,116 @@
+.post 19
+
+.mixin code_rouge
+
+.title Custom exceptions via metaprogramming
+.pubdate 2020-02-17
+.views computing computing
+.tags
+
+.teaser
+Suppose you want a large number of custom exceptions. And suppose you're not afraid of metaprogramming.
+.end
+
+A few months back, I found myself wanting to be "more specific" with the exceptions
+I raised in my ongoing RuneBlog project (which is used to create this blog). I
+wanted to raise specific exceptions with custom parameterized messages (without
+repeating myself too much).
+
+Here's an example of the "usual" way to do this:
+
+.ruby 
+class MyException < StandardError
+
+  def initialize(file, dir)
+    msg = "Could not find #{file} under #{dir}"
+    super(msg)
+  end
+
+end
+
+raise MyException.new("stuff.txt", "/home/willard")
+
+# Output:
+# exc.rb:10:in `<main>': Could not find stuff.txt under /home/willard (MyException)
+.end
+
+Now there is nothing particularly wrong with that. But as it happens, I wanted a 
+large number of exceptions with fairly descriptive names. I didn't want to type
+(or even paste) this stuff over and over.
+
+Here comes the "not afraid of metaprogramming" part. This is what I did:
+
+.ruby
+def make_exception(sym, str, target_class = Object)
+  return if target_class.constants.include?(sym)
+  target_class.const_set(sym, StandardError.dup)
+  define_method(sym) do |*args|
+    msg = str.dup
+    args.each.with_index {|arg, i| msg.sub!("%#{i+1}", arg) }
+    target_class.class_eval(sym.to_s).new(msg)
+  end
+end
+.end
+
+Now, what does this do? The method takes two parameters (or three if you count the
+target class which defaults to `[Object]). You specify a symbol (for the
+name of the exception) and a string (for the exception message). It then does
+two things: It creates an exception class (named after the symbol); and it creates
+a method of the same name.
+
+Here are examples of calling `[make_exception]:
+
+.ruby
+make_exception(:NotImplemented, "Feature not yet implemented")
+make_exception(:CantOpen,       "Can't open '%1'")
+make_exception(:InternalError,  "Internal error: Method %1 got arg '%2'")
+.end
+
+And here are examples of raising these exceptions:
+
+.ruby
+raise NotImplemented
+raise CantOpen(somefile)
+raise InternalError(__method__, arg)
+.end
+
+You might ask: Why define a method returning an exception object? The answer
+is that I don't want to write these this way:
+
+.ruby
+raise NotImplemented.new("Feature not yet implemented")
+raise CantOpen.new("Can't open '#{somefile}'")
+raise InternalError.new("Internal error: Method #{__method__} got arg '#{arg}'")
+.end
+
+I perceive four advantages doing it the first way: I don't have to specify the 
+message string each time; I still get to have a descriptive, unique class name
+without the message making it seem redundantly; I don't have to interpolate
+values into the message string explicitly; and I don't have to say `[.new] 
+every time.
+
+Some of you may have two questions: Can you (or should you) really have a 
+capitalized method name? Can a method have the same name as a class without
+confusing the interpreter?
+
+I'll answer both those questions with an example from the Ruby core: There
+is an `Integer class and an `Integer method (naturally related to each other).
+Ruby distinguishes between these by context. It's not impossible, and I argue
+it's not a bad practice.
+
+As for the parameters, it's intuitive how they work. A `% sign signals a 
+numbered replaceable piece of text, and these are replaced with the parameters
+specified when the method is called. 
+
+That part of the code is not really robust, by the way. As it is written now,
+you could easily confuse it-- make it misbehave or crash. But you get the idea.
+
+So far, I have defined 23 custom exceptions in this project. Each definition
+occupies a single line. If I want to change the behavior of all of them in
+some way, I will go and change the `make_exception method (which itself is
+only 9 lines).
+ 
+Like it, hate it? Comments welcome.
+
+
+

data/doc/old-posts/0021-trying-ror-yet-again.lt3

@@ -0,0 +1,35 @@
+.post 21
+
+.title Trying ROR yet again
+.pubdate 2020-06-15
+.views computing 
+.tags 
+
+.teaser
+Those who know me know I'm not a Rails guy.
+.end
+
+I don't hate Rails, honestly. It's more that I hate web development
+in general.
+
+But here I am, trying once again to master the rudiments. Not because I
+want jobs in that area, but because I want certain small projects built;
+and I can't spend $100 an hour (or is it more?) to have someone else
+do them.
+
+To that end, last night I dived into _[Agile Web Development with Rails 6].
+I covered about 156 pages and highighted passages in iBooks.
+
+Admittedly, I skimmed over the "Ruby review" section pretty quickly, as I'm
+supposed to know that stuff. But I still ran across something that made me
+do a doubletake-- it was this line:
+
+`[  class​ CreateProducts < ActiveRecord::Migration\[6.0\]]
+
+The "versioned class" thing was new to me. I haven't looked it up yet, but
+I assume `Migration is a hash of classes with version numbers as keys (faked
+by `Float values). This is kind of an interesting concept, and it made my
+mind go off in twelve different directions (as it often does at 3:15 in the
+morning).
+
+

data/doc/old-posts/0023-doctor-sleep.lt3

@@ -0,0 +1,43 @@
+.post 23
+
+.title Doctor Sleep
+.pubdate 2020-11-07
+.views chiller
+.tags 
+
+.teaser
+If you didn't know, this is the sequel to _[The Shining].
+
+.end
+
+I have to say: It was well done. It's not a Kubrick movie (and there will
+never be another one), but in its own way, it's faithful enough to the
+original.
+
+What do you get with a Stephen King story? Well, let's be honest. He is a
+little too good for the stuff he writes. He himself said, "I am the literary
+equivalent of a burger and fries." And he isn't wrong.
+
+But on the other hand, his characters are wonderfully three-dimensional.
+(To be honest, I'm quoting someone who taught a writing seminar I was in
+years ago. But it's spot on.) He is a master of characterization and dialogue,
+of plotting and pacing, and his use of language sometimes rises to the realm
+of the sublime.
+
+Of course, even a well-written book doesn't always mean a good movie. I have
+seen some movies apparently based on his works that made me think: As an
+author, he must be crying and hiding his face... all the way to the bank.
+
+And though I have seen more King movies than I have read King novels, I
+thought I could see his work shining through here. (Pun totally not intended.)
+Add to that a few wonderful and innovative bits of CG, some interesting
+camera angles, and yes, some really decent acting here and there. What you
+then get is not exactly a masterpiece, but something well worth watching.
+
+There are arguably some downsides here. Some of the effects might be a little
+cheesy, some of the tropes a little timeworn, some of the acting a little off.
+But so what? It's better than 90% of the stuff I've streamed lately.
+
+I don't like "stars" for reviews. I'm trying to figure out what other kind of
+little icon or widget or thingy I can use. But until then: <i>Doctor Sleep</i>
+gets five stars.

data/doc/old-posts/0024-just-a-test.lt3

@@ -0,0 +1,12 @@
+.post 24
+
+.title just a test
+.pubdate 2024-01-30
+.views chiller chiller 
+.tags 
+
+.teaser
+  If you can read this...
+.end
+
+ ...your IQ might be normal.

data/doc/old-posts/0025-trying-another-post.lt3

@@ -0,0 +1,12 @@
+.post 25
+
+.title Trying another post...
+.pubdate 2024-01-30
+.views computing computing 
+.tags 
+
+.teaser
+  Here we go.
+.end
+
+...again?

data/doc/old-repo

@@ -0,0 +1 @@
+/Users/Hal/.blogs/

data/doc/reddit_integration.md

@@ -142,8 +142,8 @@ Convenience method to check Reddit configuration.
 
 The integration includes comprehensive error handling:
 
-- **Missing credentials**: Raises `FileNotFound` exception
-- **Missing Python script**: Raises `FileNotFound` exception
+- **Missing credentials**: Raises `FileNotFoundError` exception
+- **Missing Python script**: Raises `FileNotFoundError` exception
 - **Invalid JSON**: Returns `nil` for config, logs error
 - **API failures**: Returns `false`, logs error details
 - **Temporary file cleanup**: Automatic cleanup in all cases

data/doc/user.lt3

@@ -33,6 +33,3 @@ The UI(s)
 
 Livetext in more detail
 
-
-- 
--