Vocabulary/Foreigns

From J Wiki
Jump to: navigation, search
Back to: Vocabulary Thru to: Dictionary m!:n Foreigns at a glance Q=query, S=set
m n
0 1 2 3 4 5 6 7 8 9
0

Scripts

  Load

+1=display +10=continue +100=noun only

Assert Test Assert
1

Files

  Dir Read Write Append Size Mkdir Attrs Permits
1 Indx Read Indx Write
2 File #s Open Close
3 Locks Lock Unlock
4 Q CWD S CWD Q DLL
5 Erase
2

Host

  Execute Host Cmd Spawn Host I/O Wait Getenv GetPID
5 Exit
3

Convert

  Precision To Byte Rep From Bin/Hex To Hex Rep Integer Conv Floating Conv Lock Script
4

Names

  Part Of Speech Name List Scripts Which Script Names Chgd
5 Erase Name
5

Rep

  Create From AR AR Boxed Tree Linear Paren Explicit
6

Time

  Current Session Execute Delay Parser Calls Q Clk Freq Q Clk Ctr
1 Perf Monitor
7

Space

  Space In Use Execute Free Blocks Obj Space Locale Space
8

Format

  Format Atoms Format Columns Format Table
9

Globals
Even=Q
Odd=S

  RNG Initial State Default Displays Boxing Chars Error Msgs
1 Formatted-Numeric Precision OS Type J Ver Box Disp Pos Comp Toler
2 Mem Limit Secure Level Immex Sentence Immex Flag
3 Exec Time Limit Enable assert. Output Control Locale Hash Sizes
4 Retain Comments RNG Select RNG State Break filename Enable x. & y.
5 Allow assignment of intermediate results to zombies
13

Debug

  Enable Debugger Controls Signal Error Debugger Control
1 Last Error # Last Error Msg Show Stack Q/S Latent Exp Q Enable Text Stack Debugger Controls
2 Debugger Controls
15

DLL

  cd memr memw mema memfree
18

Locales

  Classify Name List Locales Q/S Path Create S Implied Q Implied
5 Erase
128

Misc

  QR Invert R Apply CRC RNG Raw Is NaN

m=0 (Scripts)
y is either a boxed filename or the unboxed text of a script. If y is a boxed filename, the file is read and the contents used as the script. Some variants require y to be unboxed.
Action n y Description
Load 0 boxed filename Stop on error; do not display each line
1 Stop on error; display each line
10 Continue on error; do not display each line
11 Continue on error; display each line
100 unboxed string, containing lines to execute separated by LF Stop on error; display each line
101 Continue on error; do not display each line
110 Continue on error; display each line
111 Continue on error; display each line
Assert 2 Load script, treating each non-assignment line as an assert. control. Display each line and the result of its execution, but stop, raising assertion error, if the result of any non-assignment line is a noun that contains an atom that is not 1.
Test Assertions 3 Load the file, checking assertions as in 0!:2, but produce a result of 0 if an assertion failed, 1 if they all succeeded.

m=1 (Files)
Action x

(if any)

n y Rank Result
Dir 0 file-search-string (optionally boxed) _ Table, where each row is

name-within-directory;timestamp of last change;size;permissions;attributes
   1!:0 'j.exe'
+-----+------------------+------+---+------+
|j.exe|2008 2 23 11 17 36|696320|rwx|-----a|
+-----+------------------+------+---+------+
Search starts in current working directory

