Re: AppleScript "standard libraries" project - need to hand, off now
Re: AppleScript "standard libraries" project - need to hand, off now
- Subject: Re: AppleScript "standard libraries" project - need to hand, off now
- From: has <email@hidden>
- Date: Tue, 28 Jun 2016 17:54:25 +0100
Takaaki Naganoya wrote:
I read your whole "standard libraries”. This is a painstaking work. It is very tidy.
But I found it is hard to maintain.
Many thanks for your response: it is important that other ASers say
exactly what they think, so that I can understand exactly what is and
isn't working right and can pass that information on to the next
maintainer. We'll go over your specific points in a moment, but let me
just go over what I think might be common concerns first, and if you
agree or disagree with any of them then please speak out:
1. As I've said before, there may well be some technical issues still to
sort, e.g. bugs, badly designed commands, commands that aren't useful
enough to justify inclusion, and so on. These libraries are not 100%
finished and won't truly be until they've been in widespread public use
for some time, because even the best written and documented code can't
predict all the faults and shortcomings that actual users are going to
discover when using them for real. That said, bugs and omissions aside,
they're still far more solidly written and thoroughly tested than 99% of
AppleScript code out there, so don't worry _too much_ either. If you
find specific problems, make a list and send it over.
2. In reality, I think most problems with these or any other libraries
are that AppleScripters simply aren't accustomed to using libraries, and
are overthinking things and turning it into a problem when it's not. Had
AS's library loader been introduced in System 7.5 or OS 8, which is when
it should've been added, this would not be a problem because everyone in
the AS community would already be completely familiar and comfortable
using, writing, and sharing libraries with everyone else. Trust me on
this, because that's exactly how it is in every other language that
didn't destroy its original development team five minutes after v1.1 was
out the door. There's NOTHING SPECIAL about libraries; they're just
another tool in your toolbox that saves you a ton of time by giving you
lots of useful features for free.
3. A third problem with these - or ANY - libraries is that "Not Invented
Here" syndrome is as widespread in the AppleScript community as in the
AppleScript team, i.e. endemic. Many AppleScripters do not trust
AppleScript code that has been written by other AppleScripters - which
actually isn't a bad thing as most AppleScripters are terrific at
application scripting but middling to lousy at programming. That said,
anyone who thinks my code isn't up to professional standards, please
raise your hands and I'll happily direct you to all my previous work for
you to kick the tyres yourselves. If you already trust the software
written for you by the AppleScript team then you should not be worried
about the quality of my code, because most of their code is WAY crappier
than most of mine. *I* wouldn't be offering anyone this code if I didn't
think it was up to the task: I'd be throwing out and rewriting it till
it was, or nuking it from orbit and never speaking of it again. Unlike a
lot of so-called "professional" programmers, I take my liabilities
seriously: if my code breaks your stuff, you have my personal permission
to kick my ass, because that is my mistake, not yours, so I completely
deserve it.
OK to summarize the above:
Treat third-party libraries *exactly* as you do third-party osaxen and
scriptable apps: do not even think or worry about what's inside; just
read their documentation, try the examples, and then use them to do
whatever it is you need to do. The only thing that matters about using
third-party libraries, osaxen, and apps is that actually do exactly what
they claim to do and never crash or corrupt your data. My AS code is
damn near bombproof once done, so if you're worried about whether these
libraries are reliable to use then please indicate this, because that's
a problem that needs to be addressed using better education,
documentation, and examples.
Now, let's go over the specific points, as I appreciate there's some
language barriers here so I need some help to make sure I understand
right. I'll include explanations where I think I've understood
correctly; if I've misinterpreted then ignore and tell us so.
1. SDEF is an obstacle in this project. It is too heavy to edit for me with Script Editor on my MacBook Pro 2012. I found it a mistake to use SDEFs with such a large editable library.
I totally agree that SDEFs are garbage, and an incredibly bad idea in
libraries, but I don't understand why you say they're "uneditable"? You
shouldn't be using SE to edit them, of course: use Shane's ASOC editor,
which includes an SDEF editing interface, or a decent text editor like
BBEdit or TextWrangler if you don't mind typing XML crap by hand, or
there's plenty general XML editing apps out there should you prefer to
split the difference. Obviously I recommend the next maintainer runs all
my SDEFs through an XML/SDEF validator as there may be typos in the XML
markup and/or HTML documentation sections, and squashing those will
avoid any future glitches. However, I've never had any problems writing
or editing these .sdef files myself; there's no problems with speed or
anything like that; so if you're having problems editing them then
there's something wrong with the tools you're using or how you're doing it.
And yeah, I would *much* prefer not to have used SDEFs, and certainly
wouldn't had they only been for my use. However, these libraries need to
be easily used and understood by even the most novice AppleScripter, so
using any other format to document them was out of the question. Plus
many of the commands make all but their most basic parameters optional,
so that you don't have to be a rocket scientist to understand or use
them to do the most common and simple stuff. Had I not used SDEFs I
would have had to make all parameters required, or make the user pass
all the parameters in a single record, because AppleScript itself still
doesn't allow users to define optional parameters in non-terminology
handlers, even though there's absolutely no technical reason for doing so.
In other words, I used SDEFs not for the library maintainer's benefit
but entirely for the *users'* benefit. If there was any other practical
choice, I'd have taken it. If there's a particular SDEF-related problem
you encounter when using these libraries in your own scripts - for
example, you get a terminology conflict or you find some of the
documentation hard to navigate or confusingly organized - then please
point those out. For example, SDEFs are _supposed_ to support linking to
other documentation files in newer OS versions, though I've never
actually tried this myself, and I know there's several places in the
docs where advanced topics would probably be moved out of the main SDEF
into linked pages to avoid overloading readers with too much information
at once.
Oh, and I also know that the font styles used in Script Editor's
dictionary browser make it tricky to distinguish between 'normal' text
and 'code' text. However, that is entirely Apple's fault for picking two
san-serif fonts that look almost identical except for slight differences
in letter spacing (proportional vs monospace); SDEFs have no real
control over styling (and nor should they). Funny enough, had exactly
the same problem with the Apress book, and yeah, did ask them to use a
different font for the code but it was their "house style" (so
presumably all their other books had the same readability issues too).
So if the poor presentation and styles in Apple's dictionary browser is
something that bothers you then file Radar tickets on it with Apple. (Or
get Script Debugger which has an infinitely better dictionary viewer
than Apple's crap.)
2. This library is not practical. Only low-level functions are not here as professional level scripters are using.
Not sure what you mean by that; probably a Japanese-to-English
translation glitch. Do you mean these libraries are lacking "low-level"
functions that ASers commonly need, or that the functions they do
contain are all too "low-level" for ASers' needs. All the commands in
the seven "public" libraries (Text, Number, Date, List, File, Objects,
Web) break down into three categories:
1. Reliable, robust versions of everyday commands that ASers
traditionally copy and paste as source code, or get from osaxen (or used
to; most osaxen no longer work now): uppercaseText(), findAndReplace(),
sortList(), roundToPlaces(), readFile(), etc.
All I've done is package those routines into easily reusable libraries,
and tested and documented them to make sure they work correctly and
don't do stupid things even when fed invalid inputs. Sure ASers can copy
and paste findAndReplace() and sortList() routines off the internet, but
unless they're a bit of an expert they have no idea whether they're any
good or not.
For example, there's no difference between using the `search text`
command in the Text libraries and the `find text` and `change` commands
in Satimage.osax: I've just combined both into a single command whose
replacement text parameter is optional; if anything, mine are actually
simpler and easier to use because I've condensed it down to only the
parameters that are actually needed and discarded all the old obsolete
regexp syntaxes in favor of ICU, which is the one that OSX already uses
itself.
The only library that might initially freak ASers out is Objects, as
most ASers have never done OOP in AppleScript so aren't used to working
with script objects like this. However, ASOC has been around several
years now so that there are enough ASers around who are used to working
with NSDictionary, so apart from syntax differences it's just the same
thing, only using pure AppleScript instead of going across the ObjC
bridge. Shane already provides a "SmartDictionary" library which is just
a script wrapper around an NSDictionary, and while that might be a bit
faster when working purely with strings and numbers it's an absolute
nightmare of nasty gotchas, data corruption, and crashes as soon as you
try to pass it anything more complex like records, application
references, or script objects. So Shane's library really ought to be
called "DangerousDictionary", because none of these gotchas are anything
close to adequately documented, leaving trusting users to fall into
those traps all by themselves. The Objects' library's Dictionary script
object may not be as fast as NSDictionary because it's almost all
written in pure AppleScript, but it avoids all those gotchas and still
provides magnitudes better performance than the sort of ad-hoc key-value
list-searching code AppleScripters would typically write themselves.
Hell, Jon Pugh still occasionally shills his prehistoric "SmartString"
library, which aside from being worse than useless for modern text tasks
(it's pure ASCII-only) packages all its handlers in a completely useless
OO wrapper, which solely to confuse users and make them jump through
completely pointless hoops for simple tasks that only ever needed simple
procedural handlers. Now the Text library provides a simpler, correct
way to manipulate AS text, Jon can now at last take that old stinker out
back the woodshed and bury it at last - an Unreservedly Good Thing, yes?!
2. Routines that wouldn't be needed if AppleScript hadn't screwed up
itself or lost that capability itself.
For example, manipulating file paths correctly is a giant PITA in
AppleScript due to all the dodgy old obsolete types like `alias` and
`file specifier` combined with shoddily designed `POSIX file` and `file`
later slapped on top. The `join path` and `split path` handlers save
users from having to deal with all that mess themselves: just pass in
whatever values you have and the correct result comes out. It took me
half a chapter to explain this nonsense in Learn AppleScript and it
still was confusing as hell; now it just takes a quick glance at a
dictionary to figure out how.
Similarly, the `read file` and `write file` commands make it dirt easy
to do what users traditionally had to write several lines of error-prone
StandardAdditions commands to achieve, with the added bonus that they
understand a dozen extra plain text legacy encodings that are still in
depressingly common use: no need to add even more error-prone `do shell
script "textutil ..."` commands to your script to cope with
Latin1-encoded files, for example.
Or the `send HTTP request` command, which replaces the old
upload/download FBA that used to be in OSX until Apple took it out one
day with zero explanation. Sure you can use `do shell script "curl..."`
which is powerful if cryptic, but for the most common, simple tasks
`send HTTP request` is easier. Plus the Web library comes with a bunch
of extra handlers for related tasks like splitting, joining, and
encoding URLs, and converting data to/from JSON which you can already
download a separate third-party FBA for but now get included as standard.
Or the `parse/format number/date` commands (and I'm still open to
suggestions for better names, btw, as I realize the terms "parse" and
"format" aren't ideal), which eliminate ALL of the portability problems
that users run into when converting text values to and from numbers and
dates using AS coercions, because they always use standard global
formats that are recognized everywhere. Plus you get a bunch of extra
formatting options should you want to display numbers and dates in
custom formats of your own choosing - no more need to mess around with
arcane yet limited garbage like `do shell script "date ..."`, for example.
I mean, Apple just put their "Essential Subroutines" section back up on
developer.apple.com a decade after it was removed from it, and those
routines are so grossly incompetent and wrong that everyone involved in
their restoration deserves sacked on the spot because they are utterly
unfit at their jobs. Anyone who uses those routines and think they're
better than what I've provided because "Apple wrote them", please step
up with some examples of how you're using it and I will show you all the
ways your code is now WRONG as a result. Apple couldn't write good
AppleScript code if their lives depended on it. Why d'you think I wrote
these libraries? It wasn't for my benefit: 99% of my work is in Python now.
3. Routines that AppleScript has never had, but after 15 years of OS X
would be nice if it did.
The big one there obviously is the Shell Script Support suite in the
File library. Obviously AS users have long been able to write shell
scripts in AppleScript by adding `#!/usr/bin/osascript` at the top and
saving as plain text, but they've never had a quick-n-easy way to make
those scripts read data from Unix's stdin, or process `-a`,
`--this=that`, etc style options. There's almost as much code gone into
implementing those commands as an entire library, yet users never need
to know or care about that: they just write a list of records saying
what options their script takes, and out comes all the values, fully
checked and converted, ready to use. It even automatically generates a
big chunk of their `--help` documentation completely for free. Sure,
most AppleScripters don't write AppleScript-based shell scripts, but is
that because they don't need them or because it's traditionally been
more work to do than it's worth? Now it can all be done in a couple of
commands at zero extra cost to ASers, I guess we shall see.
3. Your script is not an instructive example. It seems demonstration-purpose one just as you wrote. There is a need to decipher.
I'm not sure what scripts you're referring to.
The libraries? That's not teaching code, it's *production code*. It's
written to be as fast, efficient, and *reliable* as possible, not to
teach ASers how to write AS code, never mind how to program. You want to
learn how to write AS code, buy one of the better AS books off Amazon.
You want to learn how to program properly: there are tons of resources
out there to learn. My first recommendation's always to get a high
school Computing textbook first, and once you've grokked that get a
first-edition copy of Code Complete off ebay. And, of course, write,
run, test, throw away, and redo lots and lots of code until you get good
at it.
The unittest scripts? Those definitely aren't intended for users.
They're purely there so that whoever is writing and maintaining these
libraries can run automated tests to check that everything works
correctly and they haven't broken anything by accident. They're not
supposed to be distributed to users; only the libraries are.
The examples in the SDEFs? I don't think you mean those, because those
*are* the instructive examples that demonstrate to users how the various
commands can be used. The main problem with those is that there's not
enough of them yet: adding examples to commands that don't yet have any
is left for the new maintainer to do.
----
Apologies for length, but it's easy to forget just how many new and
improves features these libraries pack in, and how important it is to
get everything right for AS users - from fixing bugs, to improving
documentation and code examples, to just teaching ASers what libraries
are and why they should care or want to use them. The last one of which
is supposed to be Apple's damn job, mind, but if the AS community was to
rely on them we'd STILL be waiting for them to tell us how the hell to
use AppleScript-ObjC! Hopefully these libraries can do to crappy
everyday make-work coding tasks like list sorting and string searching
what Shane's amazing contributions have done for GUI development: make
them infinitely quicker, easier, and a tiny fraction of the pain in the
butt they were before.
Anyway, back to you folks. No volunteers so far to take over the project
and get these libraries into AS users' hands at long last, but there's
still a week and a half to go, so plenty time for someone to step up
yet. Do it for your community, not to mention yourself!
Many thanks,
has
_______________________________________________
Do not post admin requests to the list. They will be ignored.
AppleScript-Users mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
Archives: http://lists.apple.com/archives/applescript-users
This email sent to email@hidden