Text

FileMaker text type with optional character-level formatting.

Overview#Back to top

FileMaker Text type stores text strings.

Initialization#Back to top

Text()
Text(value[, locale)]
Text(value[, encoding)]
Text(value[, original)]
Arguments
value

The value to set the text to. This can be any other FileMaker type or any of supported Python types, such as str, int, datetime.date, etc.

locale

The locale to use for numeric and temporal values. Setting Text to a number or time basically formats the numeric or time value and the result can vary depending on locale: 123.456 in German locale will be formatted as "123,456". Possible locale codes are defined in the filemaker module:

EMPTY_LOCALE           SYSTEM_LOCALE          RAW_UNICODE_LOCALE
UNICODE_LOCALE         CATALOG_LOCALE         CATALAN_LOCALE
CROATIAN_LOCALE        CZECH_LOCALE           DANISH_LOCALE
DUTCH_LOCALE           ENGLISH_LOCALE         FINNISH_LOCALE
FINNISH_CUSTOM_LOCALE  FRENCH_LOCALE          GERMAN_LOCALE
GERMAN_DICT_LOCALE     GREEK_LOCALE           HUNGARIAN_LOCALE
ICELANDIC_LOCALE       ITALIAN_LOCALE         JAPANESE_LOCALE
NORWEGIAN_LOCALE       POLISH_LOCALE          PORTUGUESE_LOCALE
ROMANIAN_LOCALE        RUSSIAN_LOCALE         SLOVAK_LOCALE
SLOVENIAN_LOCALE       SPANISH_LOCALE         SPANISH_TRAD_LOCALE
SWEDISH_LOCALE         SWEDISH_CUSTOM_LOCALE  TURKISH_LOCALE
UKRAINIAN_LOCALE       CHINESE_PINYIN_LOCALE  CHINESE_STROKE_LOCALE
HEBREW_LOCALE          HINDI_LOCALE           ARABIC_LOCALE
ESTONIAN_LOCALE        LITHUANIAN_LOCALE      LATVIAN_LOCALE
SERBIAN_LOCALE         PERSIAN_LOCALE         BULGARIAN_LOCALE
VIETNAMESE_LOCALE      THAI_LOCALE            GREEK_MIXED_LOCALE
BENGALI_LOCALE         TELUGI_LOCALE          MARATHI_LOCALE
TAMIL_LOCALE           GUJARATI_LOCALE        KANNADA_LOCALE
MALAYALAM_LOCALE       ORIYA_LOCALE           PANJABI_LOCALE
SINHALA_LOCALE         URDU_LOCALE            DIVEHI_LOCALE
THANAA_LOCALE          BURMESE_LOCALE         MYANMAR_LOCALE
SANSKRIT_LOCALE        LAO_LOCALE             KHMER_LOCALE
TIBETAN_LOCALE
encoding

The encoding to use to decode the passed string value. This parameter can only be used if the value is str. Possible encoding codes are defined in the filemaker module:

NATIVE_ENC              UTF8_ENC                ASCII_DOS_ENC
ASCII_WIN_ENC           ASCII_MAC_ENC           ISO_8859_1_ENC
SHIFT_JIS_MAC_ENC       SHIFT_JIS_WIN_ENC       KOREAN_MAC_ENC
KOREAN_WIN_ENC          KOREAN_JOHAB_ENC        CHINESE_TRAD_MAC_ENC
CHINESE_TRAD_WIN_ENC    CHINESE_SIMP_MAC_ENC    CHINESE_SIMP_WIN_ENC
CYRILLIC_MAC_ENC        CYRILLIC_WIN_ENC        ISO_8859_5_ENC
CENTRAL_EUROPE_MAC_ENC  EASTERN_EUROPE_WIN_ENC  ISO_8859_2_ENC
TURKISH_MAC_ENC         TURKISH_WIN_ENC         ISO_8859_3_ENC
ISO_8859_9_ENC          BALTIC_WIN_ENC          ISO_8859_4_ENC
ARABIC_MAC_ENC          ARABIC_WIN_ENC          ISO_8859_6_ENC
GREEK_MAC_ENC           GREEK_WIN_ENC           ISO_8859_7_ENC
HEBREW_MAC_ENC          HEBREW_WIN_ENC          ISO_8859_8_ENC
ISO_8859_15_ENC
original

A boolean value that indicates whether to use the original text value of the passed value. This parameter only works if the value is another FileMaker data type (i.e. Number, Date, Container) and has original text (only read-only instances may have it).