Read 1 boxed filename, or unboxed file number. y=1 means read from the keyboard, y=3 means read from stdin. 0 The contents of the file, as a list of bytes. If y is a boxed filename, the file is opened, read, and closed. If y is a file number of an open file, the file is read but not closed. Reading from keyboard not allowed while script is loading.
Write<<Anchor(m1n2)>> a list of bytes 2 boxed filename, or unboxed file number. y=2 means write to screen, y=4 to stdout, y=5 to stderr. _ 0 x is written to the file y, replacing the previous contents if the file existed. If the file is specified by number, the file number remains open, pointing to the newly written file. Result of the verb is (i. 0 0), except when (y e. 2 4 5), in which case it is x.
Append a list of bytes 3 boxed filename, or unboxed file number. y=2 means write to screen. _ 0 Like 1!:2, but x is appended to the file instead of replacing it.
Size 4 boxed filename, or unboxed file number 0 The number of bytes in the file; error if file does not exist.
Mkdir 5 boxed directory name 0 The directory is created. Result is 1. Error if directory exists.
Query Attributes 6 boxed filename, or unboxed file number 0 A string of bytes, giving the system-dependent attributes. Each attribute is either present or absent. Presence is indicated by an assigned letter, and absence by a dash (-). The assigned letters for Windows are: read-only (r), hidden (h), system (s), directory (d), archivable (a), volume-label (v)
Set Attributes A list of bytes, containing only assigned attribute letters and - boxed filename, or unboxed file number 1 0 Result is 1 if there is no error. Each attribute is set if its assigned letter appears in x an odd number of times, cleared otherwise
Query Permissions 7 boxed filename, or unboxed file number 0 A string of bytes, giving the system-dependent permissions. Each permission is either present or absent. Presence is indicated by an assigned letter, and absence by a dash (-). The assigned letters for Windows are: readable (r), writable (w), executable (x)
Set Permissions A list of bytes, containing only assigned permission letters and - boxed filename, or unboxed file number 1 0 Result is 1 if there is no error. Each permission is set if its assigned letter appears in x an odd number of times, cleared otherwise
Indexed Read 11 file;start[,length]

file is filename or file number. start is starting offset, length is number of bytes to read.

1 The bytes read from the file. start may be negative to count back from the end of the file. If length is omitted, the read goes to the end.
Indexed Write a list of bytes 12 file;start

file is filename or file number. start is starting offset.

