FvgTypes█ OVERVIEW
This library serves as a foundational module for Pine Script™ projects focused on Fair Value Gaps (FVGs). Its primary purpose is to define and centralize custom data structures (User-Defined Types - UDTs) and enumerations that are utilized across various components of an FVG analysis system. By providing standardized types for FVG characteristics and drawing configurations, it promotes code consistency, readability, and easier maintenance within a larger FVG indicator or strategy.
█ CONCEPTS
The library introduces several key data structures (User-Defined Types - UDTs) and an enumeration to organize Fair Value Gap (FVG) related data logically. These types are central to the functioning of FVG analysis tools built upon this library.
Timeframe Categorization (`tfType` Enum)
To manage and differentiate FVGs based on their timeframe of origin, the `tfType` enumeration is defined. It includes:
`LTF`: Low Timeframe (typically the current chart).
`MTF`: Medium Timeframe.
`HTF`: High Timeframe.
This allows for distinct logic and visual settings to be applied depending on the FVG's source timeframe.
FVG Data Encapsulation (`fvgObject` UDT)
The `fvgObject` is a comprehensive UDT designed to encapsulate all pertinent information and state for an individual Fair Value Gap throughout its lifecycle. Instead of listing every field, its conceptual structure can be understood as holding:
Core Definition: The FVG's fundamental price levels (top, bottom) and its formation time (`startTime`).
Classification Attributes: Characteristics such as its direction (`isBullish`) and whether it qualifies as a Large Volume FVG (`isLV`), along with its originating timeframe category (`tfType`).
Lifecycle State: Current status indicators including full mitigation (`isMitigated`, `mitigationTime`), partial fill levels (`currentTop`, `currentBottom`), midline interaction (`isMidlineTouched`), and overall visibility (`isVisible`).
Drawing Identifiers: References (`boxId`, `midLineId`, `mitLineLabelId`, etc.) to the actual graphical objects drawn on the chart to represent the FVG and its components.
Optimization Cache: Previous-bar state values (`prevIsMitigated`, `prevCurrentTop`, etc.) crucial for optimizing drawing updates by avoiding redundant operations.
This comprehensive structure facilitates easy access to all FVG-related information through a single object, reducing code complexity and improving manageability.
Drawing Configuration (`drawSettings` UDT)
The `drawSettings` UDT centralizes all user-configurable parameters that dictate the visual appearance of FVGs across different timeframes. It's typically populated from script inputs and conceptually groups settings for:
General Behavior: Global FVG classification toggles (e.g., `shouldClassifyLV`) and general display rules (e.g., `shouldHideMitigated`).
FVG Type Specific Colors: Colors for standard and Large Volume FVGs, both active and mitigated (e.g., `lvBullColor`, `mitigatedBearBoxColor`).
Timeframe-Specific Visuals (LTF, MTF, HTF): Detailed parameters for each timeframe category, covering FVG boxes (visibility, colors, extension, borders, labels), midlines (visibility, style, color), and mitigation lines (visibility, style, color, labels, persistence after mitigation).
Contextual Information: The current bar's time (`currentTime`) for accurate positioning of time-dependent drawing elements and timeframe display strings (`tfString`, `mtfTfString`, `htfTfString`).
This centralized approach allows for extensive customization of FVG visuals and simplifies the management of drawing parameters within the main script. Such centralization also enhances the maintainability of the visual aspects of the FVG system.
█ NOTES
User-Defined Types (UDTs): This library extensively uses UDTs (`fvgObject`, `drawSettings`) to group related data. This improves code organization and makes it easier to pass complex data between functions and libraries.
Mutability and Reference Behavior of UDTs: When UDT instances are passed to functions or methods in other libraries (like `fvgObjectLib`), those functions might modify the fields of the passed object if they are not explicitly designed to return new instances. This is because UDTs are passed by reference and are mutable in Pine Script™. Users should be aware of this standard behavior to prevent unintended side effects.
Optimization Fields: The `prev_*` fields in `fvgObject` are crucial for performance optimization in the drawing logic. They help avoid unnecessary redrawing of FVG elements if their state or relevant settings haven't changed.
No Direct Drawing Logic: `FvgTypes` itself does not contain any drawing logic. It solely defines the data structures. The actual drawing and manipulation of these objects are handled by other libraries (e.g., `fvgObjectLib`).
Centralized Definitions: By defining these types in a separate library, any changes to the structure of FVG data or settings can be made in one place, ensuring consistency across all dependent scripts and libraries.
█ EXPORTED TYPES
fvgObject
fvgObject Represents a Fair Value Gap (FVG) object.
Fields:
top (series float) : The top price level of the FVG.
bottom (series float) : The bottom price level of the FVG.
startTime (series int) : The start time (timestamp) of the bar where the FVG formed.
isBullish (series bool) : Indicates if the FVG is bullish (true) or bearish (false).
isLV (series bool) : Indicates if the FVG is a Large Volume FVG.
tfType (series tfType) : The timeframe type (LTF, MTF, HTF) to which this FVG belongs.
isMitigated (series bool) : Indicates if the FVG has been fully mitigated.
mitigationTime (series int) : The time (timestamp) when the FVG was mitigated.
isVisible (series bool) : The current visibility status of the FVG, typically managed by drawing logic based on filters.
isMidlineTouched (series bool) : Indicates if the price has touched the FVG's midline (50% level).
currentTop (series float) : The current top level of the FVG after partial fills.
currentBottom (series float) : The current bottom level of the FVG after partial fills.
boxId (series box) : The drawing ID for the main FVG box.
mitigatedBoxId (series box) : The drawing ID for the box representing the partially filled (mitigated) area.
midLineId (series line) : The drawing ID for the FVG's midline.
mitLineId (series line) : The drawing ID for the FVG's mitigation line.
boxLabelId (series label) : The drawing ID for the FVG box label.
mitLineLabelId (series label) : The drawing ID for the mitigation line label.
testedBoxId (series box) : The drawing ID for the box of a fully mitigated (tested) FVG, if kept visible.
keptMitLineId (series line) : The drawing ID for a mitigation line that is kept after full mitigation.
prevIsMitigated (series bool) : Stores the isMitigated state from the previous bar for optimization.
prevCurrentTop (series float) : Stores the currentTop value from the previous bar for optimization.
prevCurrentBottom (series float) : Stores the currentBottom value from the previous bar for optimization.
prevIsVisible (series bool) : Stores the visibility status from the previous bar for optimization (derived from isVisibleNow passed to updateDrawings).
prevIsMidlineTouched (series bool) : Stores the isMidlineTouched status from the previous bar for optimization.
drawSettings
drawSettings A structure containing settings for drawing FVGs.
Fields:
shouldClassifyLV (series bool) : Whether to classify FVGs as Large Volume (LV) based on ATR.
shouldHideMitigated (series bool) : Whether to hide FVG boxes once they are fully mitigated.
currentTime (series int) : The current bar's time, used for extending drawings.
lvBullColor (series color) : Color for Large Volume Bullish FVGs.
mitigatedLvBullColor (series color) : Color for mitigated Large Volume Bullish FVGs.
lvBearColor (series color) : Color for Large Volume Bearish FVGs.
mitigatedLvBearColor (series color) : Color for mitigated Large Volume Bearish FVGs.
shouldShowBoxes (series bool) : Whether to show FVG boxes for the LTF.
bullBoxColor (series color) : Color for LTF Bullish FVG boxes.
mitigatedBullBoxColor (series color) : Color for mitigated LTF Bullish FVG boxes.
bearBoxColor (series color) : Color for LTF Bearish FVG boxes.
mitigatedBearBoxColor (series color) : Color for mitigated LTF Bearish FVG boxes.
boxLengthBars (series int) : Length of LTF FVG boxes in bars (if not extended).
shouldExtendBoxes (series bool) : Whether to extend LTF FVG boxes to the right.
shouldShowCurrentTfBoxLabels (series bool) : Whether to show labels on LTF FVG boxes.
shouldShowBoxBorder (series bool) : Whether to show a border for LTF FVG boxes.
boxBorderWidth (series int) : Border width for LTF FVG boxes.
boxBorderStyle (series string) : Border style for LTF FVG boxes (e.g., line.style_solid).
boxBorderColor (series color) : Border color for LTF FVG boxes.
shouldShowMidpoint (series bool) : Whether to show the midline (50% level) for LTF FVGs.
midLineWidthInput (series int) : Width of the LTF FVG midline.
midpointLineStyleInput (series string) : Style of the LTF FVG midline.
midpointColorInput (series color) : Color of the LTF FVG midline.
shouldShowMitigationLine (series bool) : Whether to show the mitigation line for LTF FVGs.
(Line always extends if shown)
mitLineWidthInput (series int) : Width of the LTF FVG mitigation line.
mitigationLineStyleInput (series string) : Style of the LTF FVG mitigation line.
mitigationLineColorInput (series color) : Color of the LTF FVG mitigation line.
shouldShowCurrentTfMitLineLabels (series bool) : Whether to show labels on LTF FVG mitigation lines.
currentTfMitLineLabelOffsetX (series float) : The horizontal offset value for the LTF mitigation line's label.
shouldKeepMitigatedLines (series bool) : Whether to keep showing mitigation lines of fully mitigated LTF FVGs.
mitigatedMitLineColor (series color) : Color for kept mitigation lines of mitigated LTF FVGs.
tfString (series string) : Display string for the LTF (e.g., "Current TF").
shouldShowMtfBoxes (series bool) : Whether to show FVG boxes for the MTF.
mtfBullBoxColor (series color) : Color for MTF Bullish FVG boxes.
mtfMitigatedBullBoxColor (series color) : Color for mitigated MTF Bullish FVG boxes.
mtfBearBoxColor (series color) : Color for MTF Bearish FVG boxes.
mtfMitigatedBearBoxColor (series color) : Color for mitigated MTF Bearish FVG boxes.
mtfBoxLengthBars (series int) : Length of MTF FVG boxes in bars (if not extended).
shouldExtendMtfBoxes (series bool) : Whether to extend MTF FVG boxes to the right.
shouldShowMtfBoxLabels (series bool) : Whether to show labels on MTF FVG boxes.
shouldShowMtfBoxBorder (series bool) : Whether to show a border for MTF FVG boxes.
mtfBoxBorderWidth (series int) : Border width for MTF FVG boxes.
mtfBoxBorderStyle (series string) : Border style for MTF FVG boxes.
mtfBoxBorderColor (series color) : Border color for MTF FVG boxes.
shouldShowMtfMidpoint (series bool) : Whether to show the midline for MTF FVGs.
mtfMidLineWidthInput (series int) : Width of the MTF FVG midline.
mtfMidpointLineStyleInput (series string) : Style of the MTF FVG midline.
mtfMidpointColorInput (series color) : Color of the MTF FVG midline.
shouldShowMtfMitigationLine (series bool) : Whether to show the mitigation line for MTF FVGs.
(Line always extends if shown)
mtfMitLineWidthInput (series int) : Width of the MTF FVG mitigation line.
mtfMitigationLineStyleInput (series string) : Style of the MTF FVG mitigation line.
mtfMitigationLineColorInput (series color) : Color of the MTF FVG mitigation line.
shouldShowMtfMitLineLabels (series bool) : Whether to show labels on MTF FVG mitigation lines.
mtfMitLineLabelOffsetX (series float) : The horizontal offset value for the MTF mitigation line's label.
shouldKeepMtfMitigatedLines (series bool) : Whether to keep showing mitigation lines of fully mitigated MTF FVGs.
mtfMitigatedMitLineColor (series color) : Color for kept mitigation lines of mitigated MTF FVGs.
mtfTfString (series string) : Display string for the MTF (e.g., "MTF").
shouldShowHtfBoxes (series bool) : Whether to show FVG boxes for the HTF.
htfBullBoxColor (series color) : Color for HTF Bullish FVG boxes.
htfMitigatedBullBoxColor (series color) : Color for mitigated HTF Bullish FVG boxes.
htfBearBoxColor (series color) : Color for HTF Bearish FVG boxes.
htfMitigatedBearBoxColor (series color) : Color for mitigated HTF Bearish FVG boxes.
htfBoxLengthBars (series int) : Length of HTF FVG boxes in bars (if not extended).
shouldExtendHtfBoxes (series bool) : Whether to extend HTF FVG boxes to the right.
shouldShowHtfBoxLabels (series bool) : Whether to show labels on HTF FVG boxes.
shouldShowHtfBoxBorder (series bool) : Whether to show a border for HTF FVG boxes.
htfBoxBorderWidth (series int) : Border width for HTF FVG boxes.
htfBoxBorderStyle (series string) : Border style for HTF FVG boxes.
htfBoxBorderColor (series color) : Border color for HTF FVG boxes.
shouldShowHtfMidpoint (series bool) : Whether to show the midline for HTF FVGs.
htfMidLineWidthInput (series int) : Width of the HTF FVG midline.
htfMidpointLineStyleInput (series string) : Style of the HTF FVG midline.
htfMidpointColorInput (series color) : Color of the HTF FVG midline.
shouldShowHtfMitigationLine (series bool) : Whether to show the mitigation line for HTF FVGs.
(Line always extends if shown)
htfMitLineWidthInput (series int) : Width of the HTF FVG mitigation line.
htfMitigationLineStyleInput (series string) : Style of the HTF FVG mitigation line.
htfMitigationLineColorInput (series color) : Color of the HTF FVG mitigation line.
shouldShowHtfMitLineLabels (series bool) : Whether to show labels on HTF FVG mitigation lines.
htfMitLineLabelOffsetX (series float) : The horizontal offset value for the HTF mitigation line's label.
shouldKeepHtfMitigatedLines (series bool) : Whether to keep showing mitigation lines of fully mitigated HTF FVGs.
htfMitigatedMitLineColor (series color) : Color for kept mitigation lines of mitigated HTF FVGs.
htfTfString (series string) : Display string for the HTF (e.g., "HTF").
Udt
TUF_LOGICThe TUF_LOGIC library incorporates three-valued logic (also known as trilean logic) into Pine Script, enabling the representation of states beyond the binary True and False to include an 'Uncertain' state. This addition is particularly apt for financial market contexts where information may not always be black or white, accommodating scenarios of partial or ambiguous data.
Key Features:
Trilean Data Type: Defines a tri type, facilitating the representation of True (1), Uncertain (0), and False (-1) states, thus accommodating a more nuanced approach to logical evaluation.
Validation and Conversion: Includes methods like validate, to ensure trilean variables conform to expected states, and to_bool, for converting trilean to boolean values, enhancing interoperability with binary logic systems.
Core Logical Operations: Extends traditional logical operators (AND, OR, NOT, XOR, EQUALITY) to work within the trilean domain, enabling complex conditionals that reflect real-world uncertainties.
Specialized Logical Operations:
Implication Operators: Features IMP_K (Kleene's), IMP_L (Łukasiewicz's), and IMP_RM3, offering varied approaches to logical implication within the trilean framework.
Possibility, Necessity, and Contingency Operators: Implements MA ("it is possible that..."), LA ("it is necessary that..."), and IA ("it is unknown/contingent that..."), derived from Tarski-Łukasiewicz's modal logic attempts, enriching the library with modal logic capabilities.
Unanimity Functions: The UNANIMOUS operator assesses complete agreement among trilean values, useful for scenarios requiring consensus or uniformity across multiple indicators or conditions.
This library is developed to support scenarios in financial trading and analysis where decisions might hinge on more than binary outcomes. By incorporating modal logic aspects and providing a framework for handling uncertainty through the MA, LA, and IA operations, TUF_LOGIC bridges the gap between classical binary logic and the realities of uncertain information, making it a valuable tool for developing sophisticated trading strategies and analytical models.
Library "TUF_LOGIC"
3VL Implementation (TUF stands for True, Uncertain, False.)
method validate(self)
Ensures a valid trilean variable. This works by clamping the variable to the range associated with the trilean type.
Namespace types: tri
Parameters:
self (tri)
Returns: Validated trilean object.
method to_bool(self)
Converts a trilean object into a boolean object. True -> True, Uncertain -> na, False -> False.
Namespace types: tri
Parameters:
self (tri)
Returns: A boolean variable.
method NOT(self)
Negates the trilean object. True -> False, Uncertain -> Uncertain, False -> True
Namespace types: tri
Parameters:
self (tri)
Returns: Negated trilean object.
method AND(self, comparator)
Logical AND operation for trilean objects.
Namespace types: tri
Parameters:
self (tri) : The first trilean object.
comparator (tri) : The second trilean object to compare with.
Returns: `tri` Result of the AND operation as a trilean object.
method OR(self, comparator)
Logical OR operation for trilean objects.
Namespace types: tri
Parameters:
self (tri) : The first trilean object.
comparator (tri) : The second trilean object to compare with.
Returns: `tri` Result of the OR operation as a trilean object.
method EQUALITY(self, comparator)
Logical EQUALITY operation for trilean objects.
Namespace types: tri
Parameters:
self (tri) : The first trilean object.
comparator (tri) : The second trilean object to compare with.
Returns: `tri` Result of the EQUALITY operation as a trilean object, True if both are equal, False otherwise.
method XOR(self, comparator)
Logical XOR (Exclusive OR) operation for trilean objects.
Namespace types: tri
Parameters:
self (tri) : The first trilean object.
comparator (tri) : The second trilean object to compare with.
Returns: `tri` Result of the XOR operation as a trilean object.
method IMP_K(self, comparator)
Material implication using Kleene's logic for trilean objects.
Namespace types: tri
Parameters:
self (tri) : The antecedent trilean object.
comparator (tri) : The consequent trilean object.
Returns: `tri` Result of the implication operation as a trilean object.
method IMP_L(self, comparator)
Logical implication using Łukasiewicz's logic for trilean objects.
Namespace types: tri
Parameters:
self (tri) : The antecedent trilean object.
comparator (tri) : The consequent trilean object.
Returns: `tri` Result of the implication operation as a trilean object.
method IMP_RM3(self, comparator)
Logical implication using RM3 logic for trilean objects.
Namespace types: tri
Parameters:
self (tri) : The antecedent trilean object.
comparator (tri) : The consequent trilean object.
Returns: `tri` Result of the RM3 implication as a trilean object.
method MA(self)
Evaluates to True if the trilean object is either True or Uncertain, False otherwise.
Namespace types: tri
Parameters:
self (tri) : The trilean object to evaluate.
Returns: `tri` Result of the operation as a trilean object.
method LA(self)
Evaluates to True if the trilean object is True, False otherwise.
Namespace types: tri
Parameters:
self (tri) : The trilean object to evaluate.
Returns: `tri` Result of the operation as a trilean object.
method IA(self)
Evaluates to True if the trilean object is Uncertain, False otherwise.
Namespace types: tri
Parameters:
self (tri) : The trilean object to evaluate.
Returns: `tri` Result of the operation as a trilean object.
UNANIMOUS(self, comparator)
Evaluates the unanimity between two trilean values.
Parameters:
self (tri) : The first trilean value.
comparator (tri) : The second trilean value.
Returns: `tri` Returns True if both values are True, False if both are False, and Uncertain otherwise.
method UNANIMOUS(self)
Evaluates the unanimity among an array of trilean values.
Namespace types: array
Parameters:
self (array) : The array of trilean values.
Returns: `tri` Returns True if all values are True, False if all are False, and Uncertain otherwise.
tri
Three Value Logic (T.U.F.), or trilean. Can be True (1), Uncertain (0), or False (-1).
Fields:
v (series int) : Value of the trilean variable. Can be True (1), Uncertain (0), or False (-1).
Motion▮ FEATURES
Now as library version :)
String-based transition-effects
Performance optimization. Reduced memory consumption up to >90% by kicking the output to the "stdout".
Use marquee- or loader-effect on any possible string location.
Example: UI Price-Ticker
----------------------------------------------------------------------------
Library "Motion"
_getStringMono(_len, _str, _sep)
Parameters:
_len
_str
_sep
marquee(this, _extern, _ws, _subLen, _subStart)
Parameters:
this
_extern
_ws
_subLen
_subStart
transition(this, _subLen, _subStart)
Parameters:
this
_subLen
_subStart
hold(this)
Parameters:
this
keyframe
keyframe A keyframe object.
Fields:
seq
intv
step
length
update_no
frame_no
ltr
hold
WelcomeUDT█ OVERVIEW
This is a simplest example of user-defined types (UDT) or objects , which simplify as alternative to hello world.
█ CREDITS
Tradingview
█ USAGE
These are the types used during initializations, commonly variables.
export type Settings
int bar
float price
string phrase
...
Example of library function to print out label.
export printLabel(Settings setup) =>
if setup.variable
var label lab = na
label.delete(lab)
lab := label.new(setup.bar, setup.price, setup.phrase, color = setup.bg)
else
label.new(setup.bar, setup.price, setup.phrase, color = setup.bg)
Usage of types
Settings setup = Settings.new(bar_index , priceInput, phraseInput, colorInput, variableInput)
Alternative way to write types
Settings setup = Settings.new(
bar = bar_index ,
price = priceInput,
phrase = phraseInput,
variable = variableInput)
Usage of types into custom function / library function.
printLabel(setup)
printLabel(Settings)
Print out label
Parameters:
Settings : types
Returns: Label object
Settings
Initialize type values
Fields:
bar : X position for label
price : Y position for label
phrase : Text for label
bg : Color for label
variable : Boolean for enable new line and delete line
