1. The Plato importer uses markup to determine how a file is structured so that it may divide the file up into "blocks." Each block will form the raw material for a Plato object, of the class specified in the markup.
   
2. Once the importer has divided the file into blocks, it then goes through the list of blocks and parses each block for fields and notes. How it parses the fields will depend on a particular file's format. Some files (such as email) will have a field section and a note section. Other files, such as spreadsheets, will only have fields, one of which may qualify as a note. Other files will have blocks that will only be broken up into notes. Once fields have been obtained, some may have field names assiciated with content, others only content without associated names. Your import markup will have to define fields and markup in accordance with the conventions of a particular file's format.
   
3. Once fields and notes have been obtained from a block, the field information is gathered into an array where it is validated against the mapping table in your markup and then mapped to the appropriate attributes in your new Plato object, and the import is completed.
   

  "Mojoworld","","Pandromeda","game, simulation"
  "Nikon Scan","","Nikon","editor, image"
  "Wikipad","1.16","Jason Horman","editor, outliner"
  "Chview","","","mapping, astronomical"

[INSTRUCTIONS]
  block_mode= line
  block_composition = fields
  block_mark_mode   = end_of_line
  field_mode= delimited_no_fieldname

[MARKUP_DEFINITIONS]
  end_of_line = &end_of_line
  field_end_delimiter = &comma
  field_braces = &quotes

[FIELD_SEQUENCE]
  1 = {Author}
  2 = Editor
  3 = Translator
  4 = {Title}
  5 = {Subtitle}
  6 = Publisher
  7 = Year

@book{taylor_ethics_1985,
  address = {Englewood Cliffs  N.J.},
  title = {Ethics, faith, and reason},
  isbn = {9780132905527},
  publisher = {Prentice-Hall},
  author = {Richard Taylor},
  year = {1985}
 }

[INSTRUCTIONS]
  block_mode= block
  block_composition = fields
  block_mark_mode   = start_and_end_tags
  field_mode= delimited_with_fieldname

[MARKUP_DEFINITIONS]
  block_markers = @book{|}
  field_end_delimiter = &comma
  field_braces = {}
  field_seperator = =
  strip_chars_from_block = &control &spaces

[FIELD_SUBSTITUTION]
  title = {Title}
  author = {Author}
  publisher = Publisher
  year = Year

• How are 'records' to be defined in the file?
• How are fields defined?
• Do fields contain names along with content?
• Will matching braces need to be kept track of?
• Should field names be validated?

• Parsing Instructions Parsing instructions tell Plato how the external file is constructed: how records are to be distinguished, what records contain, how fields are distinguished from each other within a record.
• Markup Definitions Markup definitions give the specific text Plato is to look for to determine the start and end of records and the fields and notes they contain.
• Mapping Tables Mapping tables define how the fields and notes extracted from records are mapped to Plato objects.

• Block Mode
• Block Composition
• Block Markers
• Field Mode

• Line mode reads the file and looks for end-of-line markers. Each line goes into a block.
• Block mode reads the file and looks for block markers. Everything between the markers goes into a block.
• Chunk mode is for binary files and works by pointing to a file offset and grabbing a chunk of the file of the length you've specified. Chunk mode should only be used on binary files with embedded plain text information.
  One chunk mode method is to go to a specified location in the file and grab one chunk of text. This is useful for reading text information from binary file headers if you know where to find that information.
  Another chunk method is to start at a particular location in the file and sequentially read chunks of the specified length until the end of the file is reached. This approach may be useful for small flat-file databases that have fixed record and field lengths. It is also useful for going through a binary file whose structure is unknown and extracting all the text strings.
• File mode takes the whole file and puts it into a block.

• Fields Tells the importer to break the block up into fields using specified field markers.
• Notes Tells the importer to consider the whole block a note field.
• Fields and Notes Tells the importer to break up the block into a fields section and a notes section, then further break up the fields section into fields using specified field markers.