This is the only way to get the value of Containers that only stores a reference to the file. Normally a Container is a collection of streams, including a stream for the file name (FNAM). When you convert Container into Text (i.e. create a new Text and pass the Container instance as a parameter), it normally returns the value of this FNAM stream or, if the stream is not there, raises the MissingDataError (FileMaker error 10).

But a Container that only stores a reference to a file is not really a container. When you get such a container into Python, you'll see that it has no streams at all; the reference is stored simply as text. To get this reference you need to create a new Text instance and pass it the Container instance with the original parameter.

Discussion

Text instances also have the set() method that takes almost the same parameters and allows to completely change the text value once it has been created.

Conversion#Back to top

Text instances can be converted into supported Python types. To convert into text and numeric types use the standard str(), unicode(), bool(), int(), long(), and float() methods. To convert into datetime types use the corresponding Text methods: date(), time(), datetime(), and timedelta(). When converting into non-text types the plug-in uses the current file's locale. (To have more control over the locale create a corresponding filemaker type; this way you can pass the locale as a parameter.)

FileMaker doesn't filter unsafe ASCII characters, so be careful with what you send into it. The plug-in automatically replaces LF with CR but doesn't do any other replacements for now.

Standard protocols#Back to top

In Python Text looks like a modifiable sequence with bits of other standard protocols.

Comparison#Back to top

Text instances can be compared with other Text instances or compatible Python types (str and unicode). Text instances are compared mechanically: A is not equal to a, a is not equal to ä and so on. Text formatting information is ignored.

>>> from filemaker import Text
>>> t = Text('a')
>>> t == 'a'
True
>>> t == 'A'
False
>>> t == u'ä'
False
>>> t < 'b'
True

Length#Back to top

Text instances support the len() function and return the length of text in characters:

>>> from filemaker import Text
>>> t = Text('AbcDef')
>>> len(t)
6

Inclusion#Back to top

Text instances support the in operator to check if they contain the specified substring. The substring can be another Text instance or a compatible Python type (str or unicode):

>>> from filemaker import Text
>>> t = Text('AbcDef')
>>> 'Abc` in t
True

The search is case-sensitive:

>>> from filemaker import Text
>>> t = Text('AbcDef')
>>> 'abc` in t
False

To perform a case-insensitive search use the find() method.

Concatenation#Back to top

Text instances can be concatenated with other Text instances or a compatible Python types (str and unicode):

>>> from filemaker import Text
>>> t = Text('AbcDef')
>>> u = t + 'Ghi'
>>> str(u)
'AbcDefGhi'

If the Text instance is editable (some instances are read-only), it can be concatenated in-place:

>>> from filemaker import Text
>>> t = Text('AbcDef')
>>> t += 'Ghi'
>>> str(t)
'AbcDefGhi'

Multiplication#Back to top

Text instances can be ‘multiplied’ by an integer to repeat their contents the specified number of times:

>>> from filemaker import Text
>>> t = Text('Abc')
>>> u = t * 3
>>> str(u)
'AbcAbcAbc'

If the Text instance is editable (some instances are read-only), it can be multiplied in-place:

>>> from filemaker import Text
>>> t = Text('Abc')
>>> t *= 3
>>> str(t)
'AbcAbcAbc'

Subscription or index access#Back to top

Text instances can return individual characters or slices by their index:

>>> from filemaker import Text
>>> t = Text('AbcDef')
>>> str(t[3])
'D'

If the Text instance is editable (some instances are read-only), you can also modify or delete text this way:

>>> from filemaker import Text
>>> t = Text('AbcDef')
>>> t[3] = 'G'
>>> str(t)
'AbcGef'
>>> del t[3]
>>> str(t)
'Abcef'

The replacement string doesn't have to be a single-character string:

>>> from filemaker import Text
>>> t = Text('AbcDef')
>>> t[3] = 'Xyz'
>>> str(t)
'AbcXyzef'

Text also supports slice access:

>>> from filemaker import Text
>>> t = Text('AbcDef')
>>> str(t[0:3])
'Abc'
>>> t[0:3] = 'Ghi'
>>> str(t)
'GhiDef'
>>> t[3:3] = 'Xyz'
>>> str(t)
'GhiXyzDef'
>>> del t[3:6]
>>> str(t)
'GhiDef'

Methods by category#Back to top

Generic PyFM methods#Back to top

set()

Change the text value.

readonly()

Check if this instance is read-only.

Specific text methods#Back to top

find()

Find a substring in the text.

lower()

Convert text into lowercase.

upper()

Convert text into uppercase.

Methods to convert into datetime type#Back to top

date()

Convert text into datetime.date

