cape.filecntl.filecntl: File control base module

This provides common methods to control objects for various specific files. This includes various methods for reading files, splitting it into sections, and replacing lines based on patterns or regular expressions.

File manipulation classes for specific files (such as pyCart.inputCntl.InputCntl for Cart3D input.cntl files) are built off of this module and its main class. A possibly incomplete list of class built on this class is given below.

class cape.filecntl.filecntl.FileCntl(fname=None)

Base file control class

The lines of the file can be split into sections based on a regular expression (see cape.filecntl.FileCntl.SplitToSections()); most methods will keep the overall line list and the section breakout consistent.

Call:
>>> FC = cape.filecntl.FileCntl(fname)
Inputs:
fname: str

Name of file to read from and manipulate

Data members:
FC.fname: str

Name of file instance was read from

FC.lines: list[str]

List of all lines in the file (to use for replacement)

FC.SectionNames: list[str]

List of section titles if present

FC.Section: dict (list[str])

Dictionary of the lines in each section, if present

AppendLine(line)

Append a line of text to FC.lines

Call:
>>> FC.AppendLine(line)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

line: str

String to add

Versions:

  • 2014-06-03 @ddalle: v1.0

AppendLineToSection(sec, line)

Append a line of text to a section

Call:
>>> FC.AppendLineToSection(sec, line)
Inputs:
FC: pyCart.fileCntl.FileCntl

File control instance

sec: str

Name of section to update

line: str

String to add

Versions:

  • 2014-06-03 @ddalle: v1.0

AssertSection(sec)

Assert that a certain section is present

Call:
>>> FC.AssertSection(sec)
Inputs:
FC: cape.filecntl.FileCntl

File control instance, defaults to FC.fname

sec: str

Name of section to check for

Versions:

  • 2014-06-03 @ddalle: v1.0

CountEmptyEnd(lines)

Count empty lines at the end of a list of lines

Call:
>>> n = FC.CountEmptyEnd(lines)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

lines: list[str]

List of lines in section or file

Outputs:
n: int

Number of trailing empty lines

Versions:

  • 2016-04-18 @ddalle: v1.0

CountEmptyStart(lines)

Count empty lines at the start of a list of lines

Call:
>>> n = FC.CountEmptyStart(lines)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

lines: list[str]

List of lines in section or file

Outputs:
n: int

Number of trailing empty lines

Versions:

  • 2016-04-18 @ddalle: v1.0

DeleteLineInSectionStartsWith(sec, start, count=1)

Delete lines based on start text and section name

Call:
>>> n = FC.DeleteLineInSectionStartsWith(sec, start)
>>> n = FC.DeleteLineInSectionStartsWith(sec, start, count)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

sec: str

Name of section to search

start: str

Line-starting string to search for

count: {1} | int

Maximum number of lines to delete

Outputs:
n: int

Number of deletions made

Effects:

Lines in FC.Section[sec] may be removed if they start with start.

Versions:

  • 2014-06-03 @ddalle: v1.0

DeleteLineStartsWith(start, count=1)

Delete lines that start with given text up to count times

Call:
>>> n = FC.DeleteLineStartsWith(start)
>>> n = FC.DeleteLineStartsWith(start, count)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

start: str

Line-starting string to search for

count: {1} | int

Maximum number of lines to delete

Outputs:
n: int

Number of deletions made

Effects:

Lines in FC.lines that start with start are removed

Versions:

  • 2014-06-03 @ddalle: v1.0

GetIndexInSectionSearch(sec, reg, n=None)

Find lines in a given section that start with a regex

Call:
>>> i = FC.GetIndexInSectionSearch(sec, reg)
>>> i = FC.GetIndexInSectionSearch(sec, reg, n)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

sec: str

Name of section to search in

reg: str

Regular expression to match beginning of line

n: int

Maximum number of matches to search for

Outputs:
i: list[int]

List of indices of lines in section that match pattern

Versions:

  • 2014-02-28 @ddalle: v1.0

GetIndexInSectionStartsWith(sec, start, n=None)

Find lines in a given section with given start string