• Line mode
• end of line This tells the importer to look only for a marker at the end of each block, which in this case is the end of a line. The entire line up to the end-of-line marker will become a block.
• Block mode
• start tag only This tells the importer to look only for a marker at the start of each block. The material between any two start markers will become a block. Material between the last start marker and the end of the file will be placed in a block, but material before the first start marker will be discarded.
• end tag only This tells the importer to look only for a marker at the end of each block. The material between any two end markers will become a block. Material between the start of the file and the first end marker will be placed in a block, but materials between the last end marker and the end of the file will be discarded.
• start and end tags This tells the importer to look for a start marker and an end marker and place what is found between them in a block. Any material outside of what is defined by the start block/end block pairs will be discarded.
• Chunk Mode
• start at offset Tells the importer to go to a specified location in the file (the offset) and grab a specified number of bytes for placement in a block.
• start at offset+ Same as start at offset, except continues through the file grabbing the specified number of bytes and putting them in blocks until the end of the file is reached.
• start at tag Tells the importer to find a specified tag (an arbitrary series of characters you define) and, starting from there, grab a specified number of bytes for placement in a block.
• start at tag+ Same as start at tag, except continues through the file grabbing the specified number of bytes and putting them in blocks until the end of the file is reached.
• File Mode
• start at line Optional. Tells the importer to start at a specified line and grab the rest of the file for the block. If this option is nmot used the whole file is assumed to be the block.

• delimited_no_fieldname Fields are seperated by a delimiter such as a comma or a tab (although a delimiter can be one alphanumeric or punctuation character, or can be a combination of several characters including words, phrases, or language tags). The field data between the delimiters contains no filename information and this mode therefore requires a field_sequence mapping table to map the fields to Plato attributes.
• delimited_with_fieldname Same as delimited_no_fieldname except the field data also contains fieldname information. delimited_with_fieldname mode therefore requires that you specify a field_seperator marker to distinguish the field data from the fieldname data. It also requires a field_substitution mapping table to map the fieldnames in the data to attribute names in the Plato destination object.
• delimit_embedded_fieldname Same as delimited_with_fieldname except the fieldname is not contained in the field data, but is rather embedded in the delimiter.
• tagged_no_fieldname Fields are enclosed within a pair of tags termed start and end tags. The field data between the pair of tags contains no filename information and this mode therefore requires a field_sequence mapping table to map the fields to Plato attributes.
• tagged_with_fieldname Same as tagged_no_fieldname except the field data also contains fieldname information. tagged_with_fieldname mode therefore requires that you specify a field_seperator marker to distinguish the field data from the fieldname data. It also requires a field_substitution mapping table to map the fieldnames in the data to attribute names in the Plato destination object.
• tag_embedded_fieldname Same as tagged_with_fieldname except the fieldname is not contained in the field data, but is rather embedded in the start tag.
• line_offset This mode addresses text files in which fields are laid out in fixed-length columns in a line, and each line is a fixed-lengh record. The columns are padded with spaces to achieve equal width. There are no tags or delimiters so fields are determined strictly by their position along the line. line_offset mode therefore requires only a line_offset table to map the fields to Plato attributes according to their position in the fixed-length record.
• length_offset This mode addresses

• block_start, block_end markers Defines the marker that represents the start or end of a block. A marker can be any single character or set of characters. Any number of markers can be specified, but start and end markers can't be mixed in one set of markup.
• block_markers Defines a pair of markers that enclose a block. Such a pair consists of a start marker and an end marker on one line seperated by a vertical mark (|). Any number of block marker pairs can be specified, but they can't be mixed with block start or block end markers.