_ 1 x is written to the file file starting at byte offset start, replacing the previous contents if the file existed. start may be negative to count back from the end of the file. The length of the write is (#x). Result of the verb is (i. 0 0).
Open Files 20 '' _ A table where each row contains

filenumber;filename
representing one file opened by 1!:21

Open<<Anchor(m1n21)>> 21 boxed filename, or unboxed file number 0 The file is opened. The result is a file number: an integer that can be used to refer to the file. Repeated accesses to a file are faster using file numbers.
Close<<Anchor(m1n22)>> 22 boxed filename, or unboxed file number 0 The file is closed and any locks released. The result is 1.
Locks 30 '' _ A table where each row contains

filenumber,start,length
representing one lock established by 1!:21

Lock File Region<<Anchor(m1n21)>> 31 filenumber,start,length

filenumber is a file number from 1!:21

1 The region is locked. Result is 1 if lock was granted, 0 if not.
Unlock File Region<<Anchor(m1n22)>> 32 filenumber,start,length

filenumber is a file number from 1!:21

1 The lock is released. The result is 1.
Query CWD<<Anchor(m1n43)>> 43 '' _ The current working directory, a list of bytes.
Set CWD 44 The new working directory, a list of bytes _ Result is 0$0.
Query DLL 46 '' _ The path to j.dll, a list of bytes. '' in Unix.
Erase File/Directory 55 boxed filename, or unboxed file number 0 The file or directory is erased. Error if file does not exist. Result is 1.

m=2 (Host)
Action n y Rank Result
Execute Host Command 0 A character list 1 The list y is passed to the Host for execution. J waits for the command to finish, and the result from the host becomes the result of 2!:1. Not available in Windows.
Spawn 1 A character list 1 Like 2!:0, but does not wait for completion. Result is ''. Unix only.
Host I/O 2 1 First, two files are opened, appearing in the list returned by 1!:20 as

filenumber;'<',y
and
filenumber;'>',y
Then, y is passed to /bin/sh with the two files connected to stdin and stdout. The files should be closed using 1!:22 when no longer needed. Unix only.

Wait 3 An integer 0 Wait for process id y to terminate, and return its status code as the result of 2!:3. Unix only.
Getenv 5 A byte list 1 Return the value of the environment variable y, or Boolean 0 if not defined.
GetPid 6 '' 1 The process ID of the J process.
Exit 55 integer _ No result - the J session terminates with return code y.

m=3 (Conversions)
Action x n y Rank Result
Type/Precision 0 any noun _ A value indicating the type and precision of y.
Byte Representation [an atom, one of 0 1 2 3] 1 any noun _ A list of bytes, giving the internal representation of the noun y. If x is given, the sentence

'longlong littleendian' =. 2 2 #: x
would set two names indicating word length (64 or 32 bits) and byte order. If x is omitted, the machine default is used (the PC is littleendian).

Hex Representation [an atom, one of 0 1 2 3] 3 any noun _ Like 3!:1, but the result is a table, where each word of the result of 3!:1 (represented by 4 or 8 bytes) becomes one row, with each byte expressed as 2 displayable hexadecimal digits.
Convert From Byte Or Hex Representation 2 The list or table resulting from 3!:1 or 3!:3 _ The noun represented by y
Convert To J Integers _3 4 A list of bytes _ _ An integer list, each set of 8 bytes of y construed as a 64-bit integer (supported only in 64-bit versions of J)
_2 A list of integers, each set of 4 bytes of y construed as a signed 32-bit integer
_1 A list of integers, each set of 2 bytes of y construed as a signed 16-bit integer
0 A list of integers, each set of 2 bytes of y construed as an unsigned 16-bit integer
Convert From J Integers 1 A numeric atom or list, with atoms tolerantly equal to integers representable in a machine word A list of bytes, 2 bytes per atom of y. Any higher significance is lost.
2 A list of bytes, 4 bytes per atom of y. Any higher significance is lost.
3 A list of bytes, 8 bytes per atom of y (supported only in 64-bit versions of J)
Convert To J Floating-Point _2 5 A list of bytes _ _ A floating-point list, each set of 8 bytes of y construed as a 64-bit IEEE-754 floating-point value
_1 A floating-point list, each set of 4 bytes of y construed as a 32-bit IEEE-754 floating-point value
Convert From J Floating-Point 1 A numeric atom or list, in the range of a 64-bit IEEE floating-point value A list of bytes, 4 bytes per atom of y. Numbers too large or small for 32-bit representation are converted to infinity or zero.
2 A list of bytes, 8 bytes per atom of y.
Lock Script 6 a list of bytes, containing the text of a script _ A list of encrypted bytes, the same shape as y, that can be loaded using load or 0!:n

m=4 (Names)
Action x n y Rank Result
Part Of Speech 0 boxed list of characters 0 The part of speech assigned to the name, if any

If the value of the objname[s] in an object locative are improper, an error is raised.
If the name contains a locative that refers to a numeric locale that has been erased, a locale error is raised.

Defined Names [characters] 1 numeric where each atom is a part of speech number, or 6 meaning "locale" 0 The atoms of y indicate what names are requested. If 6 is among them, the names of all defined locales will be returned. The presence of values 0-3 requests the corresponding parts of speech from the names currently defined, either in the active private namespace or in the implied locale. If x is given, only names beginning with a letter in x will be returned. To execute 4!:1 is a specified locale l, assign 4!:1 to a name, say nlist, and execute nlist_l_
Script Names 3 '' _ The list of boxed filenames that have been invoked using 0!:n
Which Script 4 boxed name 0 The index in (4!:3 '') of the script that loaded the name y, or _1 if not from a script
Names Changed 5 0 or 1 0 4!:5 (0) turns off data collection; 4!:5 (1) turns it on and produces a list of global names assigned since the last execution of 4!:5 .
Erase Name 55 boxed name 0 Erases the name in y and frees its storage. The result is 1.

m=5 (Representation)
Action x n y Rank Result
Define From AR (adverb) an atomic representation 0 The entity defined by the AR, which may have any part of speech
Create AR 1 boxed name 0 The atomic representation (AR) of the name in y
Boxed Display 2 boxed name 0 A list of boxes describing the value of the name
Tree Display 4 A character table describing the value of the name
Linear Display 5 A character list that, when executed, creates the value of the name
Parenthesized Display 6 Like 5!:5, but fully parenthesized
Parsed Explicit Definition 1 or 2 7 boxed name 0 0 A table describing the valence given in x of the explicit entity named in y

m=6 (Time)
Action x n y Rank Result
Get Current Time 0 character list, or empty list _ If y is empty, result is a 6-atom numeric list containing year,month,day,hour,minute,second. If y is a nonempty character list, result is a copy of y, with occurrences of the characters 'Y', 'M', 'D', 'h', 'm', and 's' are replaced by digits of the time, up to a maximum of 4, 2, 2, 2, 2, and 5 replacements respectively.
Session Time 1 '' _ Number of seconds since J started running.
Time Sentence [repetitions] 2 sentence, a list of characters 0 1 Time, averaged over repetitions attempts (default 1), to execute sentence.
Delay 3 number of seconds 0 Delay for y seconds.
Count Parser Calls 4 '' _ Number of times parser has been called since J started running. This is a machine integer and may overflow.
Query Clock Frequency 8 '' _ Used by Performance Monitor (PM)
Query Clock Counter 9
PM Data Area [control info] 10
Unpack PM Data 11
Add to PM Counter 12
PM Statistics 13

m=7 (Space)
Action n y Rank Result
Space In Use 0 '' _ The number of bytes currently in use.
Measure Sentence 2 a list of characters _ The number of bytes used to execute the sentence x.
Free Blocks 3 '' _ A table of the free blocks being managed by J's internal memory manager. Each row contains

blocksize,count

Space For Object 5 boxed name 0 Number of bytes used by the definition of the name in y
Space For Locale 6 boxed name 0 Number of bytes used by the locale in y

m=8 (Format)
Action x n y Rank Result
Format Atoms The formatting string, a list of bytes 0 A numeric or character noun _ _ Each atom of y is converted to a boxed character list as specified by x.
Format Columns 1 A numeric or character atom, list, or table Each column of y is converted to a boxed character table as specified by the corresponding formatting phrase in x.
Format Table 2 Like 8!:1, but the columns are joined to create a single character table

m=9 (Globals)
All ranks are infinite. Values of n come in pairs: n is an even number to query a global value, odd to set the value. y should be an empty list for query (normally ''), and should have a valid value to set. The valid values are described in the table below.
Action n

(Q)

n

(S)

Description of value Remarks
RNG Initial State 0 1 An integer, or (for the Mersenne Twister RNG) a list of integers 9!:1 puts the selected RNG into an initial state that depends entirely on y
Default Displays 2 3 An integer list with numbers selected from 1 2 4 5 6 with no duplicates Non-noun results will be displayed in each format 5!:a where a is an atom in x
Boxing Characters 6 7 A list of 11 characters The characters will be used for displaying boxed nouns.
Error Messages 8 9 A list of 33 boxed character lists The error messages
Print Precision 10 11 A numeric atom tolerantly equal to an integer Default precision used for display of numerics
OS Type 12 An integer atom System type: UNIX (5), Windows (6), Windows CE (7), or _1 if other
J Version 14 A character list Example: j602/2008-03-03/16:45
Boxed Display Positioning 16 17 A numeric atom or list, maximum length 2, each atom tolerantly one of 0 1 2 2$y is the value used for centering the contents of boxes.
Comparison Tolerance 18 19 A value between 0 and 2^_44 The default comparison tolerance
Memory Limit 20 21 A numeric value tolerantly equal to an integer The maximum size of a single memory allocation (initialized to 1/4 of the virtual address space)
Security Level 24 25 0 or 1 When set to 1, operations that affect the environment are disallowed
Immex Sentence 26 27 A character list, containing a J sentence The sentence is executed as controlled by the Immex Flag (9!:29)
Immex Flag 28 29 0 or 1 J is in immediate execution mode when it is waiting for keyboard input. It enters immediate execution mode when a top-level sentence completes execution. Possible sources of a top-level sentence are:
  • the initialization of J including the starting script
  • a sentence typed from the keyboard
  • a sentence executed by an event handler

If the immex flag (set by 9!:29) is 1 when J enters immediate execution mode, the immex flag is cleared and then the immex sentence (set by 9!:27) is executed. The normal use for the immex flag is in events handlers, to provide an error handler or simulated user continuation. To provide an error handler, you set the immex flag to 1 on entry to the event, and clear it to 0 at normal exit. If the event handler fails with an error, the immex sentence will be executed. For user continuation, you set the immex sentence and flag just before your handler exits. The immex sentence will be the first thing executed. This allows you to execute the sentence in the user's locale rather than the locale of the event handler; and also to remove the event handler from the execution stack before the immex sentence executes.

Execution Time Limit 32 33 A numeric atom If the value of the time limit is nonzero, it is decremented to account approximately for execution time, and if it decremented to 0, time limit error is signaled.
Enable assert. 34 35 0 or 1 If 0, assert. sentences are ignored. Default is 1.
Output Control 36 37 A numeric list of length 4, tolerantly equal to integers The values control the display of results:

atom 0: 0 to end lines with LF, 2 for CRLF
atom 1: maximum line length; characters beyond this length are replaced with ...
atoms 2-3: the values of b and a. Only the first b and the last a lines of a long result are displayed, with the intervening lines replaced by ...

Default is 0 256 0 222

Locale Hash-Table Sizes<<Anchor(DefaultLocaleHash)>> 38 39 A numeric list of length 2, tolerantly equal to integers The number of hashtable entries for named and numbered locales respectively is (_17 + 2 ^ 6 + y). Any value will produce correct results, but it is a good idea for the hashtable to have at least 30% more entries than the number of defined names.
Retain Comments and Whitespace 40 41 0 or 1 When 0, comments and surplus whitespace are discarded from the saved form of explicit definitions, to save space. Default is 1.
RNG Select 42 43 A numeric atom, tolerantly one of 0 1 2 3 4 Selects a random-number generator
RNG State 44 45 An opaque internal value Saves/Restores the state of the random-number generator
Break file 46 47 A character list, giving the break filename The break filename is the file that is used to break in to a long-running computation. Once set it cannot be modified.
Allow x. and y. 48 49 0 or 1 Set to 1 to recognize and define the old-fashioned names x. etc for arguments. Deprecated. Default is 0.
Allow intermediate results to be stored in a zombie name 52 53 0, 1, or 2 0=Do not allow; 1=allow complete results only; 2 (default)=allow incomplete results.

m=13 (Debug)
All ranks are infinite.
Action x

(if any)

n y Result
Enable Debug Suspension 0 0 or 1 Reset the debugging stack and enable (y=1) or disable (y=0) debugging.
Query Debug Suspension 17 '' Boolean result, 1 if debugging enabled
Signal Error [optional character list] 8 a numeric noun whose first atom is tolerantly equal to an integer Error number ({.,y) is raised, with the error text changed to x if given

(default error text is (<:y) { 9!:8 '')
Signaling error number 55 has the same effect as throw.

Last Error Number 11 '' Result is an integer atom, the number of the last error signaled
Last Error Message 12 '' Result is a character list, the text of the last error signaled
Display Stack 1 '' These verbs are for use by the debugger, and are meaningful only when debugging is enabled. Details are in the J Dictionary
Query Stops 2 ''
Set Stops 3 stop info
Run Again 4 ''
Run Next 5 ''
Exit And Return 6 return result
Continue 7 line number
Rerun [x argument] 9 y argument
Stack 13 ''
Query Latent Sentence 14 ''
Set Latent Sentence 15 latent sentence
Stack As Text 18 ''
Cut Stack Back 19 ''
Step Over [line number] 20 ''
Step Into [line number] 21 ''
Step Out [line number] 22 ''

m=15 (DLL)
Action x (if any) n y Rank Result
Call DLL character list identifying the function to be called and describing its arguments 0 arguments to the function 1 1 The DLL is called. Details are given in The User Guide
Allocate Memory 3 A numeric atom, tolerantly equal to an integer _ y bytes are allocated. The result is the memory address of the allocated region, or 0 if the allocation failed.
Free Memory 4 A numeric atom _ The memory region at address y is freed. The result is 0 for success, 1 for failure.
Read Memory 1 An integer list

addr,byteoffset,count[,precision]

_ Result is a list of count sequential atoms of the specified precision, read from the memory address at addr+byteoffset. The precision is restricted to one of 2 4 8 16 (default 2). If precision=2, a count of _1 is allowed and means "read up to but not including the first zero byte"
Write Memory A numeric noun 2 An integer list

addr,byteoffset,count[,precision]

_ _ (,x) is written to sequential atoms, having the specified precision, starting at the memory address at addr+byteoffset. The precision is restricted to one of 2 4 8 16 (default 2). count must equal the number of atoms in (,x), except that if precision=2, count may be one more, to cause a zero byte to be appended. The precision of x must match the precision in y, except that Boolean x is promoted to integer. The result is 0 0$0.
Free DLLs 5 '' _ ?
Get address of locale entry for name 6 A boxed name or an array of boxed names _ ?
Set array as address 7 An integer address _ ?
Allocate header 8 An integer size _ Result is address of allocated header
Free header 9 An integer address _ ?
Get address of data for name 14 A boxed name or an array of boxed names _ ?
Get memory blocks 12 ? _ A 3-column table
Set callback address 13 Number of parameters the callback expects _ ?

m=18 (Locales)
Action x n y Rank Result
Locale Name Class 0 A boxed character list 0 Status of the string in y regarded as a locale name: Illegal (_2), Nonexistent (_1), Named (0), or Numbered (1)
List Locale Names [character noun] 1 An atom or list all of whose atoms are tolerantly 0 or 1 _ _ _ List of locale names, including named and numbered locales according as y contains 0 or 1. If x is given, include only names whose initial letter is an atom of x.
Query/Set Search Path [list of boxed locale names] 2 A boxed locale name 0 1 0 The monad returns the search path of locale y; the dyad sets the search path of y to x and returns a result of 0 0$0
Create Locale [numeric, tolerantly equal to an integer] 3 A boxed locale name, or an empty list _ 0 _ Create a locale, a new numbered one if y is empty, otherwise one named y (in which case the locale must not already contain names). x, if given, overrides the default hash table size. Result is the boxed name of the created locale.
Set Implied Locale 4 A boxed locale name _ Set the implied locale to y after the next completion of a named verb (which might not be the currently-executing verb). Do not use 18!:4 directly! It is designed to be used under a cover name such as cocurrent. The locale is created if it does not exist.
Query Implied Locale 5 '' _ The implied locale, a boxed character list.
Erase Locale 55 A boxed locale name _ The locale y is erased as soon as it finishes execution (that is, all verbs in the locale have completed)

m=128 (Miscellaneous)
Action x n y Rank Result
QR Decomposition 0 A numeric matrix whose columns are linearly independent 2 A list of two boxes, containing Q and R, such that y -: Q +/ . * R. Q has orthogonal columns normalized to unit length. R is upper-triangular. If y has shape m×n, Q is m×n and R is n×n. domain error if y has dependent columns. (Note: the J Dictionary says Q is Hermitian but this is incorrect.)
Invert Upper-Triangular R 1 An upper-triangular square matrix 2 The inverse of R. If R is singular, the result may contain infinities.
Apply x to y A character list 2 Any noun 1 _ The character list x is executed and must produce a verb result. This resulting verb is applied to y to produce the result of 128!:2.
CRC [A 2-element boxed list (p;i) or a numeric list or atom p.] 3 A list of bytes _ _ The 32-bit CRC of y using the polynomial p and initial value i. If i is omitted, _1 is used. The polynomial p, which is given LSB first (known as 'reversed representation' in the literature) may be represented as a Boolean list or an integer. If p is omitted, _306674912 (the standard CRC-32, 0xEDB88320), is used.
RNG Raw 4 A numeric atom, tolerantly equal to an integer _ y numbers from the selected RNG. Used for debugging RNGs.
Is NaN 5 Any noun _ Result has the shape of y, with each value 1 if and only if the corresponding atom of y is a NaN.