cta

The cta module is used to access Chinese Text Analyser functionality from within your Lua scripts. You can include it your scripts as follows:

local cta = require 'cta'

The following functions are available:

cta.askUserForDirectory()
cta.askUserForDirectory( title )

Displays a dialog box asking the user to choose a directory on their file system. If title is specified then the title bar of the dialog box will contain that text.

This function returns a single result:

  • directory (string) - If the user selected a directory then this will be the full path to the directory that the user specified. Returns nil if the user cancelled.

Example

1
2
3
4
5
6
7
local cta = require 'cta'
local directory = cta.askUserForDirectory()
if directory ~= nil then
    print( 'The user chose: ' .. directory )
else
    print( "The user didn't chose a directory" )
end

cta.askUserForFileToOpen()
cta.askUserForFileToOpen( options )

Displays a dialog box asking the user to choose a file (or files) on their file system to open.

If specified, options is a table that can have the following values:

  • allowMultiple (boolean) - whether or not to allow the user to select multiple files. Defaults to false.
  • title (string) - Text to display in the title bar of the dialog box. If not specified, the default open file text for your system is used.

This function returns a single result:

  • file (string|table) - If the user cancels, the result will be nil. Otherwise the value depends on the allowMultiple option.

    When false, then the result will be a string containing the full path of the selected file.

    When true, then the result will be an indexed table of strings containing the full path of each selected file.

Note

This function doesn’t open the file itself. It only returns the name of the file or files that the user selected. If you want to process the files, you’ll still need to open them yourself, e.g. using cta.Document( filename ).

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
local cta = require 'cta'

-- getting a single file
local file = cta.askUserForFileToOpen()
if file ~= nil then
    print( 'The user chose: ' .. file )
else
    print( "The user didn't chose a file" )
end

-- getting multiple files
local files = cta.askUserForFileToOpen( { allowMultiple = true } )
if files ~= nil then
    print( 'The user chose the following files:' )
    for i, file in ipairs( files ) do
        print( '', i .. ': ' .. file )
    end
else
    print( "The user didn't choose any files" )
end

cta.askUserForFileToSave()
cta.askUserForFileToSave( title )

Displays a dialog box asking the user to specify the name of a file to save to.

If title is specified then the title bar of the dialog box will contain that text.

This function returns a single result:

  • file (string) - If the user selected a file then this will be the full path of the file that the user specified. Returns nil if the user cancels.

Note

This function doesn’t save the file itself. It only returns the name of a file or files that the user wishes to save. What you do with that is then up to you.

Example

1
2
3
4
5
6
7
local cta = require 'cta'
local file = cta.askUserForFileToSave()
if file ~= nil then
    print( 'The user chose: ' .. file )
else
    print( "The user didn't specify a file" )
end

cta.dictionary()

Returns a Dictionary object that can be used to query word definitions.

Example

1
2
local cta = require 'cta'
local dictionary = cta.dictionary()

See Dictionary for more information.

cta.Document( filename, options )

Creates a new Document for processing.

Example

1
2
local cta = require 'cta'
local document = cta.Document( 'file.txt' )

See Document for more details.

cta.hskLevel( level )
cta.hskLevel( lowerLevel, upperLevel )

Returns a WordList object containing all words from a specific HSK level, or range of HSK Levels.

Takes as a parameter either a single level, or a lower and an upper level. The level must be an integer in the range 1-6 otherwise an error will occur.

Example

1
2
3
local cta = require 'cta'
local level4 = cta.hskLevel( 4 )
local levels1_6 = cta.hskLevel( 1, 6 )

cta.tocflLevel( level )
cta.tocflLevel( lowerLevel, upperLevel )

Returns a WordList object containing all words from a specific TOCFL level, or range of TOCFL Levels.

Takes as a parameter either a single level, or a lower and an upper level. The level must be an integer in the range 1-5 otherwise an error will occur.

Example

1
2
3
local cta = require 'cta'
local level4 = cta.tocflLevel( 4 )
local levels1_5 = cta.tocflLevel( 1, 5 )

cta.knownWords()

Returns a WordList object containing all of the user’s currently known vocabulary.

Example

1
2
local cta = require 'cta'
local knownWords = cta.knownWords()

cta.lookedUpWords()

Returns a WordList object containing all the words the user has looked up in the current session of Chinese Text Analyser.

Example

1
2
 local cta = require 'cta'
 local lookedUp = cta.lookedUpWords()

cta.openDocuments()

Returns an array containing all the documents currently open in Chinese Text Analyser. Each element of the array is a Document object.

Example

1
2
3
4
5
6
local cta = require 'cta'
local open = cta.openDocuments()

for _, document in ipairs( open ) do
    ...
end

cta.Text( text )

Creates a new Text object.

Example

1
2
local cta = require 'cta'
local text = cta.Text( '洪钧感觉自己所有的内脏器官好像都坠了下去' )

See Text for more information.

cta.WordList()
cta.WordList( filename )

Creates a new WordList object.

Example

1
2
local cta = require 'cta'
local wordList = cta.WordList( 'words.txt' )

See WordList for more information.

cta.write()

Similar to print(), except it does not append a newline to the end of the output.

This is useful when you want to build a full line of text from multiple calls to write.

Example

1
2
3
4
5
6
7
local cta = require 'cta'

local values = { 'one', 'two', 'three' }
for _, value in ipairs( values ) do
    cta.write( value .. ' -> ' )
end
cta.write( '\n' )

Output

one -> two -> three ->