• note_delimiter Defines the marker that seperates fields from notes in block. Few file formats will have note delimiters but some do. The raw email format is one of the few that does, and uses a blank line (&end_of_paragraph is a Plato macro that represents this) to seperate the email header (which contains fields) from the body (which contains a block of text).
• field start, field end delimiters Field delimiters seperate one field from another in a block. Common field delimiters are commas, tabs, and spaces. These are generally 'field end' delimiters in Plato terminology since they are placed at the end of a field (except for the last field).
  
  Field start delimiters are less common, but an email header is a good candidate for them, which would be the email header field names followed by a colon. This is also a good example of field delimiters with embedded field names.
  

  Message-ID:  <4.1.20000226171947.00935630@mail.well.com>
  Date: Sat, 26 Feb 2000 17:21:12 -0800
  Reply-To: "H-NEXA: the Science-Humanities Convergence Forum" 
  Sender: "H-NEXA: the Science-Humanities Convergence Forum" 
  From: "Smiley Hamburguesa" 
  Subject:   SUBJECT: The Gospel according to Science [hbe-l]
  To: H-NEXA@H-NET.MSU.EDU
  X-UIDL: 53938ef43ccdb961435520d46578aec2

  
  The import markup for this would have several markup delimiters:
  

    field_start_delimiter = Message-ID:
    field_start_delimiter = Date:
    field_start_delimiter = Reply-To:
    field_start_delimiter = Sender:
    field_start_delimiter = From:
    field_start_delimiter = Subject:
    field_start_delimiter = To:
    field_start_delimiter = X-UIDL:

  
  
• field tag pairs Defines a pair of markers that enclose a field. Such a pair consists of a start marker and an end marker on one line seperated by a vertical mark (|). Any number of field marker pairs can be specified, but they can't be mixed with block start or block end markers.
• fieldname seperator Defines a marker that seperates a fieldname (on the left) from the field contents (on the right). Any number of fieldname seperators can be specified.
• field braces Sometime fields are also enclosed in quotes or other pairs of braces when they contain characters that might be confused with delimiters. The braces "protect" the field contents from this sort of misapplication. Braces are specified in pairs. Several brace pairs can be specified on one line so long as each pair is seperated from the next by a space. Here's an example of a field braces markup definition ('&quotes' is a Plato macro that expands to a pair of quotes):
  

  field_braces = &quotes <> {} [] ()

1. blocks
2. fields
3. notes

• strip_chars_from_block
• strip_words_from_block
• strip_tags_from_block
• strip_chars_from_field
• strip_words_from_field
• strip_tags_from_field
• strip_chars_from_note
• strip_words_from_note
• strip_tags_from_note
• discard_block_if_word

  strip_tags_from_note = <>
  strip_words_from_note = &nbsp; &gt; &quot; &lt; &ordm; &middot; &acute; &macr; &cedil;
  strip_chars_from_note = &control &spaces &CRFLs

discard_block_if_word = bingbot
discard_block_if_word = googlebot
discard_block_if_word = semrushbot
discard_block_if_word = ahrefsbot
discard_block_if_word = yandexbot

discard_block_if_word = bingbot googlebot semrushbot
discard_block_if_word = ahrefsbot yandexbot

use_last_nonblank_for = 1 2 4 5 8

• field_substitution Substitution tables are used to translate field names found in the file being parsed to actual object attibute names. Example:
  

    "author name" = author
    "year"= publication_date 

• field_sequence The 'field sequence' type is for delimited files with a record on each line, such as CSV files, in which the order of fields doesn't match the order in the Plato object. For example, the file might look like:
  

    "12345","Jones, Bob","123 Elm Street","555-1212"
    "23456","Miller, Bill","234 Oak Street","555-2323"
    "34567","Smith, Jack","345 Ash Street","555-3434" 

  
  where customer_ID is the first field, followed by name, address, then phone number. But the Plato object might have its attributes placed in a different order, such as:
  

    Name
    phone
    address
    customer_id 

  
  A 'field order' table for this file would then be:
  

    2 = name
    4 = phone
    3 = address
    1 = customer_id 

• line_offset The 'line offset' type is for files with a record on each line, in which the fields are aligned in columns and padded with spaces. Database reports are sometimes structured this way. Such a file might look like this:
  

    Customer ID  Name  Address  Phone
    -----------  ------------  ---------------  ---------
    12345Jones, Bob123 Elm Street   555-1212
    23456Miller, Bill  234 Oak Street   555-2323
    34567Smith, Jack   345 Ash Street   555-3434 

  
  A 'line offset' table for this file would be:
  

    1  = customer_id
    13 = name
    33 = address
    55 = phone 

  
  This example would take whatever is found from line offsets 1 to 12 and place it in the object's 'customer_id' attribute, and so on to the end of the line.
• length_offset The 'field length' type is for binary files that contain fixed-length records of known length and sequence.