Call:
>>> i = FC.GetIndexInSectionStartsWith(sec, start)
>>> i = FC.GetIndexInSectionStartsWith(sec, start, n)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

sec: str

Name of section to search in

start: str

Line start target

n: int

Maximum number of matches to search for

Outputs:
i: list[int]

List of indices of lines in section that match pattern

Versions:

  • 2014-02-28 @ddalle: v1.0

GetIndexSearch(reg, n=None)

Find lines that start with a given regular expression

Call:
>>> i = FC.GetIndexSearch(reg)
>>> i = FC.GetIndexSearch(reg, n)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

reg: str

Regular expression to match beginning of line

n: int

Maximum number of matches to search for

Outputs:
i: list[int]

List of lines that match pattern

Versions:

  • 2014-02-28 @ddalle: v1.0

GetIndexStartsWith(start, n=None)

Find indices of lines that start with a given literal pattern

Call:
>>> i = FC.GetIndexStartsWith(start)
>>> i = FC.GetIndexStartsWith(start, n)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

start: str

Line start target

n: int

Maximum number of matches to search for

Outputs:
i: list[int]

List of lines that match pattern

Versions:

  • 2015-02-28 @ddalle: v1.0

GetLineInSectionSearch(sec, reg, n=None)

Find lines in a given section that start specified regex

Call:
>>> lines = FC.GetLineInSectionSearch(sec, reg)
>>> lines = FC.GetLineInSectionSearch(sec, reg, n)
Inputs:
FC: pyCart.fileCntl.FileCntl

File control instance

sec: str

Name of section to search in

reg: str

Regular expression to match beginning of line

n: int

Maximum number of matches to search for

Outputs:
lines: list[str]

List of lines that match pattern

Versions:

  • 2014-06-10 @ddalle: v1.0

GetLineInSectionStartsWith(sec, start, n=None)

Find lines in a given section that start specified target

Call:
>>> lines = FC.GetLineInSectionStartsWith(sec, start)
>>> lines = FC.GetLineInSectionStartsWith(sec, start, n)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

sec: str

Name of section to search in

start: str

Target line start

n: int

Maximum number of matches to search for

Outputs:
lines: list[str]

List of lines that match pattern

Versions:

  • 2014-06-10 @ddalle: v1.0

GetLineSearch(reg, n=None)

Find lines that start with a given regular expression

Call:
>>> lines = FC.GetLineSearch(reg)
>>> lines = FC.GetLineSearch(reg, n)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

reg: str

Regular expression to match beginning of line

n: int

Maximum number of matches to search for

Outputs:
lines: list[str]

List of lines that match pattern

Versions:

  • 2014-06-10 @ddalle: v1.0

GetLineStartsWith(start, n=None)

Find lines that start with a given literal pattern

Call:
>>> lines = FC.GetLineStartsWith(start)
>>> lines = FC.GetLineStartsWith(start, n)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

start: str

String to test as match for beginning of each line

n: int

Maximum number of matches to search for

Outputs:
lines: list[str]

List of lines that match pattern

Versions:

  • 2014-06-10 @ddalle: v1.0

InsertLine(i, line)

Insert a line of text somewhere into the text

Call:
>>> FC.InsertLine(i, line)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

i: int

Index to which to insert the line

line: str

String to add

Versions:

  • 2014-06-03 @ddalle: v1.0

InsertLineToSection(sec, i, line)

Insert a line of text somewhere into the text of a section

Call:
>>> FC.InsertLineToSection(sec, i, line)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

sec: str

Name of section to update

i: int

Index to which to insert the line

line: str

String to add

Effects:

A line is inserted to FC.Section[sec]

Versions:

  • 2014-06-03 @ddalle: v1.0

PrependLine(line)

Prepend a line of text to FC.lines

Call:
>>> FC.PrependLine(line)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

line: str

String to add

Versions:

  • 2014-06-03 @ddalle: v1.0

PrependLineToSection(sec, line)

Prepend a line of text to a section

Call:
>>> FC.PrependLineToSection(sec, line)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

sec: str

Name of section to update

line: str

String to add

Versions:

  • 2014-06-03 @ddalle: v1.0

Read(fname)

Read text from file

Call:
>>> FC.Read(fname)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

