Join List items Applescript Script libraries command

 join list items command

#the list

set  theList to {“the”, “cat”, “jumped”, “over”}

#join the list

set theString to  join list items theList using text space

Result:

“the cat jumped over”


After watching Apples  Introducing AppleScript Libraries  WWDC 2013 session 416. I wanted to share one of my simple Applescript Libraries commands.

Applescript Libraries are a new thing in Mavericks which allow you to put all you commonly used Applescript handlers in one place to make them easily accessible  in any new script.

As apposed to having them only in snippet file or some script file  stored somewhere you cannot remember where or what exactly the code contained to help find it.

An even better thing is Applescript Libraries also allow you to create a Scripting Definition file for you handlers. i.e your own terminology/syntax and you the user can write them yourself very easily.  Which was not the case for scripting additions for which Applescript Libraries partially replace.

Apple quote.
In a major update and enhancement to its native scripting language, OS X delivers a new plugin architecture for AppleScript, enabling easy development and access to custom sets of functions and methods. Each individual AppleScript Library, saved as an AppleScript script file, can publish its own scripting terminology, and contain dozens of routines written in native AppleScript or the incredibly powerful AppleScriptObjective-C. Scripting just got a whole lot better!

 


 

You will be happy to know I  am not going to repeat some of the stuff written by apple to explain how to build the libraries. They are very easy to do and Apple provide a very good   Introducing AppleScript Libraries  session  over on their developers site to explain about the libraries and how to build them. And me doing so would be a considerable waste of my time trying to do a better job.

There is also a excellent tutorial over on Macscripter.net by DJ Bazzie Wazzie

 

Some nitty gritty first


 

So what we have here is an example. Possibly one of many I will post.

Some times I want to join a list of text items up as a single string. Using Applescript Text item delimiters and a handler I stowed some where in some script…

#Join Handler

on joinAList(theList, delim)

        set newString to “”

        set oldDelims to AppleScript’stext item delimiters

        set AppleScript’stext item delimiters to delim

        set newString to theList as string

       set AppleScript’stext item delimiters to oldDelims

return newString

end joinAList

#the list

       set theList to {“the”, “cat”, “jumped”, “over”}

#join the list

       set theString to my joinAList(theList, ” “)

I would not only have to find that code where ever I have it stored. But if I cannot find it I would have to reinvent it.

If I had that handle in a Applescript Library then that task would be easier.  But I would still have to remember the handlers name and arguments..

 

What if I could just type:


use script “Text Utils”

#the list

set theList to {“the”, “cat”, “jumped”, “over”}

#join the list

set theString to join list items   theList  using text   space 

Well I now can. If I give my library a sdef file I can shape the command into words I can easily remember. “join list items

Following Apples instructions in the Introducing AppleScript Libraries session.  WWDC 2013 session 416.

 

BRIEFLY BECAUSE I EXPECT YOU TO WATCH/READ THE APPLE SESSION


 

 

I saved a blank Applescript bundle  file.

I then set the details in the Bundle drawer to reflect the name of my sdef file’s terminology’s name, bundle id, and  check the Applescript Objective – c because this library will be using AppleScript/Objective-C code.

applescriptBundleForASlib

Script Library Name : “Text Utils”.

Bundle ID : “com.apple.ScriptEditor.id.TextUtils”

Script file Definition Name (extension not needed) :”Text Utils”.

And then copy over my sdef file into it’s Resources by dragging the file from the finder and directly into the Resources section in the Documents drawer.

Then re save the Applescript Bundle.

 

The Scripting Definition file

Comprises of a plain text xml file with the extension “.sdef” and a dictionary as described by Apple.


 

 <?xml version= “1.0” encoding=“UTF-8”?>

<!DOCTYPE dictionary SYSTEM file://localhost/System/Library/DTDs/sdef.dtd >