time()

Convert text into datetime.date

datetime()

Convert text into datetime.date

timedelta()

Convert text into datetime.date

Text formatting methods#Back to top

get_style()

Get text style.

add_style()

Apply text style.

del_style()

Unapply text style.

Methods reference#Back to top

add_style()#Back to top

Apply a formatting style to the text or a part of it. Usage:

add_style(style[, position, length])
Arguments
style

Must be an instance of filemaker.Style.

position

Starting position; by default 0.

length

Length of text to add the style to; if omitted, the style will be added till the end of the text.

Result and side effects

The method adds the specified style to the text or to the specified part of the text. The method may raise the plugin.ReadOnlyError if the instance is read-only. The method returns no result.

Discussion

A style is a collection of formatting attributes, such as font, size, color, bold, italic, etc. Adding a style applies these attributes to text. Note that each style attribute can also be individually enabled or disabled. If all attributes are enabled, then the style is opaque and will change each text attribute. But if some parameters are disabled, the style becomes partially transparent; adding it to text only changes enabled parameters. for more information about styles see modules-filemaker-style.

date()#Back to top

Parse the text as a time value and return the result as an instance of the datetime.date type. Usage:

date()
Arguments

The method takes no arguments.

Result and side effects

The method returns an instance of the datetime.date type whose value matches the text. If the text cannot be parsed as date, the method raises the ValueError exception. The method has no side effects.

Discussion

The method interprets the text according to the file locale. To have more control over the locale use an intermediate instance of Date:

>>> from filemaker import Text, Date, GERMAN_LOCALE
>>> t = Text('1.2.2009')
>>> t.date()
datetime.date(2009, 1, 2)
>>> Date(t, GERMAN_LOCALE).date()
datetime.date(2009, 2, 1)

FileMaker parser is simplistic and will happily produce invalid results. If you need to deal with parsing and locales consider using a third-party module.

datetime()#Back to top

Parse the text as a time value and return the result as an instance of the datetime.datetime type. Usage:

datetime()
Arguments

The method takes no arguments.

Result and side effects

The method returns an instance of the datetime.datetime type whose value matches the text. If the text cannot be parsed as timestamp, the method raises the ValueError exception. The method has no side effects.

Discussion

The method interprets the text according to the file locale. To have more control over the locale use an intermediate instance of Timestamp:

>>> from filemaker import Text, Timestamp, GERMAN_LOCALE
>>> t = Text('1.2.2009 12:34:56,789')
>>> t.datetime()
datetime.datetime(2009, 1, 2, 0, 0)
>>> Timestamp(t, GERMAN_LOCALE).datetime()
datetime.datetime(2009, 2, 1, 12, 34, 56, 789000)

FileMaker parser is simplistic and will happily produce invalid results. If you need to deal with parsing and locales consider using a third-party module.

del_style()#Back to top

Unapply all styles or the specified style. Usage:

del_style([style])
Parameters
style

The style parameter must be an instance of the Style type. If no style is specified, the method will delete all style information.

Result and side effects

The method deletes all style information or unapplies the specified style. If the style is specified, it is unapplied only if the style's values match the text formatting. The method may raise the plugin.ReadOnlyError if the instance is read-only. The method returns no result.

Discussion

Unapplying a style disables the affected attributes. A disabled attribute simply takes whatever value is assigned to it on the layout. For example, if the field is formatted as bold, the text in this field will also show as bold. But if the text's bold attribute is enabled, this text will always show its own value. If the attribute is set to True, the text will always be bold and if it's False, the text always be non-bold regardless of the field's settings.

A Style is a collection of formatting attributes, each of which can also be enabled or disabled. With styles, however, this has a different meaning: if an attribute is enabled, then it affects the text when the style is applied or unapplied; if the attribute is disabled, it is completely ignored.

Unapplying a style takes the style, checks which attributes are active, and then compares their values with text attributes. If the value matches, then the attribute is disabled, else it stays.

For example, let's make a text instance with three different settings for bold:

>>> from filemaker import Text, Style
>>> t = Text('abc')
>>> s1 = Style(bold=True)
>>> s2 = Style(bold=False)
>>> t.add_style(s1, 0, 1)
>>> t.add_style(s2, 1, 1)

Here we've created a text value and formatted the first character as bold and the second as non-bold. These values will stay regardless of field formatting; if the field is bold, the second character will show up as non-bold, if the field is plain, the first character will show up as bold. The third character will have the same format as the field.

Now let's remove these styles. Note that we cannot remove a style from a part of the text, only from the whole text at once:

