Export Script argument parsing

Exporting & Previewing
1

Ah, I think that might explain the “import argparse” part of the sample code.

I was looking at the sample code and I’m like… how’s it actually doing anything? :smile:

I don’t know what’s the equivalent in JXA, but that’s at least something to look for.

2

(I moved this to a new topic since it wasn’t strictly related to the original, but wanted to comment)

argparse is a great library! Not only does it handle making sure the right arguments come into the script and making them easily accessible by the programmer, it even can print out usage if the input patterns don’t match what it is expecting.

The basic structure I used for the export scripts is:

  • parse arguments
  • switch based on which primary argument it is (get_options, replace_url, modify_staging_path, or check_for_updates)
    • optionally use the other arguments to determine what to return
3

Is this the same kind of argument?

It seems related, but I’m not used to doing stuff like this on Mac :smile:

Like this… https://github.com/tumult/hype-export-scripts/#get_options

There’s the --get_options argument… then it has return arguments, which means :man_shrugging:t2:

Is that supposed to be used in the Terminal, like a command line?

4

WOOO HOOO!

Getting closer!

Mac-mini:~ Photics$ /Applications/Hype.app/Contents/MacOS/Hype2 -P --get_options
2017-08-09 07:25:59.698 Hype2[8133:1311908] Hype Thumbnail Generator Webkit Version mismatch. Thumbnail: 11603.3.8 Hype: 11601.7.8

I renamed the “Hype 3.app” to “Hype.app” to make it easier to experiment with.

5

Yes - macOS is a UNIX-based OS and you can run commands from a command-line terminal with arguments, like what that box provides.

Whoops, that's a typo :smiley:. I've fixed this and hopefully clarified the return value.

Not exactly; Hype will run your export script and send it those arguments.

You do not need to send arguments to Hype, it is Hype that runs your command line script and sends it the arguments. The arguments Hype sends is basically a request for it to get data back in a certain way.

Thus you don't need to run Hype from the command line at all. You could run your script from the command line though for easier development perhaps. The only advantage to running Hype from the command line is that it may be easier to see the export script debug logs if you have that enabled.

6

Heh, I'm more confused now. What's the significant of the backslash?

What I meant is I don't know exactly how the API is supposed to work. You have the API in four sections. I don't know how each subsection is supposed to work. Like, how do I change the settings using JXA? (I know Python is more popular, but JXA is based on JavaScript and more Mac native. It's an option in Script Editor. Unless Hype is going cross-platform, I think JXA might make more sense. Maybe that's a bad idea, but I'm not any less confused when looking at the Python code. HA HA.)

Examples of confusion...

  • get_options ...so is there a set_options? Is that the wrong type of thinking? What is the most basic... exportShouldIncludePIE = false
  • check_for_updates ...OK, so I can let people know the script is updated, so this is different than the Hype version. I sorta knew that, then doubted myself, then checked again.
  • replace_url vs modify_staging_path ...which one do I really need? I think it's modify_staging_path, as I want to change where the project is saved.

I feel like this needs one of those flow charts. :smile:

I'm getting confused as to what exactly is doing the getting. Here's part of the reason I'm confused...

Export Scripts may be called when Hype is launched, re-activated, and multiple times when previewing or exporting a document.

Problems...

  • I'm not quite sure how to tell the script... whoa whoa whoa, don't do anything yet. That's just Hype starting up.
  • How to translate Python to JXA
  • How to actually get things to run using a Hype script.

Anyway, that's what I'm thinking. I'm still experimenting. Maybe I'll figure out some more of this stuff.

7

Inconsequential to the matter at hand; some flavors of markdown use the _ character for italics and prefacing it with a backslash says "no, I really want it to be an underscore."

It works like this:

  1. Hype asks a question of the export script or asks it to do something. It does this by executing your script with command line arguments.
  2. The export script returns the requested information or performs any actions it wants. You do this by writing JSON to standard output and exiting.

Take get_options. This is Hype asking the Export Script for items like how Hype's export should be configured and what UI should be presented. Your script is responsible for letting Hype know.

It may be easiest to look at the debugging logs for a functional export script. Here's get_options for the DoubleClick Campaign Manager script (slightly cleaned up for clarity):

Hype calls the script with arguments:

running: /Users/deutschj/Library/Application Scripts/com.tumult.Hype2/DoubleClickDCM/DoubleClick DCM.hype-export.py --get_options --hype_version 4.0.0 --hype_build 599

(You could run this type of command yourself from Terminal when debugging)

The export script outputs a JSON dictionary and exits with:

{
  "result": {
    "document_arguments": [
      "clickTag"
    ],
    "export_options": {
      "exportShouldSaveRestorableDocument": false,
      "exportSupportInternetExplorer6789": false,
      "exportShouldIncludeTextContents": false,
      "exportShouldNameAsIndexDotHTML": true,
      "exportShouldBustBrowserCaching": false,
      "exportShouldInlineHypeJS": true,
      "exportShouldInlineDocumentLoader": true,
      "exportShouldIncludePIE": false,
      "exportShouldSaveHTMLFile": true
    },
    "save_options": {
      "allows_preview": true,
      "file_extension": "zip",
      "allows_export": true
    },
    "extra_actions": [
      {
        "function": "hypeAdExit",
        "label": "Exit"
      }
    ]
  }
}

The Hype application then uses this data.

This call is for changing the value of resources only. The original use case was ad tech systems that needed to change "myimage.jpg" to something like "$$_AD_SYSTEM_FILE['myimage']$$" because they perform substitutions themselves later.

You can likely ignore any calls with this argument for your purposes.

This is the main call that you want. This is the final call of the export script lifecycle - it is basically saying "Hype has written everything it knows about out to a temporary directory, can you make your final changes and then put it in the spot the user requested?"

So in this call, you would take hype output, and package it into an Xcode project folder at the user's save location.

Hype needs to call get_options at startup, as this is how Hype decides how to display information about your export script. It isn't asking to export, just getting the options :slight_smile:. It makes more calls on preview/export.

That's on you! Hype export scripts have a basic protocol of taking command-line arguments and needing to return JSON as the documentation specifies. Beyond that it is up to you. There's nothing to say you couldn't base it in Python and use JXA for talking to Xcode if you are using apple events, for instance.

1 Like
8

Oooooohhh... so the Script has the JSON. For some reason I thought that's what Hype was outputting. Like, "This is what Hype is currently set to." ...but no, if I'm understanding this correctly, the preferred options are saved in JSON – in the script – and then Hype goes and get it by running the script.

This is what threw me off... hype-export-scripts/SampleExportScript/SampleExportScript.hype-export.py at bc572eb073a7cc504280be5234a2bb2cc050615f · tumult/hype-export-scripts · GitHub

It's commented out, so I thought that was the guide as to what to expect as a result from Hype... get_options ...but it works as a way to set the options – if I'm understanding this correctly.

9

Correct, those lines are an annotated structure on what you should be outputting for your JSON dictionary.