reference

Table Of Contents

CSV
JSON
Canvas
Page
Text
Files
Random
Vector
Files
Vertex
Styles

Color

background(bgColor)

Sets a background on the current page.

blendMode(obj, blendMode)

Sets the blend mode of a page item.

color(Get)

Gets or creates a color.

colorMode(colorMode)

Sets the color mode to RGB or CMYK.

fill(fillColor, [name])

Sets the fill color of shapes and text.

fillTint(tint)

Sets a tint for the current fill color.

gradient(c1, c2, [name])

Gets or creates a gradient.

gradientMode(gradientMode)

Sets the gradient mode to linear or radial.

lerpColor(c1, c2, amt)

Calculates colors between two other colors.

noFill()

Disables fill color of shapes and text.

noStroke()

Disables drawing a stroke around shapes.

opacity(obj, opacity)

Sets the opacity of a page item.

stroke(strokeColor)

Sets the stroke color.

strokeTint(tint)

Sets the tint of the current stroke color.

swatch(swatchName)

Gets a color swatch.

Data

Data#Collections

forEach(collection, cb)

Runs a function on all elements of an array.

Data#Conversion

binary(num, [numBits])

Converts a number to a binary string.

hex(value, [len])

Converts a number to a hex number.

unbinary(binaryString)

Converts a binary number string to a number.

unhex(hex)

Converts a hex number to a number.

Data#CSV

CSV.parse(String, [delimiter])

Parses (decodes) a CSV string to an array.

CSV.stringify(Array, [delimiter])

Stringifies (encodes) an array to a CSV string.

Data#HashList

HashList()

HashList is a data container to store key - value pairs.

HashList.clear()

Deletes all key - value pairs in a HashList.

HashList.get(key)

Gets a HashList value by its key.

HashList.getKeys()

Gets an array of all HashList keys.

HashList.getKeysByValues()

Gets an array of all HashList keys sorted by their values.

HashList.getSortedKeys()

Gets an array of all HashList keys in a sorted order from higher to lower magnitude.

HashList.getValues()

Gets an array of all HashList values.

HashList.hasKey(key)

Checks if a HashList key exists.

HashList.hasValue(value)

Checks if a HashList value exists.

HashList.remove(key)

Removes a HashList key - value pair by its key.

HashList.set(key, value)

Sets a HashList key - value pair.

Data#JSON

JSON.parse(text, [reviver])

Parses (decodes) a string to a JSON object.

JSON.stringify(value, [replacer], [space])

Stringifies (encodes) an object or an array to a JSON string.

Data#String Functions

contains(searchContainer, valueToFind)

Checks wether a string contains a specific string or if an array contains a specific element.

endsWith(searchContainer, valueToFind)

Checks wether a string ends with a specific string or if an array ends with a specific element.

join(array, separator)

Combines an array into a string.

nf(value, leftDigits, rightDigits)

Formats numbers into strings, with options for leading and trailing zeros.

nfc(value, leftDigits, rightDigits)

Formats numbers into strings, including comma separators to mark units of 1000.

nfp(value, leftDigits, rightDigits)

Formats numbers into strings, including a leading + or -.

nfs(value, leftDigits, rightDigits)

Formats numbers into strings, including a blank space before positive numbers.

split(str, [delim])

Splits a string using a specific string or character as divider.

splitTokens(str, [tokens])

Splits a string using a list of strings as dividers.

startsWith(searchContainer, valueToFind)

Checks whether a string starts with a specific string or if an array starts with a specific value.

trim(str)

Removes whitespace from the beginning or end of a string.

trimWord(s)

Removes whitespace and punctuation from the beginning and end of a string.

Data#Type-Check

isArray(obj)

Checks wether a var is an array.

isInteger(num)

Checks wether a var is an integer.

isNumber(num)

Checks wether a var is a number.

isString(str)

Checks wether a var is a string.

isURL(url)

Checks wether a var is a valid URL string.

Document

clear(container)

Removes all page items in a given container.

close([saveOptions], [file])

Closes the current document.

doc([doc])

Creates a document or gets the current one.