fname: str

Name of file to read from

Effects:
FC.lines: list

List of lines in file is created

FC._updated_sections: bool

Whether section breakouts have been updated

FC._updated_lines: bool

Flag for update status of global lines

Versions:

  • 2014-06-03 @ddalle: v1.0

ReplaceLineInSectionSearch(sec, reg, line, imin=0, nmax=None)

Find all lines in a certain section that start with a specified regular expression and replace the entire lines with the specified text.

Call:
>>> n = FC.ReplaceLineInSectionSearch(sec, reg, line, **kw)
>>> n = FC.ReplaceLineInSectionSearch(sec, reg, lines, **kw)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

sec: str

Name of section to search in

reg: str

Regular expression to search for at beginning of each line

line: str

String to replace every match with

lines: list

List of strings to match first len(lines) matches with

imin: {0} | int >= 0

Do not make replacements for matches with index < imin

nmax: {None} | int > 0

Make at most nmax substitutions

Outputs:
n: int

Number of matches found

Effects:

Some lines in FC.Section[sec] may be replaced.

See also:

This function is similar to pyCart.fileCntl.FileCntl.ReplaceLineSearch() except that the search is restricted to a specified section.

Versions:

  • 2014-06-04 @ddalle: v1.0

ReplaceLineInSectionStartsWith(sec, start, line, imin=0, nmax=None)

Make replacements within section based on starting string

Find all lines in a certain section that start with a specified literal string and replace the entire line with the specified text.

Call:
>>> n = FC.ReplaceLineInSectionStartsWith(
    , start, line, **kw)
>>> n = FC.ReplaceLineInSectionStartsWith(
    sec, start, lines, **kw)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

sec: str

Name of section to search in

start: str

String to test as literal match for line start

line: str

String to replace every match with

lines: list

List of replacement strings

imin: {0} | int >= 0

Do not make replacements for matches with index < imin

nmax: {None} | int > 0

Make at most nmax substitutions

Outputs:
n: int

Number of matches found

Effects:

Some lines in FC.Section[sec] may be replaced.

See also:

This function is similar to cape.filecntl.FileCntl.ReplaceLineStartsWith() except that the search is restricted to a specified section.

Versions:

  • 2014-06-03 @ddalle: v1.0

ReplaceLineSearch(reg, line, imin=0, nmax=None)

Replace lines based on initial regular expression

Find all lines that begin with a certain regular expression and replace them with another string. Note that the entire line is replaced, not just the regular expression.

Leading spaces are ignored during the match tests.

Call:
>>> n = FC.ReplaceLineSearch(reg, line, imin=0, nmax=None)
>>> n = FC.ReplaceLineSearch(reg, lines, imin=0, nmax=None)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

reg: str

Target regular expression for line starts

line: str

String to replace every match with

lines: list

Multiple replacements

imin: {0} | int >= 0

Do not make replacements for matches with index < imin

nmax: {None} | int > 0

Make at most nmax substitutions

Outputs:
n: int

Number of matches found

Effects:

FC.lines: Some of the lines may be affected FC._updated_lines: Set to True

Examples:

Suppose that FC has the following two lines.

Mach      8.00   # some comment\n

Mach    4\n

Then this example will replace both lines with Mach 2.0

>>> FC.ReplaceLineSearch('Mach\s+[0-9.]+', 'Mach 2.0')

This example replaces each line with a different value for the Mach number.

>>> FC.ReplaceLineSearch('Mach\s+[0-9.]+',
    ['Mach 2.0', 'Mach 2.5'])

Finally, this example is different from the first example in that it will replace the first line and then quit before it can find the second match.

>>> FC.ReplaceLineSearch('Mach\s+[0-9.]+', ['Mach 2.0'])
Versions:

  • 2014-06-04 @ddalle: v1.0

ReplaceLineStartsWith(start, line, imin=0, nmax=None)

Replace lines starting with fixed text

Find all lines that begin with a certain string and replace them with another string. Note that the entire line is replaced, not just the initial string.

Leading spaces are ignored during the match tests.