>>> t.del_style(s2)

The s2 instance has the bold set to False. Unapplying the style checks the bold attribute of each character and if it is also False, disables it. We can verify that by probing the style of the second character:

>>> t.get_style(1).bold is None
True

The first character, however, stays unaffected. It also has the bold attribute enabled, but here the value is True, which does not match the style being unapplied. As a result this style stays put:

>>> t.get_style(0).bold is True
True

If you want to remove some attributes regardless of their values, simply apply the style first and then remove it. When you apply it, all enabled attributes of the style will be copied to text as they are, so when you unapply them later, they will match in all cases. I.e. in our case to remove the bold attribute regardless of whether it's True or False we need to do that:

>>> t.add_style(s2) # s1 would also do
>>> t.del_style(s2)

find()#Back to top

Return position of a substring in the text or -1 if there's no such substring. Usage:

find(text[, start=0, backward=False, case=False])
Arguments
text

Text to find.

start

Starting index, by default 0.

backward

Whether to search backward, by default False.

case

Whether to consider case when searching, by default False.

Result and side effects

The method searches the specified text in the string and returns the index of the first occurrence or -1 if the text is not there. Indices start with 0. The method may raise errors like TypeError if the parameters are not what it expects. The method has no side effects.

lower()#Back to top

Replace all uppercase characters with their lowercase equivalents. Usage:

lower()
Arguments

The method takes no arguments.

Result and side effects

The method replaces all uppercase characters in the text with their lowercase equivalents.The method returns no result. If the instance is read-only, the method will raise the plugin.ReadonlyError exception.

Discussion

Note that this method modifies the data and in general case there's no easy way to go back to the original version. A non-destructive way to make the text appear lowercase while retaining the original information about the case is to create a Style with the lowercase attribute and apply it to the text.

readonly()#Back to top

Check if this instance is read-only or not. Usage:

readonly()
Parameters

The method takes no parameters.

Result and side effects.

The method returns True if this instance is read-only, otherwise False. The method has no side effects.

get_style()#Back to top

Probe a style at the specified position or get the default style. Usage:

get_style(position)
Arguments
position

The position to probe a style at, starting with 0.

Results and side effects

An instance of Style that has the same values and state as the text at this position. The method has no side effects.

Discussion

You can only probe styles one character at a time, because two or more characters can have different styles.

set()#Back to top

Change the text's value. Usage:

set(value[, locale)]
set(value[, encoding)]
set(value[, original)]
Arguments
value

The value to set the text to. This can be any other FileMaker type or any of supported Python types, such as str, int, datetime.date, etc.

locale

The locale to use for numeric and temporal values. Setting Text to a number or time basically writes the numeric or time value and the result can vary depending on locale: 123.456 in German locale should be "123,456". Possible locale codes are defined in the filemaker module:

EMPTY_LOCALE           SYSTEM_LOCALE          RAW_UNICODE_LOCALE
UNICODE_LOCALE         CATALOG_LOCALE         CATALAN_LOCALE
CROATIAN_LOCALE        CZECH_LOCALE           DANISH_LOCALE
DUTCH_LOCALE           ENGLISH_LOCALE         FINNISH_LOCALE
FINNISH_CUSTOM_LOCALE  FRENCH_LOCALE          GERMAN_LOCALE
GERMAN_DICT_LOCALE     GREEK_LOCALE           HUNGARIAN_LOCALE
ICELANDIC_LOCALE       ITALIAN_LOCALE         JAPANESE_LOCALE
NORWEGIAN_LOCALE       POLISH_LOCALE          PORTUGUESE_LOCALE
ROMANIAN_LOCALE        RUSSIAN_LOCALE         SLOVAK_LOCALE
SLOVENIAN_LOCALE       SPANISH_LOCALE         SPANISH_TRAD_LOCALE
SWEDISH_LOCALE         SWEDISH_CUSTOM_LOCALE  TURKISH_LOCALE
UKRAINIAN_LOCALE       CHINESE_PINYIN_LOCALE  CHINESE_STROKE_LOCALE
HEBREW_LOCALE          HINDI_LOCALE           ARABIC_LOCALE
ESTONIAN_LOCALE        LITHUANIAN_LOCALE      LATVIAN_LOCALE
SERBIAN_LOCALE         PERSIAN_LOCALE         BULGARIAN_LOCALE
VIETNAMESE_LOCALE      THAI_LOCALE            GREEK_MIXED_LOCALE
BENGALI_LOCALE         TELUGI_LOCALE          MARATHI_LOCALE
TAMIL_LOCALE           GUJARATI_LOCALE        KANNADA_LOCALE
MALAYALAM_LOCALE       ORIYA_LOCALE           PANJABI_LOCALE
SINHALA_LOCALE         URDU_LOCALE            DIVEHI_LOCALE
THANAA_LOCALE          BURMESE_LOCALE         MYANMAR_LOCALE
SANSKRIT_LOCALE        LAO_LOCALE             KHMER_LOCALE
TIBETAN_LOCALE
encoding