group(pItems, [name])

Creates a group from page items or gets a group.

layer([layer])

Creates, sets or gets a layer.

referencePoint([referencePoint])

Sets the reference point for the transform() function.

remove(obj)

Removes an InDesign object.

revert()

Reverts a document to its last saved state.

ungroup(group)

Ungroups a group and returns its items.

units([units])

Sets the units of the document.

Document#Canvas

bleeds([top], [right], [bottom], [left])

Sets the document bleeds.

canvasMode(mode)

Sets the dimensions of the working canvas.

guideX(x)

Creates a vertical guide line.

guideY(y)

Creates a horizontal guide line.

margins([top], [right], [bottom], [left], [pageNumber])

Sets or gets the margins of a page.

pasteboard(h, v)

Sets or gets the pasteboard margins.

Document#Page

addPage([location])

Adds a new page to the document.

applyMasterPage(page, master)

Applies a master page to a page.

masterPage(master, [pageIndex])

Sets a master page to be the active page.

nextPage()

Jumps to the next page.

page([page])

Jumps to a page or gets the current one.

pageCount([pageCount])

Returns the number of pages in the document.

pageNumber([page])

Returns the page number of a page.

previousPage()

Jumps to the previous page.

removePage([page])

Removes a page from the document.

Document#Page Items

applyObjectStyle(item, style)

Applies an object style to a page item.

arrange(pItemOrLayer, positionOrDirection, [reference])

Arranges a page item or layer before or behind other page items and layers.

bounds(obj)

Calculates the geometric bounds of a page item or text.

duplicate(item)

Duplicates a page or page item.

graphics(container, [cb])

Runs a function on a collection of graphics in a container or returns them.

items(container, [cb])

Runs a function on a collection of page items in a container or returns them.

label(itemOrLabel, label)

Tags a page item with a script label or finds an item by label.

labels(label, [cb])

Runs a function on all page items of a script label or returns them.

linkedTextFrames(item, [cb])

Runs a function on a chain of linked text frames or returns them.

nameOnPage()

Returns an item on the active page by name.

objectStyle(itemOrName, [props])

Creates or gets an object style.

selection([item])

Returns the first selected object or selects an object.

selections([cb])

Runs a function on all selected page items or returns them.

textFrames(container, [cb])

Runs a function on a collection of text frames in a container or returns them.

Document#Text

addToStory(story, itemOrString, insertionPointOrMode)

Adds a page item or string to a story.

characters(container, [cb])

Runs a function on all characters in a container or returns them.

lines(container, [cb])

Runs a function on all text lines in a container or returns them.

linkTextFrames(textFrameA, textFrameB)

Links two textframes.

paragraphs(container, [cb])

Runs a function on all paragraphs in a container or returns them.

placeholder(textFrame)

Fills a text frame with placeholder text.

stories(container, [cb])

Runs a function on all stories in a container or returns them.

textStyleRanges(container, [cb])

Runs a function on all text style ranges in a container or returns them.

words(container, [cb])

Runs a function on all words in a container or returns them.

Document#Type-Check

isText(obj)

Checks wether a var is an InDesign text object.

Environment

delay(milliseconds)

Pauses script execution for a certain amount of time.

frameRate([fps])

Sets the framerate of a looping script.

height

The height of the current page.

inspect(obj, [settings])

Inspects a var and lists its properties and methods.

printInfo()

Prints info about the current environment to the console.

projectFolder()

Gets the current document’s project folder.

property(obj, prop, [value])

Sets an objects property.

size([widthOrPageSize], [heightOrOrientation])

Sets the size of the current document.

width

The width of the current page.

Environment#Constants

stackArray

The name of the current script.

VERSION

The basil version.

Image

image(img, x, [y], [w], [h])

Adds an image to the document.

imageMode([mode])

Modiefies the location from which images draw.

Input

shellExecute(cmd)

Executes a shell command and returns the result.

Input#Files

download(url, [file])

Downloads an URL to a file.

file(filePath)

Returns a file.

files([folder], [settings])

Gets all files of a folder.

folder([folderPath])

Returns a folder.