<dictionary>

            <suite name=“Text Utils”code = “MOSX”  description=“Commands to process text”>

                <command name=“join list items”  code =“MOSXJLIT” description=“Join the items of a list into a string” >

                    <direct-parameter type=“specifier”  description =“The List of items to be joined”/>

                    <parameter name=“using text” code =“JLtx” type=“text” description = “The string to join the items of the list with”/>

                    <documentation>

                        <html>

                            <![CDATA[

                                <style type=”text/css”>

                                p.sdef1 {margin: 0.0px 0.0px 0.0px 39.2px; text-indent: -39.3px; font: 12.0px Verdana; color: #5e6161}

                                p.sdef2 {margin: 0.0px 0.0px 0.0px 39.2px; text-indent: -39.3px; font: 12.0px Verdana}

                                p.sdef3 {margin: 0.0px 0.0px 0.0px 39.2px; text-indent: -39.3px; font: 12.0px Verdana; min-height: 15.0px}

                                p.sdef4 {margin: 0.0px 0.0px 0.0px 39.2px; text-indent: -39.3px; font: 12.0px Verdana; color: #012fbe}

                                span.ssdef1 {color: #0433ff}

                                span.ssdef2 {color: #4f8f00}

                                span.ssdef3 {color: #000000}

                                span.ssdef4 {color: #812fdc}

                                </style>

                                </head>

                                <body>

                                 <p class=”sdef3″><br></p>

                                 <p class=”sdef2″>Examples</p>

                                  <p class=”sdef3″><br></p>

                                <p class=”sdef1″>Needed Use Clauses</p>

                                <p class=”sdef2″><b>use</b> <span class=”ssdef1″><i>script</i></span> “Text Utils”</p>

                                <p class=”sdef3″><br></p>

                                <p class=”sdef1″>#example 1.</p>

                                <p class=”sdef2″><b>set</b> <span class=”ssdef2″>theList</span> <b>to</b> {“the”, “cat”, “jump”, “over”}</p>

                                <p class=”sdef4″><b>join list items</b><span class=”ssdef3″> </span><span class=”ssdef2″>theList</span><span class=”ssdef3″> </span>using text<span class=”ssdef3″> </span><span class=”ssdef4″>space</span></p>

                                <p class=”sdef3″><br></p>

                                <p class=”sdef1″><b>Result:</b></p>

                                 <p class=”sdef2″>”the cat jump over”</p>

                            <hr class=”sdef1″ align=”left” width=”45%”>

                                <p class=”sdef1″>#example 2.</p>

                                <p class=”sdef2″><b>set</b> <span class=”ssdef2″>theList</span> <b>to</b> {“the”, “cat”, “jump”, “over”}</p>

                                <p class=”sdef4″><b>join list items</b><span class=”ssdef3″> </span><span class=”ssdef2″>theList</span><span class=”ssdef3″> </span>using text<span class=”ssdef3″> “”</span></p>

                                <p class=”sdef3″><br></p>

                                <p class=”sdef1″><b>Result:</b></p>

                                 <p class=”sdef2″>”thecatjumpover”</p>

                                <hr class=”sdef1″ align=”left” width=”45%”>

                                <p class=”sdef1″>#example 3.</p>

                                <p class=”sdef2″><b>set</b> <span class=”ssdef2″>theList</span> <b>to</b> {“the”, “cat”, “jump”, “over”}</p>

                                <p class=”sdef4″><b>join list items</b><span class=”ssdef3″> </span><span class=”ssdef2″>theList</span><span class=”ssdef3″> </span>using text<span class=”ssdef3″> “,”</span></p>

                                <p class=”sdef1″><b>Result:</b></p>

                                <p class=”sdef2″>”the,cat,jump,over”</p>

                                <hr class=”sdef1″ align=”left” width=”45%”>

                                </body>

                            ]]>

                        </html>

                    </documentation>

                </command>

    </suite>

</dictionary>


The   <suite name= : The name of the suite.

The   <command name= : The name of the command (verb). This is the actual string you will use as the command in you Applescripts.

The    <direct-parameter : The direct parameter is the value that immediately follows the command/verb. In the case of this library the direct-parameter will be indicated as being a specifier – a list

.

The   <parameter name=  : This is normally the command  preposition: i.ewith”, “by”, etc. But we use  “using text

The  <documentation>  <html>  <![CDATA[   ]]>  </html>  </documentation> tags contain the html which is used as a example documentation.

The  type specifies to the user what type of argument/ value is needed for a parameter

The description describes what the element is for.

The code :  the unique command/parameter code

 

Now we have the sdef file saved in the Applescript document’s bundle we can add the code to the Applescript document.

We need to do this after we  have completed the above because trying to enter the text before will not work due to the documents not knowing about any of the terminology described in the sdef. Now we have the sdef file saved in it’s bundle it will.

 

The  handler code


 

#JOIN TEXT ITEMS

on join list items listItems      joinText

#We check the class of listItems. Which should be a list. Returne error if not

set theClass to class of listItems

        if theClass is not list then

              error “The argument  ” & listItems & ” is not a list”

       end if

#We check the class of joinText. Which should be a text. Returne error if not

set theClass to class of joinText

       if theClass is not text then

              error “The argument  ” & joinText & ” is not a text item”

       end if

#We put the list items into a Applescript Objective -c NSArray

set listItemsArray to current application’sNSArray’sarrayWithArray : listItems

#We coerce the text item  joinText into a Applescript Objective -c NSString object

set joinTextString to current application’sNSString’sstringWithString : joinText

#We  join the NSaary objects as a string and using the NSstring  joinTextString

set newString to listItemsArray’scomponentsJoinedByString:joinTextString

return newString as text

end join list items


 

Save the document again once this code is entered and compiled.

textUtils

 

If you have saved the document into one of the Script Libraries folders then you just need to drag it onto the Applescript Library window to list it’s terminology along with all the other Applications libraries.

textUtilsLib

If not the first put the file inside one of the Script Librariesfolders. You may have to create one first. Doing so will register it to the Mac system.

The one I have placed mine in is my users Script Libraries folder : ~/Library/Script Libraries

Now when I double click on the library in the Applescript Library I get it’s terminology.

textUtilsTerminology

Usage


 

Example 1:

use script “Text Utils”

#the list

set  theList to {“the”, “cat”, “jumped”, “over”}

#join the list

set theString to  join list items theList using text space

Result:

“the cat jumped over”

 Example 2:

use script “Text Utils”

#the list

set  theList to {“the”, “cat”, “jumped”, “over”}

#join the list

set theString to  join list items theList using text “”

Result:

“thecatjumpedover”

Example 3:

use script “Text Utils”

#the list

set  theList to {“the”, “cat”, “jumped”, “over”}

#join the list

set theString to  join list items theList using text “,”

Result:

“the,cat,jumped,over”

**New to Version 2.


Version 2. Now allows you to add single quotes,double quotes or no quotes around each list item as it is placed in the final string. This is useful for example  in placing single quotes around file paths in the list. 

Examples

Needed Use Clauses

use script "Text Utils"

#example 1.

set theList to { "/Users/UserName/Folder 1", "/Users/UserName/Folder 2"}

 join list items theList using text " " with items in single quotes

Result:

"'/Users/UserName/Folder 1' '/Users/UserName/Folder 2' "


#example 2.

set theList to { "the", "cat", ", "over"}

join list items theListusing text "" with items in no quotes

Result:

"thecatjumpover"


#example 3.

set theList to { "the", "cat", "jump", "over"}

join list items theListusing text "," with items in no quotes

Result:

"the,cat,jump,over"


 

Download it

But guess what. You don’t have to write all that. Just download it. And save it to your Script Libraries folder

Download “Text-Utils.scptd_v1” Text-Utils.scptd_v1.zip – Downloaded 302 times – 7 KB

Download “Text-Utils.scptd_v2” Text-Utils.scptd_v2.zip – Downloaded 365 times – 9 KB

 

 

Hi, Please Leave a Reply