Call:
>>> n = FC.ReplaceLineStartsWith(start, line, imin=0, nmax=None)
>>> n = FC.ReplaceLineStartsWith(start, lines, imin=0, nmax=None)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

start: str

String to test as literal match for beginning of line

line: str

String to replace every match with

lines: list

List of strings for replacements

imin: {0} | int >= 0

Do not make replacements for matches with index < imin

nmax: {None} | int > 0

Make at most nmax substitutions

Outputs:
n: int

Number of matches found

Effects:

FC.lines: Some of the lines may be affected FC._updated_lines: Set to True

Examples:

Suppose that FC has the following two lines.

Mach      8.00   # some comment\n

Mach      Mach_TMP\n

Then this example will replace both lines with the string Mach 4.0

>>> FC.ReplaceLineStartsWith('Mach', 'Mach 4.0')

This example replaces each line with a different value for the Mach number.

>>> FC.ReplaceLineStartsWith(
    'Mach', ['Mach 2.0', 'Mach 4.0']

Finally, this example is different from the first example in that it will replace the first line and then quit before it can find the second match.

>>> FC.ReplaceLineStartsWith('Mach', ['Mach 4.0'])
Versions:

  • 2014-06-03 @ddalle: v1.0

  • 2019-06-19 @ddalle: Added imin and nmax

ReplaceOrAddLineSearch(reg, line, i=None, **kw)

Replace a line that starts with a given regular expression or add the line if no matches are found.

Call:
>>> FC.ReplaceOrAddLineSearch(reg, line, **kw)
>>> FC.ReplaceOrAddLineSearch(reg, line, i, **kw)
Inputs:
FC: pyCart.fileCntl.FileCntl

File control instance

reg: str

Regular expression to match beginning of line

line: str

String to replace first match with

i: int

Location to add line (by default it is appended)

imin: {0} | int >= 0

Do not make replacements for matches with index < imin

nmax: {None} | int > 0

Make at most nmax substitutions

Effects:

Replaces line in section FC.lines or adds it if not found

Versions:

  • 2014-06-04 @ddalle: v1.0

ReplaceOrAddLineStartsWith(start, line, i=None, **kw)

Replace a line or add a new one

Replace a line that starts with a given literal string or add the line if no matches are found.

Call:
>>> FC.ReplaceOrAddLineStartsWith(start, line, **kw)
>>> FC.ReplaceOrAddLineStartsWith(start, line, i, **kw)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

start: str

Target beginning of line to replace

line: str

String to replace every match with

i: {None} | int

Location to add line, negative ok, (default is append)

imin: {0} | int >= 0

Do not make replacements for matches with index < imin

nmax: {None} | int > 0

Make at most nmax substitutions

Effects:

Replaces line in section FC.lines or adds it if not found

Versions:

  • 2014-06-03 @ddalle: v1.0

ReplaceOrAddLineToSectionSearch(sec, reg, line, i=None)

Replace a line in a specified section

Replace a line in a specified section that starts with a given regular expression or add the line to the section if no matches are found.

Call:
>>> FC.ReplaceOrAddLineToSectionStartsWith(sec, reg, line)
>>> FC.ReplaceOrAddLineToSectionStartsWith(sec, reg, line,
    i=None, **kw)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

sec: str

Name of section to search in

reg: str

Regular expression to match beginning of line

line: str

String to replace every match with

i: {`None} | int

Location to add line (by default it is appended)

Effects:

Replaces line in FC.Section[sec] or adds it if not found

Versions:

  • 2014-06-04 @ddalle: v1.0

ReplaceOrAddLineToSectionStartsWith(sec, start, line, i=None, **kw)

Replace a line or add a new one (within section)

Replace a line in a specified section that starts with a given literal string or add the line to the section if no matches are found.

Call:
>>> FC.ReplaceOrAddLineToSectionStartsWith(sec, start, line)
>>> FC.ReplaceOrAddLineToSectionStartsWith(sec, start, line,
    i=None, **kw)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

sec: str

Name of section to search in

start: str

Target line start for replacement

line: str

String to replace every match with

i: {None} | int

Location to add line (by default it is appended)

imin: {0} | int >= 0

Do not make replacements for matches with index < imin

nmax: {None} | int > 0

Make at most nmax substitutions

Effects:

Replaces line in FC.Section[sec] or adds it if not found

Versions:

  • 2014-06-03 @ddalle: v1.0

SplitToBlocks(reg='\\$__([\\w_]+)', ngr=1, **kw)

Split lines into sections based on start and end

Call:
>>> FC.SplitToBlocks()
>>> FC.SplitToBlocks(reg="\$__([\w_]+)", ngr=1, **kw)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

reg: str

Regular expression for recognizing the start of a new section. By default this looks for sections that start with "$__" as inCart3D input.cntl files. The regular expression must also include a group (meaning content between parentheses) to capture the name of the section. Thus the default value of "\$__([\w_]+)" finds any name that consists of word characters and/or underscores.

ngr: {1} | int | str

Group number from which to take name of section. This is always 1 unless the section-starting regular expression has more than one explicit group. Note that using 1 instead of 0 means that an explicit group using parentheses is required. A string can be used if the groups have names in the regular expression reg.

begin: {True} | False

Whether section regular expression must begin line

endreg: {None} | str

Optional regular expression for end of section. If used, some lines will end up in sections called "_inter1", "_inter2", etc.

endbegin: {begin} | True | False

Whether section-end regular expression must begin line

endngr: {ngr} | int | str

Group number of name for title of end-of-section regex

Effects:
FC.SectionNames: list

List of section names is created (includes “_header”)

FC.Section: dict

Dictionary of section line lists is created

Versions:

  • 2014-06-03 @ddalle: v1.0

SplitToSections(reg='\\$__([\\w_]+)', ngr=1, begin=True)

Split into sections based on starting regular expression

Call:
>>> FC.SplitToSections()
>>> FC.SplitToSections(reg="\$__([\w_]+)", ngr=1, **kw)
Inputs:
FC: cape.filecntl.FileCntl

File control instance

reg: str

Regular expression for recognizing the start of a new section. By default this looks for sections that start with "$__" as in Cart3D input.cntl files. The regular expression must also include a group (meaning content between parentheses) to capture the name of the section. Thus the default value of "\$__([\w_]+)" finds any name that consists of word characters and/or underscores.

ngr: {1} | int | str

Group number from which to take name of section. This is always 1 unless the section-starting regular expression has more than one explicit group. Note that using 1 instead of 0 means that an explicit group using parentheses is required. A string can be used if the groups have names in the regular expression reg.

begin: {True} | False

Whether section regular expression must begin line

endreg: {None} | str

Optional regular expression for end of section. If used, some lines will end up in sections called "_inter1", "_inter2", etc.

Effects:
FC.SectionNames: list

List of section names is created (includes “_header”)

FC.Section: dict

Dictionary of section line lists is created

Versions:

  • 2014-06-03 @ddalle: v1.0

UpdateLines()

Update the global file text list from current section content

Call:
>>> FC.UpdateLines()
Inputs:
FC: cape.filecntl.FileCntl | derivative

File control instance

Effects:
FC.lines: list

Lines are rewritten to match the sequence of lines from the sections

Versions:

  • 2014-06-03 @ddalle: v1.0

UpdateSections()

Remake the section split if necessary

This runs SplitToSections() is run if FC._updated_lines is True.

Call:
>>> FC.UpdateSections()
Inputs:
FC: cape.filecntl.FileCntl

File control instance

Versions:

  • 2014-06-03 @ddalle: v1.0

Write(fname=None)

Write to text file

Call:
>>> FC.Write()
>>> FC.Write(fname)
Inputs:
FC: cape.filecntl.FileCntl

File control instance, defaults to FC.fname

fname: str

Name of file to write to

Versions:

  • 2014-06-03 @ddalle: v1.0

  • 2015-11-16 @ddalle: Moved contents to _Write()

WriteEx(fname=None)

Write to text file as an executable script

Call:
>>> FC.WriteEx()
>>> FC.WriteEx(fname)
Inputs:
FC: cape.filecntl.FileCntl

File control instance, defaults to FC.fname

fname: str

Name of file to write to

Versions:

  • 2014-06-23 @ddalle: v1.0