loadCSV(file, [delimiter])

Gets and parses the contents of a CSV file.

loadJSON(file, [userAgent])

Gets and parses the contents of a JSON file.

loadString(file, [userAgent])

Gets the contents of a file or loads an URL into a string.

loadStrings(file, [userAgent])

Gets the contents of a file or loads an URL into an array of its individual lines.

selectFile([settings])

Opens a dialog to select a file.

selectFiles([settings])

Opens a dialog to select multiple files.

selectFolder([settings])

Opens a dialog to select a folder.

Input#Time & Date

day()

Returns the current day of the month.

hour()

Returns the current hour.

millis()

Returns the milliseconds since starting the script.

millisecond()

Returns the milliseconds of the current time.

minute()

Returns the current minute.

month()

Returns the current month.

second()

Returns the current second.

timestamp()

Returns a timestamp.

week()

Returns the current week number of the year.

weekday()

Returns the current day number of the week.

year()

Returns the current year.

Math

Math#Calculation

abs(val)

Calculates the absolute value (magnitude) of a number.

ceil(val)

Calculates the closest integer value that is greater than or equal to the value of the parameter.

constrain(aNumber, aMin, aMax)

Constrains a value to not exceed a maximum and minimum.

dist(x1, y1, x2, y2)

Calculates the distance between two points.

exp(x)

The exp() function returns ex, where x is the argument, and e is Euler’s number

floor(a)

Calculates the closest integer value less than or equal to a value.

lerp(value1, value2, amt)

Calculates a number between two numbers at a specific increment.

log(x)

Calculates the natural logarithm of a number.

mag(x, y, [z])

Calculates the magnitude (or length) of a vector.

map(value, istart, istop, ostart, ostop)

Maps a number from one range to another.

max(a, [b], [c])

Determines the largest value in a sequence of numbers.

min(a, [b], [c])

Determines the smallest value in a sequence of numbers.

norm(aNumber, low, high)

Normalizes a number from another range into a value between 0 and 1.

pow(num, exponent)

Facilitates exponential expressions.

round(value)

Calculates the integer closest to a value.

sq(aNumber)

Squares a number.

sqrt(val)

Calculates the square root of a number.

Math#Constants

EPSILON

Epsilon

HALF_PI

Half Pi

KAPPA

Kappa

PI

Pi

QUARTER_PI

Quarter Pi

SINCOS_LENGTH

Sin Cos Length

TWO_PI

Two Pi

Math#Random

noise(x, [y], [z])

Returns the Perlin noise value at specified coordinates.

noiseDetail(octaves, fallout)

Adjusts the character and detail of the noise() function.

noiseSeed(seed)

Sets the seed value for noise().

random([low], [high])

Generates a random number or returns a random array item.

randomSeed(seed)

Sets the seed value for random().

Math#Trigonometry

acos(value)

Returns the arc cosine of a value.

asin(value)

Returns the arc sine of a value.

atan(value)

Returns the arc tangent of a value.

atan2(y, x)

Calculates the angle from a specified point to the coordinate origin.

cos(rad)

Calculates the cosine of an angle.

degrees(aAngle)

Converts a radian measurement to the corresponding value in degrees.

radians(aAngle)

Converts a degree measurement to the corresponding value in radians.

sin(rad)

Calculates the sine of an angle.

tan(rad)

Calculates the ratio of the sine and cosine of an angle.

Math#Vector

Vector(x, y, [z])

A class to describe a two or three dimensional vector.

Vector.add(v, [y], [z])

Adds x, y, and z components to a vector or adds one vector to another.

Vector.angleBetween(v1, v2)

Calculates the angle between two vectors.

Vector.array()

Returns the vector as an array.

Vector.cross(v1, v2)

Calculates the cross product of two vectors.

Vector.cross(v, [y], [z])

Calculates the cross product from this vector to another.

Vector.dist(v1, v2)

Calculates the Euclidean distance between two points.

Vector.dist(v, [y], [z])

Calculates the distance from this vector to another.

Vector.div(v, [y], [z])

Divides this vector through another.