The encoding to use to decode the passed string value. This parameter can only be used if the value is str. Possible encoding codes are defined in the filemaker module:

NATIVE_ENC              UTF8_ENC                ASCII_DOS_ENC
ASCII_WIN_ENC           ASCII_MAC_ENC           ISO_8859_1_ENC
SHIFT_JIS_MAC_ENC       SHIFT_JIS_WIN_ENC       KOREAN_MAC_ENC
KOREAN_WIN_ENC          KOREAN_JOHAB_ENC        CHINESE_TRAD_MAC_ENC
CHINESE_TRAD_WIN_ENC    CHINESE_SIMP_MAC_ENC    CHINESE_SIMP_WIN_ENC
CYRILLIC_MAC_ENC        CYRILLIC_WIN_ENC        ISO_8859_5_ENC
CENTRAL_EUROPE_MAC_ENC  EASTERN_EUROPE_WIN_ENC  ISO_8859_2_ENC
TURKISH_MAC_ENC         TURKISH_WIN_ENC         ISO_8859_3_ENC
ISO_8859_9_ENC          BALTIC_WIN_ENC          ISO_8859_4_ENC
ARABIC_MAC_ENC          ARABIC_WIN_ENC          ISO_8859_6_ENC
GREEK_MAC_ENC           GREEK_WIN_ENC           ISO_8859_7_ENC
HEBREW_MAC_ENC          HEBREW_WIN_ENC          ISO_8859_8_ENC
ISO_8859_15_ENC
original

A boolean value that indicates whether to use the original text value of the passed value. This parameter only works if the value is another FileMaker data type (i.e. Number, Date, Container) and has original text (only read-only instances may have it).

Result and side effects

The method replaces the text with the passed value. The method has no side effects.

Discussion

The method is same as initialization, except that you must pass at least one parameter.

time()#Back to top

Parse the text as a time value and return the result as an instance of the datetime.time type. Usage:

time()
Arguments

The method takes no arguments.

Result and side effects

The method returns an instance of the datetime.time type whose value matches the text. If the text cannot be parsed as time, the method raises the ValueError exception. The method has no side effects.

Discussion

The method interprets the text according to the file locale. To have more control over the locale use an intermediate instance of Time:

>>> from filemaker import Text, Time, GERMAN_LOCALE
>>> t = Text('12:34:56,789')
>>> t.time()
Traceback (most recent call last):
    ...
ValueError: The passed text value does not make valid time.
>>> Time(t, GERMAN_LOCALE).time()
datetime.time(12, 34, 56, 789000)

FileMaker parser is simplistic and will happily produce invalid results. If you need to deal with parsing and locales consider using a third-party module.

timedelta()#Back to top

Parse the text as a time value and return the result as an instance of the datetime.timedelta type. Usage:

timedelta()
Arguments

The method takes no arguments.

Result and side effects

The method returns an instance of the datetime.timedelta type whose value matches the text. If the text cannot be parsed as time, the method raises the ValueError exception. The method has no side effects.

Discussion

The method interprets the text according to the file locale. To have more control over the locale use an intermediate instance of Time:

>>> from filemaker import Text, Time, GERMAN_LOCALE
>>> t = Text('60:34:56,789')
>>> t.timedelta()
Traceback (most recent call last):
    ...
ValueError: The passed text value does not make valid time.
>>> Time(t, GERMAN_LOCALE).timedelta()
datetime.timedelta(2, 45296, 789000)

FileMaker parser is simplistic and will happily produce invalid results. If you need to deal with parsing and locales consider using a third-party module.

upper()#Back to top

Replace all lowercase characters with their uppercase equivalents. Usage:

upper()
Arguments

The method takes no arguments.

Result and side effects

The method replaces all lowercase characters in the text with their uppercase equivalents.The method returns no result. If the instance is read-only, the method will raise the plugin.ReadonlyError exception.

Discussion

Note that this method modifies the data and in general case there's no easy way to go back to the original version. A non-destructive way to make the text appear uppercase while retaining the original information about the case is to create a Style with the uppercase attribute and apply it to the text.

Properties#Back to top

Text has no properties.