hpr-knowledge-base/hpr_transcripts/hpr2864.txt

Episode: 2864
Title: HPR2864: One weird trick to add a --help option to your awk scripts
Source: https://hub.hackerpublicradio.org/ccdn.php?filename=/eps/hpr2864/hpr2864.mp3
Transcribed: 2025-10-24 12:27:25

---

This is HBR episode 2008-164 entitled One Weird Trick to Other, Help Option to Your Lock
Crypts.
And in part of the series, Learning Ork, it is hosted by Klaatu, and in about 20 minutes
long, and Karima Clean Flag.
The summary is Klaatu Demonstrates to Ways to Other, Help Message to Your Lock Crypts.
This episode of HBR is brought to you by An Honest Host.com.
With 15% discount on all shared hosting with the offer code HBR15, that's HBR15.
Better web hosting that's Honest and Fair at An Honest Host.com.
You're listening to Ag Republic Radio.
My name is Klaatu, not Paul.
That means something to, according to the front page, 38,000 people.
And those people know what I'm talking about.
In this episode, I'm going to talk about Locke.
Of course, Dave Morris and Be Easy just wrapped up their Auk series officially, and I don't
want to let it die because it was from Dave Morris and Be Easy that I learned Auk.
And since I'd been trying to learn Auk for about 10 years, maybe not trying consistently
for 10 years, but it was definitely on the, it was on my to-do list.
And I finally grasped it because of their series.
I figured I'd add a little, little content to that, little unofficial content.
Recently, I've been writing a lot of scripts in Auk, and some of the scripts have sort
of been just little utilities that I would, I would call from, from shell scripts, or they
would just be little utilities that I would quickly pipe something through and then never
use again, a little bit of a variety there.
So this time, I was writing a script and I thought to myself that it really could be a self-standing
script.
I felt like it was something that I was going to, that I'd been using, I would do this
one process.
It was, it's a script, I mean, it doesn't really actually matter for the, for this tip,
but it was a script that, that increments pages in the bookmarks file of a PDF.
And I had to do that a lot at work at the time.
I was doing a lot of PDF, or a lot of post-processing on PDFs.
And so I needed something to increment pages after I'd inserted pages into a PDF.
So in other words, you have a 10-page PDF, you insert two at page five, after page five.
So now you need all the bookmarks, after page five, to be incremented by two pages because
there's this new offset that the PDF is unaware of.
So that, that was the point of the, the ox script.
I'd been doing that sort of manually with a series of ox commands that I'd kind of remembered
or stashed away as little, you know, a hint file for myself.
And I finally realized that this was something that I was doing a lot and I just needed a dedicated
script for it.
That part was easy and has nothing to do, that, that's not the tip.
That part was just normal sort of finding a pattern, taking the number that appeared
after the pattern, doing some math upon it, and then continuing along the, along the
files.
That was, that was easy.
But what I, what I was struggling with was its documentation because I realized that
if, if I was eaten by a velociraptor or if I want the lottery or whatever and walked
away from work, then this script would, would be less easy to use.
And there are a lot of people who, who, um, who wouldn't be able to look at the ox script
and kind of reverse engineer it easily.
So that seemed silly not to have it documenting itself, plus there was this stupid problem where
while I was writing the script, I used certain variables to represent, for, for, for a value.
And then once I was starting to sort of use it, I, I realized that in my head I had imagined
a different set of variables.
And so every time I went to use it, I would use my, in the head variables rather than
what I'd actually written variables.
And, and so every time I used it, I would do it wrong.
So that kind of got to be stupid.
And I realized I needed a way to invoke the script, the self-standing ox script with a dash
dash help option or with no option to receive documentation.
I've learned, I think through, through trial and error that, that there are two ways to
do this.
It's probably actually better than the other.
It provides a more intuitive interface, but I'm gonna, I'm gonna throw both of them out
here, because I think they're both worth, is, I think it's worth talking about each one.
So the first one, and the one that I'm using, because it was the easiest one from the point
that I was realizing that I needed this, it was just the easiest, easiest one to tack
on to the existing script.
So this is in, this is in-auch itself, or, or, or canoe-auch, I'm, I'm, I'm using canoe-auch,
so I, I can't speak for mock or, or knock, or any of the other ox, but, but in canoe-auch,
at least, one of the things that I learned, and I don't remember if I learned it from Dave
Morris and Be Easy, or if I learned it from the canoe-auch documentation, that's, at some
point during my lessons, I kind of switched over from relying on Dave and Be Easy to just
relying on going to the documentation and, and looking something up, which is a great
feeling. I mean, that's not, that's not saying that Dave and Be Easy became less effective.
It's just saying that they, through their lessons, made that documentation actually make
sense to me to where I could actually go construct things from, from just looking something
up on the documentation site, which is a, a great feeling.
So I learned this, this thing about awkward, you could pass variables to your ox script
as options appended to your ox command.
For instance, let's say that we wanted to provide an option for the user to, to, to, to dynamically
define at, at execution time, at, at the time of invoking the, the command of the script,
they want to, we want to let them define how many pages we want to insert into this imaginary
PDF and this imaginary bookmark command script. The, the way that we could do that is a dash,
a sign, space pages equals some number, or just dash v for variable, I guess, dash v pages
equals eight. So in other words, if we named our script bookmarkinsert.ock, then when the
user executes, and we want the user to be able to execute bookmark-insert.ock, dash v pages
equals eight, or dash dash assign pages equals eight, then in the ox script, we would have
the variable pages already defined for us. It just, it just gets passed right into the
script. So you could do, if, if we did that bookmark dash, insert.ock, dash v pages equals
whatever, some number, then in our, anywhere in our script, we could then use the variable
pages as if though we had, as if though we had assigned it ourselves. So a really simple
proof of concept code snippet here, and I'll put this in the show notes, just, it would
be shabang slash user slash bin slash ock space dash f, which of course is the, the other
ock tip that I did in a previous episode. And that makes sure that, that, this file is
being executed as a script. And then begin, curly brace, print f, quote, space, quote,
percent s, space, no, that's it really. Let's do a backslash in. So percent s, backslash
in, close quote, and then comma, and then pages, semicolon, and then close your curly
brace. Now you've got a very simple thing. I didn't actually, I didn't run that, but
I'm, I'm betting that if you run that script, the proof of concept script, and, and did
dash v or dash dash assign pages equals 13, then when that, and press enter, then you'll
get 13 echoed back at you in your terminal. And you could, you could make a little bit
pretty area print f, space, quote, percent s, space, percent s, backslash in, quote, comma,
and you say, quote, you have defined space, close quote, comma, quote, no, no, quote, pages,
semicolon. And then you would get, you would define 13, you know, or whatever number you
defined as the dash v pages equals 13, or some integer. So that's, that's the, that's
the first thing that we need to understand on, on how to get this sort of self documentation
going, because obviously just working with our proof of concept script now that I've
got that, if pages is left undefined, then we could opt to provide a useful help message
for the user. And the way that you would do that is exactly as we've been doing, but in
our begin statement rather than just printing, you have defined some number of pages, we would
first check whether pages had been defined. Now in my script and my real script, I just
check to see if pages is zero, because that doesn't make sense for my, in my use case.
But in real life, or, or in other use cases rather, my script is actually something that
I use in real life. In other use cases, you would probably want to check to make sure,
or, or you would want to verify that whether the, the variable contains content. So the,
the way that you would probably do that, that I can think of is, if parentheses length,
that's an arc function of, of length, just to get the, the, the length of the value of,
or the, the length of some, some thing. So if we pass our variable, and if we're calling
that pages, then we can do, uh, length parentheses, pages, close parentheses, equals, equals zero,
close parentheses, curly bracket, then the help message, close curly bracket, and then
else curly bracket, do the thing that you actually want the script to do upon success,
uh, or upon existence of the variable, and then close curly bracket. Now, at, at the end
of your help message, you need to provide an exit function, because otherwise, arc would
continue to execute the rest of the script, because this is all in the begin portion of
the, of the arc script, and it, it will happily not print a help message and then continue
to try to execute the, the, the, the, the rest of the script. So you do want to put an exit
statement, which is just the word exit. Um, and, and you can see the, the show notes for
the, the proof of concept script, it's, it's really, really simple, but that's the, that's
the basic idea. What are the drawbacks of this, of this little, of this method? Well,
there's one, I guess, rather, rather severe one, which is if we do, if it was, so first
I'll make it, schemaad plus x, uh, test dot, ock, so that I can execute it, and then
we'll try it out. So, bin, test, ock, dash, dash, assign, var, pages, I mean, now I'm using
two different things, um, equals 13, return, you have entered 13, okay, cool, so that works.
Now if I assign, if I do, if I do it with nothing, I get my help message, and that works,
uh, the, the other test is to do the thing that probably you as a user of Linux or Unix
would probably think to do in the first place, and arguably you might even think to do this,
whether you're not, you're very used to using Linux and Unix, it's just something that
you'd probably, into it eventually, you could do a dash a, or a dash, dash help, and we
do get a help message, but it's not the help message that I as the proof of concept
tour would want. In other words, the dash, dash, help message gets, or the, the dash,
help option gets passed straight to ock. My script never doesn't pick it up, it doesn't
get the help message, uh, option, ock intercepts that, and dumps an ock help message. So that's
a big drawback of, of, of doing this, of, of doing it this way, you don't actually get the
dash, dash help, I don't know of a way around that to be honest, uh, because the, the options,
at least in GNU Ock, and I, I imagine it's probably the same for the others, they, they,
they get passed actually to ock, which is why there's that weird kind of
backwards, or, or what we would think of as, maybe, over complex assignment of variables,
you can't just say dash dash pages equals 13, or whatever, you have to say dash dash assign
pages equals 13. So it, to a Linux user, none of this feels natural, and that's probably the
biggest drawback of this, of this method. So that's method zero, method one is to do all of this
in a shell script. So essentially, wrap, wrap this process in, in bash, or, or whatever you're
preferred, shell scripting, language is, I'll just do shabang slash bin slash sh, I think that'll
be safe for this particular, particular thing. And we know, we'll, we'll just do this really kind
of sloppy for this proof of concept. We know that the first variable passed to, to bash can be
interpreted, or, or can be viewed at the dollar sign one position. So we can do the old if
square bracket, quote, dollar sign curly bracket ones, close curly bracket, close quote, equals
quote, dash dash help, close quote, dash 0 for, or dollar sign, or quote, dollar sign, curly bracket
one, curly bracket, close quote, equals quote, dash h, close quote, close square bracket,
semicolon then, and we'll say echo, this is a help message. Let's do that real quick.
And then we'll close that if statement. So if, if, oh, and we'll, before that closing it,
we'll do an exit as well. So it prints help and then it exits. Now, if we get passed that if
statement, we'll, we'll do an echo. You made it, and then quote, echo, quote, you provided,
and then we'll just echo dollar sign, or quote, quote, dollar sign, curly bracket one,
close, curly bracket. And I think that should work. So we'll Chimod. Actually, we don't need to
bother. We'll just do a SH bin test 2 dot SH dash dash help. We get a help message. And 13,
we have, you provided 13. Okay, cool. Wouldn't leave that as my final version. But let's go with it
for now. So what we'll do now is we can it within this script, we can do an arc,
we can do some arc stuff. And the way that we would do that is we would just, we would call
now in real life, I would do a check to make sure that we're, to find out what version of
arc we're actually using. And I would make sure that everything was very, very compliant or
portable, and so on. But I'm not going to do that for this. Just know that in real life, we would
be more careful about what we're calling. And the location of it, for instance, even if I type
user bin arc, we can't be sure that the system's going to have user bin arc, right? It could be in
bin, it could be in user local bin, it could be not aliased at all to anything. And we would need
to call arc, or goc directly. Who knows? I don't know how you'd find that out actually. But
I mean, I guess you could, you could brute force it. But anyway, point being, we would want to make
sure that we did these kinds of checks. But I'm not going to. So slash user, slash bin, slash
arc, and then dash dash assign, no, actually not dash dash assign dash V, because I happen to
know that the dash dash assign is a goc convention. The long option is a goc feature. I don't think
it's available in all ox. So dash V to define a variable, and then we'll use a variable name
called, I don't know, pages. I guess that's what I'm using now. Equals, quote, dollar sign,
curly brace one, curly brace, close quote, space, single quote, to start our, our, our
arc, stanza, and then begin all in capitals, curly brace, print f, quote, percent, s, space,
percent, s back slash in, close quote, comma, quote, you provided, close quote, comma, pages,
semicolon. So in other words, we have wrapped, we've, we've created the shell script with the
sole, the sole purpose of the shell script is to parse our options. Whatever it gets, it then
passes on to arc and launches a whole separate arc process. And if we try it out, if we do it,
bin test 2 dot s h, nothing, we get, oh, that's not executable yet. So s h, bin test 2 dot s h,
and nothing, we get, oh, we don't get an error because we didn't check for nothing. Okay, well,
dash dash help that, that ought to give us our help message, at least. This is a help message,
yes. And then if we actually provide a string 23, you provided 23. So there you go, it works.
As I say, in real life, we would also want to check for an empty string. If we didn't get
anything, we would want to process that probably with the help message. I think that would be a
nice sort of friendly thing to do, but I guess it depends on the context of what your script is
actually doing. But there you go. That's two ways that I kind of figured out how to provide
help messages and sort of quick documentation for a script that you, that really is essentially
just an aux script. And I hope that's useful. There might be better ways to do it. I couldn't find
anything from a cursory glance online. So that's just, those are the two methods that I came up with.
Hopefully, that's useful to somebody. Thanks for listening. Talk to you next time.
You've been listening to Hacker Public Radio at HackerPublicRadio.org.
We are a community podcast network that releases shows every weekday, Monday through Friday.
Today's show, like all our shows, was contributed by an HBR listener like yourself.
If you ever thought of recording a podcast, then click on our contribute link to find out
how easy it really is. Hacker Public Radio was founded by the digital dog pound and the
infonomicon computer club, and it's part of the binary revolution at binrev.com. If you have
comments on today's show, please email the host directly, leave a comment on the website or
record a follow-up episode yourself. Unless otherwise stated, today's show is released on the
creative comments, attribution, share a light, 3.0 license.