Vector.dot(v, [y], [z])

Calculates the dot product from this vector to another.

Vector.dot(v1, v2)

Calculates the dot product of two vectors.

Vector.get()

Gets a copy of the vector.

Vector.heading()

Returns the 2D orientation of the vector.

Vector.limit(high)

Normalizes the length of the vector.

Vector.mag()

Calculates the magnitude of the vector.

Vector.mult(v, [y], [z])

Multiplies this vector with another vector.

Vector.normalize()

Normalizes the length of the vector to 1.

Vector.set(v, [y], [z])

Sets the x, y, and z component of the vector.

Vector.sub(v, [y], [z])

Substracts x, y, and z components or another vector from this vector.

Vector.toString()

Returns data about a vector as string.

Output

Output#Console

print(msg)

Prints a message to the console.

println(msg)

Prints a message line to the console.

Output#Files

saveCSV(file, data, [delimiter])

Encodes a CSV-object array to multi-line strings and saves it to a CSV file.

saveJSON(file, data)

Encodes an object to a JSON string and saves it to a JSON file.

savePDF(file, [showOptions])

Exports the document as PDF.

savePNG(file, [showOptions])

Exports the document as PNG.

saveString(file, string)

Writes a string to a file.

saveStrings(file, strings)

Writes an array of strings to a file.

Shape

pathToPoints(obj, [addPoints])

Get points and bezier coordinates from path(s).

Shape#Attributes

ellipseMode(mode)

Sets how new ellipses are drawn.

rectMode(mode)

Sets how new rectangles are drawn.

strokeWeight(weight)

Sets the stroke width for lines and borders.

Shape#Primitives

arc(cx, cy, w, h, startAngle, endAngle, [mode])

Draws an arc.

ellipse(x, y, w, h)

Draws an ellipse.

line(x1, y1, x2, y2)

Draws a line.

point(x, y)

Draws a point.

quad(x1, y1, x2, y2, x3, y3, x3, y3)

Draws a quad.

rect(x, y, w, h, [tl], [tr], [br], [bl])

Draws a rectangle.

triangle(x1, y1, x2, y2, x3, y3)

Draws a triangle.

Shape#Vertex

addPath()

Adds a new path during shape drawing.

beginShape()

Starts drawing a complex path or shape.

endShape(shapeMode)

Finishes drawing a complex path or shape.

vertex(x, y, [xLeftHandle], [yLeftHandle], [xRightHandle], [yRightHandle])

Adds a vertex during drawing complex paths or shapes.

Structure

mode(mode)

Sets the performance mode to allow hiding or freezing the document during script execution.

noLoop()

Stops basil from looping.

Transform

applyMatrix(matrix)

Multiplies the current matrix by another one.

popMatrix()

Pops the current transformation matrix off the matrix stack.

printMatrix()

Prints the current matrix to the console.

pushMatrix()

Pushes the current transformation matrix onto the matrix stack.

resetMatrix()

Replaces the current matrix with the identity matrix.

rotate(angle)

Rotates an object.

scale(scaleX, scaleY)

Scales an object.

transform(pItem, type, [value])

Transforms an object.

translate(tx, ty)

Translates (moves) an object.

Typography

createOutlines(item, [cb])

Convert text items to outlines.

text(txt, x, y, w, h)

Creates a text frame.

Typography#Attributes

textAlign(align, [yAlign])

Sets the text alignment.

textFont([fontName], [fontStyle])

Sets the text font.

textKerning([kerning])

Sets the text kerning.

textLeading([leading])

Sets the text leading.

textSize([pointSize])

Sets the text size.

textTracking([tracking])

Sets the text tracking.

typo(item, property, [value])

Sets text properties.

Typography#Constants

LOREM

A Lorem ipsum string.

Typography#Styles

applyCharacterStyle(text, style)

Applies a character style to text.

applyParagraphStyle(text, style)

Applies a paragraph style to text.

characterStyle(textOrName, [props])

Gets a text’s character style or gets a character style by name.

paragraphStyle(textOrName, [props])

Gets a text’s paragraph style or gets a paragraph style by name.